Skip to main content
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

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:
--tool all configures every supported agent at once. Add --install --yes to install the missing ones too.
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).
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).

​
Commands

​
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:

​
Flags

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

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