substrate-setup 0.5.0

One-shot local configurator for coding agents against a Substrate gateway

substrate-setup

One-shot configurator that points local coding agents at a Substrate gateway.

Install

substrate-setup runs on Python 3.8 or newer — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain pip works:

pip install substrate-setup

If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use uv or pipx:

# Option A — uv (also downloads a Python for the tool if needed)
uv tool install substrate-setup

# Option B — pipx
pipx install substrate-setup

Don't have uv? Install it once with:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or on Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Use

substrate-setup configure          # detect installed agents and wire them up
substrate-setup verify             # read-only: confirm everything points at the gateway
substrate-setup remove             # strip the substrate-managed entries
substrate-setup --help

After running configure

substrate-setup configure writes the API key for you automatically. On Windows it lands in HKCU\Environment\SUBSTRATE_API_KEY (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish depending on $SHELL) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.

You should not need to set SUBSTRATE_API_KEY by hand. If auto-persistence fails (the printed message will say API key WARNING: …), you can set it manually:

• Windows: [Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User") then re-launch the agent.
• macOS / Linux: add export SUBSTRATE_API_KEY=<your-key> to your shell rc and source it.

Supported agents: hermes, cursor, aider, continue, claude-code, codex.

Subset with --agents-only hermes,aider. Preview without writing: --dry-run. Override the gateway base URL: --base-url https://your-gateway.example.com.

Per-agent catalog UX (0.3.0+)

Agent	How it learns about Substrate's models
hermes	Live URL fetch via model_catalog.providers.substrate.url. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL.
cursor	Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models.
aider	~/.aider.model.metadata.json written with one entry per chat-capable Substrate model. Use --model openai/<id> to switch.
continue	All chat-capable Substrate models written as separate models: entries in ~/.continue/config.yaml.
claude-code	~/.claude/settings.json env block (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL). The /model picker stays opus/sonnet/haiku — use claude --model openai/<id> for any other Substrate model. Requires Substrate's /v1/messages endpoint — shipped in gateway Phase 1.
codex	~/.codex/config.toml [model_providers.substrate] block with wire_api = "responses". API key is auto-persisted (see above). Requires Substrate's /v1/responses endpoint — shipped in gateway Phase 2.

Coexisting with account switchers (cc-switch, cockpit) — 0.5.0+

If you use an account-switcher like cc-switch or cockpit, it already owns ~/.claude/settings.json and/or ~/.codex/config.toml — it rewrites the ANTHROPIC_* env block / [model_providers.*] on every switch. substrate-setup and the switcher can't both own the same keys, so configure detects the switcher and leaves those files untouched, printing guidance instead of fighting it. (hermes, cursor, aider, continue are unaffected — they use their own files.)

Recommended: add Substrate as a provider inside your switcher, then switch to it when you want the gateway:

• Claude Code — ANTHROPIC_BASE_URL = https://substrate-solutions-api.fly.dev (no /v1), ANTHROPIC_AUTH_TOKEN = <your sk-substrate-… key>
• Codex — base_url = https://substrate-solutions-api.fly.dev/v1, wire_api = "responses", key = your sk-substrate-…

Alternatives:

• One-off Claude Code session: export ANTHROPIC_BASE_URL=… ANTHROPIC_AUTH_TOKEN=… before claude — shell env overrides the switcher's settings file, touches nothing.
• Let substrate-setup own the file anyway: re-run with --force (it backs up the file first). Note your switcher will then overwrite it on its next switch.

Heads-up: tool calling on Gemini 3.1 Pro Preview

If your CLI agent (Hermes, Aider, etc.) uses tool calling against google/gemini-3.1-pro-preview, expect occasional misses (~20-30% of attempts). All other Substrate models hit ≥95% reliability for tool calls.

Troubleshooting

Windows: Defender SmartScreen prompts on every Codex click

Codex Desktop spawns helper binaries (codex-command-runner.exe, node_repl.exe) per UI action. With sandbox = "elevated" in ~/.codex/config.toml, each spawn triggers Windows Defender SmartScreen, prompting you on every click until the Codex install directory is whitelisted.

One-time fix — open an Administrator PowerShell window and run:

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"

This excludes Codex's binaries from real-time scanning. Reverse with Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex".

substrate-setup configure --agents-only codex also prints this command at the end of its walkthrough on Windows.