Quick start (local)

Updated Aug 13, 2026View as Markdown

Run an agent on your machine. One file, two commands, no account.

1. Install the CLI

npm install -g @substructure.ai/cli

The CLI is the engine too. Nothing below signs in or leaves this machine.

2. Describe the agent

Write substructure.toml in your project root.

substructure.toml
name = "oncall-bot"

[llm.openrouter]
type = "openrouter"

[agent.oncall]
llm = "openrouter"
model = "anthropic/claude-sonnet-4-5"
system = "You are the on-call assistant."

[run]
agent = "oncall"
output = "pretty"

[llm.openrouter] says which provider to call. [agent.oncall] says who calls it. The file names no [remote], so every command acts here. [run] gives subs run its defaults so you stop repeating flags.

3. Give it a key

export OPENROUTER_API_KEY=sk-or-...

The engine takes the key from your environment. The file holds no keys — it names variables at most, with api_key_env.

4. Talk to it

subs run "what is broken?"

The reply streams to your terminal. output = "pretty" shows the turn as text; the default, ag-ui, streams protocol events.

5. Continue the session

After every run the CLI prints the command to continue it.

continue this session with:
  subs run --agent oncall --session <session-id> '...'
subs run --session <session-id> "what did I just ask?"

The agent remembers. The engine saves the whole session in substructure.db beside the file, so you can stop everything and pick the session up tomorrow.

subs sessions list
subs sessions events <session-id> -o pretty

What you have

An agent that runs on this machine, on your key, against a SQLite file you can delete. The engine calls the model, saves every step, and replays it on demand. You wrote one file and no code.

subs serve --no-auth runs the same engine as an HTTP server, with the REST and AG-UI endpoints a frontend needs.

Run subs doctor at any time to see what the project still needs.

Next

Add one thing at a time.