# contenox > Declare an agent in one Markdown file. Run it in your terminal. Every action it takes is checked against policy you wrote — and when it needs you, it waits, durably: answer from your terminal or your phone, days later, and the run resumes exactly once. A declaration is Markdown with a YAML frontmatter header in `.contenox/agents/`, naming the tools it may call and the model, with a body that becomes its system prompt; a directory of declarations is a workflow, where the `agent.md` at the top reads the request and routes to the branch beneath it. contenox reads the declarations you already keep for Claude Code, Copilot, Cursor, OpenCode and Antigravity, where they are — nothing to move or convert. It compiles each one into the chain that runs it and the policy it runs under, in `.generated/`: both JSON Schema-validated, neither hand-maintained. You bring the tools, and only the ones you need: every tool an agent carries is tokens spent on every turn and one more thing to govern. The client in front of a session provides `fs/*` and `terminal/*` as negotiated capabilities and contenox forwards to them, or you attach MCP servers and OpenAPI services and decide what each may do. Every call crosses that one tool boundary and is checked against your policy before it runs, and a run that stops for a human checkpoints, releases the process, survives a restart, and resumes exactly once when the answer arrives — hours or days later, from anywhere. Open source under Apache-2.0, one binary, no account, on your own machine, on any AI model you pick. Three shapes, partitioned by who is accountable for the machine. `contenox beam` is the front door: the first-party terminal client, a person at their own keyboard, with the filesystem and terminal working natively and gated calls raising an approval card inline — bare `contenox` on a terminal opens it. `contenox run [agent] "task"` is the scripting shape: a program is the caller (CI, cron, another agent), the report goes to stdout, exit 0 on success. `contenox serve` is the organization's shape: a standing host serving one workspace fixed at launch, with no filesystem and no terminal tools at all — every capability is an MCP server — driven by connectors and event triggers through the relay, optionally on Postgres/NATS/Valkey. Editors (Zed, JetBrains, AionUi, OpenClaw) spawn `contenox acp` over stdio, and per that protocol the editor owns the workspace. One instance serves exactly one workspace, fixed at launch; there is no workspace selection anywhere, and clients discover instances and their sessions instead. Terminology, so a summary does not invent one: the policy file bounding a run is the **envelope**; approvals gated by it are **human-in-the-loop**; a paused run that outlives its own process is the **durable ask**; a unit of unattended work is a **mission**. The agents that ship in the box (`acp`, `acpx`, `triage`, `reviewer`, `researcher`) are examples of the artifact, the default page rather than the product. The surfaces are clients, not the product either: `contenox beam` is the first-party one and the front door, editors reach the same runtime over ACP, and the browser app reaches it through the optional relay — none of them owns the policy, which is enforced underneath all of them. ## Start here - [What contenox is](https://contenox.com/docs/guide/what-contenox-is/): the product in one page — what it is, why it exists, what it is typically used for, and what it is not. - [Declaring agents](https://contenox.com/docs/guide/agents/): the artifact — the frontmatter, where declarations live, the directory that becomes a workflow. - [The envelope](https://contenox.com/docs/guide/hitl/): what passes silently, what stops for a human, what is denied outright. - [Quickstart](https://contenox.com/docs/guide/quickstart/): install, connect a model, declare an agent, and start working in `contenox beam`. ## Machine-readable - [HITL policy JSON Schema](https://contenox.com/schema/hitl-policy-v1.schema.json): the envelope format, generated from the Go types that load it. - [Task chain JSON Schema](https://contenox.com/schema/task-chain.schema.json): the compiled chain format, same source. - [Full text](https://contenox.com/llms-full.txt): every documentation page concatenated. - [Sitemap](https://contenox.com/sitemap-index.xml): the complete URL list. ## Guides Declaring agents, the envelope, missions and the durable ask, pairing, sovereignty. - [Declaring agents](https://contenox.com/docs/guide/agents/): An agent is a Markdown file with a YAML frontmatter header. Where declarations live, what the frontmatter says, what the config file supplies that a declaration cannot, and what an agent is allowed to do. - [AGENTS.md](https://contenox.com/docs/guide/agents-md/): Project-level instructions and context that load automatically into every session. - [Why a project needs an AGENTS.md](https://contenox.com/docs/guide/agents-md-why/): An AGENTS.md carries what is true about a repository but not inferable from its code — read-only boundaries, silent tooling contracts, traps already paid for, and where prior art lives — because a wrong assumption in an agent brief executes at scale. - [Chains](https://contenox.com/docs/guide/chains/): The artifact an agent declaration compiles into — writing one by hand, the loop it forms, and how chain files are named and resolved. - [The agentic loop](https://contenox.com/docs/guide/chains/agentic-loop/): The ReAct loop as contenox implements it — an authored task graph you copy and trim, not vendor plumbing you configure. - [Naming, roles, and resolution](https://contenox.com/docs/guide/chains/naming/): The chain--.json convention, what each role means, where each chain is selectable, and exactly what contenox init touches. - [Request routing](https://contenox.com/docs/guide/chains/routing/): One prompt, several specialist loops. The router is where a workflow's expertise is spent — teaching the system what a request means, instead of asking the user to prompt harder. - [Writing a chain by hand](https://contenox.com/docs/guide/chains/writing-a-chain/): Walk from a blank file to a working authored chain in five edits — for the agent that has outgrown a declaration. - [How contenox compares](https://contenox.com/docs/guide/comparison/): What contenox shares with the coding agents, the three things that are structurally different, what those cost, and which tool to pick. - [Core Concepts](https://contenox.com/docs/guide/concepts/): How agents, chains, tasks, tools, transitions, and macros fit together in Contenox. - [Confining agents](https://contenox.com/docs/guide/confinement/): Why an agent is confined, how to scope what it may reach, and the mechanisms that hold the line — the sandbox wall, trusted binaries, and a least-privilege environment. - [Least-privilege shell environment](https://contenox.com/docs/guide/confinement/environment/): The scrub-and-inject design for the shells contenox runs in its own process — give an agent exactly the environment its task needs, not your whole .env. - [Scoping what an agent may do](https://contenox.com/docs/guide/confinement/guardrails/): Six declarations decide what an LLM can reach, touch, spend and act on, and which of those need a human first. Each is a file, each fails closed, and none of them depends on the model behaving. - [The sandbox wall](https://contenox.com/docs/guide/confinement/sandbox/): How the default filesystem/exec/environment fence and the opt-in network wall confine a foreign ACP agent's process. - [Trusted binaries](https://contenox.com/docs/guide/confinement/trusted-binaries/): Pin the allowlisted commands in a HITL policy to a real path and a SHA256, so a name cannot be substituted underneath it. - [Why contenox confines agents](https://contenox.com/docs/guide/confinement/why/): The threat model behind the sandbox — you cannot trust the process of an external ACP agent, so contenox confines it below the agent, kernel-enforced and fail-closed, instead of relying on the agent's or the model's goodwill. - [Events & triggers (beta)](https://contenox.com/docs/guide/events/): The durable local event log, operator-authored trigger files that fire chains from it, and the exact guarantees the dispatcher makes — and does not make. - [HITL Policies](https://contenox.com/docs/guide/hitl/): Control which tool calls require human approval. You write an envelope in agents.toml; the runtime transpiles it into the policy the approval engine evaluates. - [Missions](https://contenox.com/docs/guide/missions/): Fire a one-line intent at a declared agent under an authored envelope, and read the durable record it leaves behind — states, hosts, reports, questions, reclaim, and compute bounds. - [Pairing a machine with a relay](https://contenox.com/docs/guide/pairing/): How pairing attaches a machine to a relay so it can be reached from a phone — what is sent, what is stored, and how to undo it. - [Quickstart](https://contenox.com/docs/guide/quickstart/): Install contenox, connect a model, declare an agent, and start working in the terminal with contenox beam. - [contenox serve: the standing host](https://contenox.com/docs/guide/serve/): The organization's shape — a standing host serving one workspace fixed at launch, with no filesystem and no terminal tools, driven by connectors and event triggers through the relay. - [AI Sovereignty & the EU AI Act](https://contenox.com/docs/guide/sovereignty/): What sovereignty means operationally with contenox — you choose the hosting, state stays in local SQLite, oversight is a policy you authored — and how those controls map to the EU AI Act's oversight and transparency themes. - [Troubleshooting & recovery](https://contenox.com/docs/guide/troubleshooting/): Symptom, cause, and fix for the failures operators actually hit — plus what survives a crash, what resumes it, and how to file a diagnostics bundle. - [Tutorials](https://contenox.com/docs/guide/tutorials/): Four worked paths — a first agent, a mission agent, an agent that files notes into Obsidian, and a recurring job. - [Your first agent](https://contenox.com/docs/guide/tutorials/first-agent/): Declare an agent in one file, watch what contenox puts behind it, and run it. What a permission setting expands into, what a declaration cannot say, and where the knobs are. - [A mission agent](https://contenox.com/docs/guide/tutorials/mission-agent/): Declare an agent in a file, fire it at an intent, and walk away. What makes an unattended agent different from an interactive one, why each difference exists, and what it looks like when you get one wrong. - [A recurring job](https://contenox.com/docs/guide/tutorials/recurring-work/): Build one real repeating job — filing a timesheet — and learn the whole declaration format on the way: what an agent file is, how it brings its own tools, where the approval step lives, and when a procedure should be a skill instead of an agent. - [An agent that files notes into Obsidian](https://contenox.com/docs/guide/tutorials/vault-agent/): Build a working agent from nothing — a folder of raw notes goes in, a tidy Obsidian vault comes out, and the agent physically cannot write anywhere else. Every file explained line by line. - [What contenox is](https://contenox.com/docs/guide/what-contenox-is/): The rules an AI agent runs under are a file you wrote, in your repo, that you can read — and nothing runs that the file does not allow. What contenox is, why it exists, what it is typically used for, and what it is not. ## Reference The CLI, agents.toml, and configuration. - [agents.toml](https://contenox.com/docs/reference/agents-config/): The config file behind agent declarations — budgets, loop bounds, the envelopes that transpile into HITL policy, and what each tool name resolves to. - [Configuration](https://contenox.com/docs/reference/config/): Backends, defaults, and workspace state — all stored in SQLite, managed with CLI commands. - [Contenox CLI Reference](https://contenox.com/docs/reference/contenox-cli/): Every contenox subcommand, flag, and environment variable. ## Specification The compiled chain format: handlers, transitions, worked examples. - [The chain format](https://contenox.com/docs/specification/): The reference for the JSON state machine behind an agent — the artifact you read to see what it may do, and the one you write when you need a guarantee instead of an instruction. - [Annotated Examples](https://contenox.com/docs/specification/examples/): Full working task chains with commentary, from tool use to error handling. - [Handlers](https://contenox.com/docs/specification/handlers/): Every task handler type and the fields valid for each. - [The relay protocol](https://contenox.com/docs/specification/relay-protocol/): The wire contract between a contenox runtime and a relay — framing, the envelope, the handshake and its signature, resumption, and what a relay must never do. Enough to run your own. - [Transitions & Branching](https://contenox.com/docs/specification/transitions/): How a chain decides which task runs next — operators, edges, and on_failure. ## Integrations Editors over ACP, model providers, MCP servers and OpenAPI tools. - [Use Contenox from AionUi](https://contenox.com/docs/integrations/editors/aionui/): Run your contenox chains inside AionUi — a free, local, open-source desktop chat UI for ACP agents. - [Use Contenox from JetBrains](https://contenox.com/docs/integrations/editors/jetbrains/): Drive your chains from inside GoLand, IntelliJ IDEA, and other JetBrains IDEs over the Agent Client Protocol. - [Use Contenox from OpenClaw](https://contenox.com/docs/integrations/editors/openclaw/): Run Contenox as a hardened, contained ACP agent driven by OpenClaw over a chat channel — the untrusted-driver profile. - [Use Contenox from Zed](https://contenox.com/docs/integrations/editors/zed/): Drive your chains from inside the Zed editor over the Agent Client Protocol. - [Anthropic](https://contenox.com/docs/integrations/providers/anthropic/): Connect Contenox to Anthropic's Claude models via the Anthropic API. - [AWS Bedrock](https://contenox.com/docs/integrations/providers/bedrock/): Connect Contenox to Amazon Bedrock — Claude, Llama, Mistral, and Nova models on your AWS account. - [Google Gemini](https://contenox.com/docs/integrations/providers/gemini/): Connect Contenox to Google Gemini via AI Studio or Vertex AI. - [Ollama](https://contenox.com/docs/integrations/providers/ollama/): Connect Contenox to a local Ollama instance or Ollama Cloud. - [OpenAI](https://contenox.com/docs/integrations/providers/openai/): Connect Contenox to OpenAI or any OpenAI-compatible endpoint. - [Vertex AI (Google Cloud)](https://contenox.com/docs/integrations/providers/vertex/): Configure Contenox to use Gemini on Vertex AI — billed through your GCP project — and renew credentials when they expire. - [What are Tools?](https://contenox.com/docs/integrations/tools/): How contenox turns files, commands, and APIs into schemas a model can call — and how the allowlist decides what's on the table. - [Local Tools](https://contenox.com/docs/integrations/tools/local/): Give a model controlled, policy-scoped access to the filesystem and shell on the machine contenox runs on. - [Model Context Protocol (MCP)](https://contenox.com/docs/integrations/tools/mcp/): Connect any MCP server — local, SSE, or HTTP — with persistent, session-scoped connections instead of one-shot calls. - [Remote Tools](https://contenox.com/docs/integrations/tools/remote/): Point at any HTTP service's OpenAPI spec and every operation becomes a callable, allowlistable tool — no client code required. ## Use cases Worked recipes. - [Cookbook](https://contenox.com/docs/use-cases/): Recipes for real work — MCP integrations, browser automation, authored HITL policies, and tool-authoring patterns. - [Any API, a tool you authored](https://contenox.com/docs/use-cases/any-api-as-a-tool/): Contenox turns any HTTP API into a scoped, credential-hidden, policy-governed tool — so an assistant, even an untrusted one, reaches exactly the slice you authored and nothing more. - [The pause is yours to define](https://contenox.com/docs/use-cases/authored-approval/): HITL isn't a checkbox. It's a policy file you wrote. - [The oracle](https://contenox.com/docs/use-cases/auto-attention/): An adjudicating agent that answers a subagent's routine asks — questions, and optionally gated tool calls — so unattended runs finish; consequential asks still wait for you. - [Codebase documentation](https://contenox.com/docs/use-cases/codebase-docs/): Declare a docs agent that reads your source tree and writes architecture guides, onboarding docs and API references — fired by contenox run from a Makefile or a CI step. - [Git & DevOps recipes](https://contenox.com/docs/use-cases/git-devops/): Commit messages, PR reviews and test-failure triage as declared agents fired by contenox run — an exit code to branch on, and a durable record of every run. - [HubSpot via MCP](https://contenox.com/docs/use-cases/hubspot-mcp/): Read and write your HubSpot CRM through HubSpot's own MCP server — OAuth 2.1 + PKCE, tokens stored locally. - [Leads → HubSpot](https://contenox.com/docs/use-cases/leads-to-hubspot/): One agent finds leads through Tavily's MCP server, another writes them into HubSpot through a hand-curated three-operation OpenAPI subset — two declarations, two contenox run invocations, no glue script. - [The moderation gate](https://contenox.com/docs/use-cases/moderation-gate/): A small cheap model decides whether the big expensive one runs at all. Why I authored it this way. - [Multi-provider fallback as authored resilience](https://contenox.com/docs/use-cases/multi-provider-fallback/): The vendor doesn't choose your failure mode. You do. - [The nested permission bomb](https://contenox.com/docs/use-cases/nested-permission-bomb/): Why inheriting human permissions is a privilege escalation vulnerability, and how to author actual AI boundaries. - [Notion as a Tool](https://contenox.com/docs/use-cases/notion-mcp/): Connect contenox to your Notion workspace via the official MCP server — read, create, and update pages like any chat message. - [Authoring your tool inventory](https://contenox.com/docs/use-cases/openapi-subset/): Expose a curated subset of an OpenAPI spec as agent tools — least privilege at registration time. - [Browser Automation with Playwright MCP](https://contenox.com/docs/use-cases/playwright-mcp/): Register Microsoft's Playwright MCP server and drive a real browser from the terminal — navigation, clicks, snapshots, and more. - [Automated release notes](https://contenox.com/docs/use-cases/release-notes/): A declared agent reads the commit range with the git tools and writes RELEASE_NOTES.md; contenox run fires it from CI and exits 0 when the file landed. - [The review specialist](https://contenox.com/docs/use-cases/review-specialist/): A request to review the git diff got a useless answer. The fix was not a better prompt — it was a third branch in the router, with the write tools taken away. - [Stateful Agents with MCP](https://contenox.com/docs/use-cases/stateful-agents-mcp/): Give a model a persistent memory graph, the local filesystem, and live web pages through native MCP — state that survives across calls. ## Legal - [Legal index](https://contenox.com/legal): terms, privacy, withdrawal, imprint, security, sub-processors for the optional hosted service. ## Source - [github.com/contenox/contenox](https://github.com/contenox/contenox): Apache-2.0.