substrate-setup 0.3.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 requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:

# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
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"

Why not pip install substrate-setup? It works only if the pip on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default pip (Python 3.9) is the common pitfall — PyPI hides every release from it with Requires-Python >=3.12 and the error message is unhelpful. uv and pipx both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.

Use

export SUBSTRATE_API_KEY="sk-substrate-..."   # or be prompted

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

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. Note: requires Substrate's /v1/messages endpoint, which is gated behind a Fly feature flag — until it's flipped, requests return 404.
codex	~/.codex/config.toml [model_providers.substrate] block with wire_api = "responses". Set SUBSTRATE_API_KEY in your shell rc. Note: requires Substrate's /v1/responses endpoint (gateway protocol adapters Phase 2 — not yet started).