substrate-setup 0.4.1

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.

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.