> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/llms.txt
> Use this file to discover all available pages before exploring further.

# One command to wire up your agents.

> npx sideren is the setup helper: it points the coding agents you already use at Sideren. Pick your agents, install what's missing, choose models from the live catalog, paste your key, verify. It deep-merges into your existing files, keeps timestamped backups, and is safe to re-run.

`npx sideren` is Sideren's setup helper. It points the coding agents you already use, such as
Claude Code, Codex and opencode, at Sideren. Nothing to install: `npx` fetches it.

## Quickstart

```sh theme={null}
npx sideren
```

That is the whole thing. The wizard finds the agents on your machine, asks for your key,
picks models from the live catalog, writes the configs, and finishes with a live check —
one real request through each agent it configured.

Or do it in one non-interactive line — handy for scripts and dotfiles:

```sh theme={null}
npx sideren setup --key sdn_your_key --tool claude-code,codex --model glm-5.3
```

`--tool all` configures every supported agent at once. Add `--install --yes` to install
the missing ones too.

<Note>
  The setup helper is zero-dependency, needs Node 18+, and never sends your key anywhere
  except into your own local config files. Point it at a different gateway with `--url` (default
  is `https://api.sideren.io`).
</Note>

<Note>
  Set up with an older version of the helper? Your existing key, model ids and environment
  variables keep working. Re-run `npx sideren setup` to update those configs: older entries
  are replaced, not duplicated, and model ids are rewritten to their plain form
  (`glm-5.3`).
</Note>

## Commands

| Command | What it does |
| - | - |
| `npx sideren` · `npx sideren init` | The interactive wizard: agents → install → models → key → live check. |
| `npx sideren setup --key <k> [--tool <ids>]` | Configure one or more agents non-interactively. |
| `npx sideren install <ids>` | Just install the agents, skipping anything already present. |
| `npx sideren status` | Which agents are installed, and which are pointed at Sideren. |
| `npx sideren doctor` | Environment, per-agent install paths, catalog source, and a live check per agent. |
| `npx sideren models` | List the model catalog. |
| `npx sideren test [--key <k>]` | Send one real request and print the reply. Without `--key` it reuses `SIDEREN_API_KEY`, the Codex bearer token, or the key already written to Claude Code's settings. |
| `npx sideren unset` | Remove the config the helper added (previous files are kept as timestamped backups). |
| `npx sideren help all` | Every command, agent and flag. |
| `npx sideren --version` | Print the helper's version. |

## The model catalog is dynamic

Model ids are not compiled into the helper. Each run resolves the catalog **live** from
`GET /v1/models`, caches it at `~/.sideren/catalog.json` for six hours, and falls back to a
bundled snapshot only when there is no network. A model added to Sideren therefore appears
in the picker, and in Codex's declared context window, with no new release of the helper.

Use `--refresh-catalog` to bypass the cache, or `--offline` to never touch the network.

## Models and slots

* `--model <id>` — the main model. The default is `auto`: the gateway picks per request.
  Setup also writes one or two stronger models and a lighter one into each agent's other
  slots, chosen from the live model list for your plan.
* `--stronger <ids>` / `--lighter <ids>` — name those yourself (or `none`).
* `--small-model <id>` — the background / fast model, where an agent has a separate slot.
* `--effort <level>` — the default thinking level: `low` | `medium` | `high` | `xhigh` |
  `max` (default `high`). A level you already set in an agent is kept as it is.
* `--fallback <ids>` — more models to register in each agent's model picker.

## Supported agents

`--tool` accepts (comma-separated, or `all`): `claude-code`, `codex`, `opencode`,
`hermes`, `pi`, `senpi`, `omp`, `zcode`, `aider`, `crush`, `goose`, `qwen`, `droid`,
`openclaw`, `continue`, `kilo`, `cline`, `zed`, `cursor`,
`roo`, `windsurf`, `cursor-cli`, `antigravity` (alias `agy`), `kiro`, `gemini-cli`.

What the helper does per agent:

| Agent | What setup writes |
| - | - |
| **Claude Code** | The `env` block in `~/.claude/settings.json` — base URL, auth token, model slots. See [Claude Code](/guides/claude-code). |
| **Codex CLI** | `~/.codex/config.toml` (top-level keys + `model_catalog_json` + a provider table with `experimental_bearer_token`) and `~/.codex/model-catalogs/sideren.json`. See [Codex CLI](/guides/codex). |
| **opencode** | A Sideren provider in `~/.config/opencode/opencode.json` (or the highest-precedence file that exists). See [opencode](/guides/agents/opencode). |
| **Hermes Agent** | `~/.hermes/config.yaml` (`providers.sideren`, `model.provider: custom:sideren`) and `~/.hermes/.env` (`SIDEREN_API_KEY`). See [Hermes Agent](/guides/agents/hermes-agent). |
| **Aider / Continue / Crush / Goose / Qwen Code / Droid / OpenClaw / Zed / Kilo Code / Cline / pi / senpi / omp / ZCode** | Each agent's own config file, on its OpenAI-compatible or Responses route. Per-agent detail on the [agent pages](/guides/other-tools). |
| **Cursor / Roo Code / Cline GUI** | GUI-only — prints the steps: paste the key, override the base URL, add model ids. |
| **Cursor CLI / Antigravity / Kiro / Gemini CLI** | Print-only — no custom-endpoint hook to write. Cursor CLI is Cursor Cloud only; Antigravity and Gemini CLI speak non-OpenAI protocols; Kiro serves its own catalog. |
| **Windsurf** | No custom endpoint — prints that and what to use instead. |

## Flags

| Flag | Default |
| - | - |
| `--key <k>` | — ; read from `SIDEREN_API_KEY` or an earlier setup when omitted |
| `--tool <ids>` | the agents found on this machine |
| `--url <u>` / `--base <u>` | `https://api.sideren.io` (`--base` also accepts a `/v1` base) |
| `--model` / `--stronger` / `--lighter` / `--small-model` / `--effort` / `--fallback` | see [Models and slots](#models-and-slots) |
| `--install` / `--no-install` | Also install any selected agent that is missing / never install anything. |
| `--yes`, `-y` | Ask nothing: auto model, the agents found, run vendor install scripts. |
| `--verbose`, `-v` | Show every note each agent's setup produced. |
| `--print` | Print the configs instead of writing files. |
| `--offline` | Never touch the network: cached or bundled catalog, no live check. |
| `--no-verify` / `--verify-timeout <s>` | Skip the live check / its deadline (default 60s). |
| `--refresh-catalog` | Ignore the cached catalog and re-fetch `/v1/models`. |
| `--persist-key` / `--no-persist-key` | Also save `SIDEREN_API_KEY` for shells and scripts / never touch your env or shell profile. Codex does not need the env var. |
| `--payment-mode <subscription\|payg>` | Stamp PAYG mode (`x-sideren-payment-mode: payg`) into the agents that carry headers (Claude Code, Codex, Hermes, opencode), so they spend purchased credit. See [Pay as you go](/plans#pay-as-you-go). |
| `--wire <w>` | `test` with nothing configured: `chat` · `responses` · `anthropic`. |
| `--home <dir>` | Write configs under `<dir>` instead of your home directory (sandboxes, tests). Also `SIDEREN_HOME`. |
| `--claude-execution-policy <strict\|off>` | Install / remove bounded Claude Code Bash safeguards. |
| `--ascii` | Plain-ASCII output (also `SIDEREN_ASCII=1`). |

A few further flags (`--exact`, `--tool-guard`, `--no-allow-effort-mapping`) stamp optional
request headers into the agents that support them — `npx sideren help all` lists them.

## Installing the agents

The helper detects each agent by executable on `PATH` first, then by its config or extension
directory, and reports which signal it used. Already installed means skipped.

Where a vendor only ships a `curl … | bash` installer, that **downloads and executes a
remote script**. The helper labels it as such, prints the exact command, and runs nothing
until you agree (or pass `--yes`). Desktop apps (Cursor, Windsurf, Zed) are never fetched:
the helper prints the download link. `npx sideren doctor` lists the install command it would
use for each agent on your platform.

## Safe by design

* **Deep-merge** — it merges into your existing config; it never overwrites a whole file.
* **Managed blocks** — additions are fenced with
  `# >>> sideren … >>>` markers, so they are easy to find and `unset` removes only what
  the helper added. Blocks an older version wrote are replaced in place, not duplicated.
* **Backups** — every change writes a timestamped `<file>.sideren.bak-<timestamp>` copy
  first.
* **Idempotent** — re-running updates in place instead of duplicating, and it will not
  clobber a model you already set (it prints the value instead).

## Your key for Codex

Codex gets the key from `experimental_bearer_token` in `~/.codex/config.toml`. Setup does
not require `SIDEREN_API_KEY` in the environment (Codex Desktop never sees User env vars).
`--persist-key` still writes that variable for shells and scripts if you want it.

## Verify it worked

```sh theme={null}
npx sideren test
```

A successful run prints a model reply served from `https://api.sideren.io`. If it fails,
check `npx sideren status` and your key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.