# Substructure subs, the cloud native agent harness.. 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 can run locally or as a client and server. ## Slack bots in minutes Install the CLI, write one file, and apply it. ```sh npm i -g @substructure.ai/cli subs login ``` ```toml name = "example" [llm.openrouter] type = "openrouter" [agent.oncall] llm = "openrouter" model = "anthropic/claude-sonnet-4-5" system = "You are the on-call assistant." [agent.oncall.slack] name = "On-call" ``` ```sh subs apply # create the project from the file subs auth llm.openrouter # add your LLM key subs auth agent.oncall.slack # set up its Slack app ``` Invite the bot to a channel and mention it, and it answers in the thread. The thread is the session. Each agent gets its own Slack app. `subs.toml` is the whole project. It names the agents, their models, their tools, and where they answer. The file holds no keys. ## Give your agents MCP servers Add an MCP server and give it to an agent. ```toml [mcp.sentry] url = "https://mcp.sentry.dev/mcp" [agent.oncall] mcp = ["sentry"] ``` ```sh subs auth mcp.sentry ``` The engine handles the auth, fetches the tools the connection offers, and runs every call. Your code never holds a token. ## Control the agent loop with webhooks Point an agent at a URL and the engine sends every decision for that agent there. ```toml [worker.main] url = "https://example.com/agent" [agent.oncall] worker = "main" ``` The engine proposes each step. Return the proposal to accept it. Change the steps you care about: run a tool in your own system, rewrite a prompt, swap the model, or pause for a person. You do not need an SDK. The engine POSTs JSON and reads JSON back. Any language that serves HTTP can answer. One project holds both kinds of agent. The agents without a `worker` stay with the engine. ## Bring your own LLM Bring your own key and the engine makes the calls for you. ```sh subs auth llm.openrouter ``` If you would rather the engine never see your key, make the calls in your worker instead. Nothing else changes. ## Develop locally, or host it yourself Iterate before you go live. Slack, MCP auth, and your worker all work locally. ```sh subs serve -c subs.dev.toml subs run oncall "what is broken?" ``` The engine is on GitHub and is built to be self-hosted. A self-hosted engine serves the same APIs, and the same file describes both. ## What agents can do - **Slack.** DM an agent or mention it. Route different agents to different channels. - **MCP connectors.** The engine authorizes the connection and runs every tool call. - **Your own tools.** Build tools in your worker and control how agents reach your system. - **Subagents.** An agent delegates to child agents, each with its own session and tools. - **Interrupts.** A run pauses on a person or an outside event and holds nothing while it waits. Slack supports human-in-the-loop approval. - **Conversations.** History, editing, regeneration, and branching belong to the engine. - **AG-UI.** The engine emits AG-UI events, so assistant-ui, CopilotKit, and other clients drive the same agents that answer in Slack. - **Durability.** Every step is saved before it runs, so a crash or a redeploy resumes where it stopped. ## The three parts | Part | What it is | | --- | --- | | Engine | Runs the agent loop. It calls the model, runs tools, saves every step, and streams events. It is the cloud, or the `subs` binary. | | Worker | Your code. It is an HTTP endpoint that answers a decision request. It is optional. | | Client | Anything that sends messages and reads events. Slack, a browser, your backend, or the CLI. | The hosted dashboard is https://app.substructure.ai and the API is https://api.substructure.ai. You manage a project with `subs`. There is no dashboard step you cannot do from the terminal. `subs login` authenticates in your browser. `subs apply` creates the project and writes its id back into the file. Run `subs doctor` to see what a project still needs. ## Docs Every page below is available as raw markdown at the linked URL. - [Quick start (cloud)](https://substructure.ai/llms.txt/docs/quick-start.md) - [Quick start (local)](https://substructure.ai/llms.txt/docs/quick-start-local.md) - [How it works](https://substructure.ai/llms.txt/docs/how-it-works.md) - [Agents](https://substructure.ai/llms.txt/docs/agents.md) - [Connectors](https://substructure.ai/llms.txt/docs/connectors.md) - [Plugins](https://substructure.ai/llms.txt/docs/plugins.md) - [Workers](https://substructure.ai/llms.txt/docs/workers.md) - [Events URL](https://substructure.ai/llms.txt/docs/events-url.md) - [Tool calls](https://substructure.ai/llms.txt/docs/tools.md) - [Deferred tools](https://substructure.ai/llms.txt/docs/deferred-tools.md) - [LLMs](https://substructure.ai/llms.txt/docs/llms.md) - [Subagents](https://substructure.ai/llms.txt/docs/subagents.md) - [Agent state](https://substructure.ai/llms.txt/docs/state.md) - [Interrupts](https://substructure.ai/llms.txt/docs/interrupts.md) - [Async tools](https://substructure.ai/llms.txt/docs/async-tools.md) - [Conversations](https://substructure.ai/llms.txt/docs/conversations.md) - [Slack](https://substructure.ai/llms.txt/docs/slack.md) - [Chat](https://substructure.ai/llms.txt/docs/chat.md) - [AG-UI](https://substructure.ai/llms.txt/docs/ag-ui.md) - [Client-side tools](https://substructure.ai/llms.txt/docs/client-tools.md) - [Local development](https://substructure.ai/llms.txt/docs/local-development.md) - [Cloud](https://substructure.ai/llms.txt/docs/cloud.md) - [Self-hosting](https://substructure.ai/llms.txt/docs/self-hosting.md) - [Authentication](https://substructure.ai/llms.txt/docs/auth.md) - [Durability](https://substructure.ai/llms.txt/docs/durability.md) - [Retries and timeouts](https://substructure.ai/llms.txt/docs/retries.md) - [Config](https://substructure.ai/llms.txt/docs/config.md) - [Protocol](https://substructure.ai/llms.txt/docs/protocol.md) - [Events](https://substructure.ai/llms.txt/docs/events.md) - [REST API](https://substructure.ai/llms.txt/docs/api.md) - [CLI](https://substructure.ai/llms.txt/docs/cli.md) - [Typed bindings](https://substructure.ai/llms.txt/docs/typed-bindings.md) ## Guides Setup walkthroughs, each one config file and three commands. Available as raw markdown at the linked URL. - [Build a Slack bot on an open model](https://substructure.ai/llms.txt/guides/slack-bot-open-models.md) - [Build a Slack bot on Hetzner inference](https://substructure.ai/llms.txt/guides/slack-bot-hetzner-inference.md) - [Connect a Slack bot to GitHub](https://substructure.ai/llms.txt/guides/slack-bot-with-github.md) - [Connect a Slack bot to Linear](https://substructure.ai/llms.txt/guides/slack-bot-with-linear.md) - [Connect a Slack bot to Notion](https://substructure.ai/llms.txt/guides/slack-bot-with-notion.md) - [Connect a Slack bot to Sentry](https://substructure.ai/llms.txt/guides/slack-bot-with-sentry.md) - [Connect a Slack bot to Stripe](https://substructure.ai/llms.txt/guides/slack-bot-with-stripe.md) ## Comparisons How Substructure relates to other agent infrastructure. Available as raw markdown at the linked URL. - [Substructure vs. DeepSeek Harness](https://substructure.ai/llms.txt/compare/deepseek-harness.md) - [Substructure vs. CrewAI for AI agents](https://substructure.ai/llms.txt/compare/crewai.md) - [Substructure vs. Inngest for AI agents](https://substructure.ai/llms.txt/compare/inngest.md) - [Substructure vs. LangGraph for AI agents](https://substructure.ai/llms.txt/compare/langgraph.md) - [Substructure vs. Mastra for AI agents](https://substructure.ai/llms.txt/compare/mastra.md) - [Substructure vs. n8n for AI agents](https://substructure.ai/llms.txt/compare/n8n.md) - [Substructure vs. the OpenAI Agents SDK](https://substructure.ai/llms.txt/compare/openai-agents-sdk.md) - [Substructure vs. Temporal for AI agents](https://substructure.ai/llms.txt/compare/temporal.md) ## Packages - [@substructure.ai/cli](https://www.npmjs.com/package/@substructure.ai/cli): `subs`. Runs agents on your machine and administers a deployment. ## Optional - [Pricing](https://substructure.ai/pricing): One flat price each month. What a turn is, and what each plan includes. - [mcpd](https://substructure.ai/mcpd): Serve a machine's commands as an MCP server, so the agent loop can run elsewhere. - [GitHub repository](https://github.com/substructureai/subs): Source for the engine and the CLI. - [Sitemap](https://substructure.ai/sitemap.xml): Full URL index for the site.