subs

# subs [substructure.ai](https://substructure.ai) > Pre-1.0: APIs and the wire protocol can change between releases. `subs` is an agent harness for the cloud. It runs an unprivileged agent loop with no system access. It uses MCP servers for tools. It runs locally or as a client and a server. Declare your agents in a config file. To customize the loop, point an agent at an HTTP endpoint and answer a webhook. `subs` handles durability, retries, timeouts, MCP connection management, session state, session branching, AG-UI, Slack connection, LLM calls, subagents, interrupts and more. To turn a sandbox into an MCP server, see [mcpd](https://github.com/substructureai/mcpd). # Get started ## Install the CLI ```sh curl -fsSL https://subs.dev/cli.sh | bash ``` The CLI is also the engine. ## Run an agent on your machine Create a `subs.toml`. ```toml title="subs.toml" name = "example" [llm.openrouter] type = "openrouter" [agent.teammate] llm = "openrouter" model = "deepseek/deepseek-v4-flash-0731" system = "You are a helpful teammate." ``` Set your provider key and talk to the agent. ```sh export OPENROUTER_API_KEY=sk-or-... subs chat teammate -c subs.toml ``` ## Run the engine as a server Add a `[serve]` section and a `[remote]` that points at it. ```toml title="subs.toml" [serve] port = 9999 auth = false [remote] url = "http://localhost:9999" ``` Start the server. ```sh subs serve -c subs.toml ``` In another terminal, the same chat command now talks to it. ```sh subs chat teammate -c subs.toml ``` ## Run the agent on substructure.ai Point `[remote]` at the hosted engine instead of your own. ```toml title="subs.toml" [remote] url = "https://api.substructure.ai" ``` Create the project from the file, then upload your LLM key. ```sh subs apply subs auth llm.openrouter ``` The same chat command now runs the turn on the hosted engine. ```sh subs chat teammate -c subs.toml ``` ## Put the agent in Slack Say which agent takes a DM and which one answers a mention. ```toml title="subs.toml" [slack] dm = "teammate" mentions = "teammate" ``` Apply the file again, then connect your workspace. ```sh subs apply subs slack connect ``` Mention the bot in a channel and it answers in the thread. ## Connect the agent to an MCP server Declare the server and give it to an agent. Every user of the agent shares one credential. ```toml title="subs.toml" [mcp.sentry] url = "https://mcp.sentry.dev/mcp" [agent.teammate] llm = "openrouter" model = "deepseek/deepseek-v4-flash-0731" system = "You are a helpful teammate." mcp = ["mcp.sentry"] ``` Authorize the connection. ```sh subs auth mcp.sentry ``` ## Give each user their own MCP connection Set `credential = "user"` and each user connects their own account. A user-scoped connection works only in a one-on-one chat between the agent and that user. ```toml title="subs.toml" [mcp.linear] url = "https://mcp.linear.app/mcp" credential = "user" [agent.personal] llm = "openrouter" model = "deepseek/deepseek-v4-flash-0731" system = "Help me with my Linear issues." mcp = ["mcp.linear"] [slack] dm = "personal" mentions = "teammate" ``` ## Control the agent loop with a webhook Point an agent at a URL and the engine sends every decision for that agent to your code. This gives you full control of the loop, including how the agent behaves in Slack. ```toml title="subs.toml" [agent.teammate] llm = "openrouter" model = "deepseek/deepseek-v4-flash-0731" system = "You are a helpful teammate." mcp = ["mcp.sentry"] worker = "https://example.com/agent" ``` Your endpoint reads the engine's proposal and returns it, changing only the steps you care about. There is no SDK to install. ```typescript title="server.ts" import { serve } from "@hono/node-server"; import { Hono } from "hono"; import type { DecisionRequest, DecisionResponse } from "./protocol.ts"; function decide({ trigger, proposed }: DecisionRequest): DecisionResponse { if (trigger.type === "session.start") { return { agent: { ...proposed.agent, tools: [{ name: "current_time", description: "Get the current time" }] } }; } // Run our tool when the model calls it. if (trigger.type === "tool.execute" && trigger.name === "current_time") { return { actions: [{ type: "tool.result", result: new Date().toISOString() }] }; } // Accept the engine's proposal for everything else. return proposed; } const app = new Hono(); app.post("/", async (c) => c.json(decide(await c.req.json()))); serve({ fetch: app.fetch, port: 4444 }); ``` Only the agents that name a worker use one. The rest stay with the engine, in the same project and the same file. Full walkthrough in the [quick start](./docs/10-quick-start.md). Docs: [Workers](./docs/50-workers.md), [Connectors](./docs/40-connectors.md), [Slack](./docs/130-slack.md), [Local development](./docs/160-local-development.md) ## Features ### Slack Mention the bot or DM it. The thread is the session. Route different channels to different agents. Docs: [Slack](./docs/130-slack.md) ### Terminal chat `subs chat` holds one session open, streams the reply as it is written, and turns an approval prompt into a picker. The session is the same kind a Slack thread is. Docs: [Chat](./docs/135-chat.md) Examples: [no-code-chat](./examples/no-code-chat) ### Custom decisions At each step the engine tells your code what it plans to do next. Accept the plan or do something else. A working agent is a few lines. Docs: [How it works](./docs/20-how-it-works.md) Examples: [Node](./examples/node-hono-basic), [Python](./examples/python-fast-api-basic) ### Any language Your agent is an HTTP endpoint. Generate typed bindings from the published JSON schema. Docs: [Typed bindings](./docs/270-typed-bindings.md) Examples: [Go](./examples/go-chat-with-tools), [Python](./examples/python-fast-api-pydantic-chat-with-tools), [TypeScript](./examples/node-hono-typescript-chat-with-tools), [Elixir](./examples/elixir-plug-chat-with-tools) ### MCP connectors Declare an MCP server and the engine handles the authorization, reads the tools it offers, and runs every call. Your code never holds a token. Docs: [Connectors](./docs/40-connectors.md) Examples: [Node](./examples/node-hono-connectors) ### Plugins Point an agent at an [agent-plugins](https://agent-plugins.org) directory and it gets that plugin's skills and MCP servers. Docs: [Plugins](./docs/45-plugins.md) ### Any LLM The engine calls Anthropic, OpenAI, or OpenRouter with your key. Or your worker makes the call and the engine never sees a key. Docs: [LLMs](./docs/70-llms.md) Examples: [Anthropic](./examples/node-hono-anthropic), [OpenAI](./examples/node-hono-openai), [OpenRouter](./examples/node-hono-openrouter) ### Crash recovery Every step is saved before it runs. A run continues from where it stopped. The same message submitted twice runs once. Docs: [Durability](./docs/200-durability.md) ### Human approval An agent can stop and wait for a person to approve, then continue. A waiting agent uses no compute. In Slack this is a button. Docs: [Interrupts](./docs/100-interrupts.md) Examples: [Node](./examples/node-hono-tool-approval), [No code](./examples/no-code-mcp-approval) ### Tools that take hours A tool does not have to answer immediately. Accept the call, do the work on your own schedule, and report the result later. Docs: [Async tools](./docs/110-async-tools.md) ### Chat history, editing, and branching History, editing, regeneration, and branching belong to the engine. A user can edit an earlier message and go a new direction. The original branch stays. Docs: [Conversations](./docs/120-conversations.md) Examples: [Node](./examples/node-hono-plan-mode), [Python](./examples/python-fast-api-plan-mode) ### Existing chat UIs The engine streams AG-UI events, so assistant-ui and CopilotKit connect to it directly. Docs: [AG-UI](./docs/140-ag-ui.md) Examples: [assistant-ui](./examples/node-hono-assistant-ui), [CopilotKit](./examples/node-hono-copilotkit) ### Tools that run in the browser A tool can run in the user's browser instead of on your server. The run waits for the browser, then continues. Docs: [Client-side tools](./docs/150-client-tools.md) Examples: [Node](./examples/node-hono-client-tool) ### Agent state without a database The engine stores your agent's state with the conversation. Your code gets it on every request and writes changes back. Docs: [Agent state](./docs/90-state.md) Examples: [Node](./examples/node-hono-plan-mode), [Python](./examples/python-fast-api-plan-mode) ### Subagents An agent can give work to other agents. Each child runs in its own session. The parent's totals include each child's cost and token use. Docs: [Subagents](./docs/80-subagents.md) Examples: [Node](./examples/node-hono-subagent), [Python](./examples/python-fast-api-subagent) ### Validated tool calls Give a tool an input and output schema. The engine checks every call against it. Docs: [Tool calls](./docs/60-tools.md) Examples: [Node](./examples/node-hono-tools), [Python](./examples/python-fast-api-tools), [Go](./examples/go-chat-with-tools) ### Retries and timeouts Set a policy on any tool or model call. The engine applies it, and keeps applying it after a restart. Docs: [Retries and timeouts](./docs/210-retries.md) ### Self-hosting Run the engine on your own servers and hold every credential. Docs: [Self-hosting](./docs/180-self-hosting.md) ## Parts of the system - **Engine.** Runs the agent loop, in Rust. It calls the model, runs tools, saves each step, retries failures, streams events, and supervises subagents. Use the hosted version at [app.substructure.ai](https://app.substructure.ai), run it from the CLI, or embed it in your process. - **Workers.** Your agent code. It receives a trigger and returns actions. It runs in your codebase with your dependencies. - **Clients.** They send work and stream events back, from your backend or from the browser. Slack and AG-UI are clients. - **CLI.** Set up, deploy, watch, and debug from the terminal. It also runs the engine locally. ## Install ```sh curl -fsSL https://subs.dev/cli.sh | bash ``` The script verifies the release checksum and installs to `~/.local/bin`. Set `SUBS_INSTALL_DIR` to install elsewhere and `SUBS_VERSION` to pin a release. Or install from npm: ```sh npm i -g @substructure.ai/cli ``` ## Docs Full documentation in [`docs/`](./docs). ## License [MIT](./LICENSE)