Documentation

• Lab The contenox Lab — research built, shipped, and run for real. The event plane, Beam web UI, Beam Desktop, modeld, the editor agent, hooks, the HTTP API layer, the UI component library, Bob, runnerd, vald-operator, the early Telegram/GitHub MVP, blueprints, and what measuring the hand-written codebase against its AI-assisted successor showed.
• The chain format 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.
• Cookbook Recipes for real work — MCP integrations, browser automation, authored HITL policies, and tool-authoring patterns.

guide/

• chains Writing a chain by hand Walk from a blank file to a working authored chain in five edits — for the agent that has outgrown a declaration.
• confinement Why contenox confines agents 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.
• Quickstart Install contenox, connect a model, declare an agent, and start working in the terminal with contenox beam.
• tutorials Your 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.
• chains The agentic loop The ReAct loop as contenox implements it — an authored task graph you copy and trim, not vendor plumbing you configure.
• confinement Scoping what an agent may do 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.
• tutorials A 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.
• 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.
• chains Naming, roles, and resolution The chain-<role>-<variant>.json convention, what each role means, where each chain is selectable, and exactly what contenox init touches.
• How contenox compares What contenox shares with the coding agents, the three things that are structurally different, what those cost, and which tool to pick.
• confinement The sandbox wall How the default filesystem/exec/environment fence and the opt-in network wall confine a foreign ACP agent's process.
• tutorials An agent that files notes into Obsidian 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.
• chains Request 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.
• Core Concepts How agents, chains, tasks, tools, transitions, and macros fit together in Contenox.
• 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.
• tutorials A recurring job 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.
• Declaring 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.
• confinement Least-privilege shell 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.
• AGENTS.md Project-level instructions and context that load automatically into every session.
• Why a project needs an AGENTS.md 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 The artifact an agent declaration compiles into — writing one by hand, the loop it forms, and how chain files are named and resolved.
• HITL Policies 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.
• Confining agents 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.
• 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.
• Events & triggers (beta) 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.
• contenox serve: the standing host 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.
• Pairing a machine with a relay 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.
• Tutorials Four worked paths — a first agent, a mission agent, an agent that files notes into Obsidian, and a recurring job.
• AI Sovereignty & the EU AI Act 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 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.

integrations/

• What are Tools? How contenox turns files, commands, and APIs into schemas a model can call — and how the allowlist decides what's on the table.
• editors Use Contenox from AionUi Run your contenox chains inside AionUi — a free, local, open-source desktop chat UI for ACP agents.
• editors Use Contenox from JetBrains Drive your chains from inside GoLand, IntelliJ IDEA, and other JetBrains IDEs over the Agent Client Protocol.
• editors Use Contenox from OpenClaw Run Contenox as a hardened, contained ACP agent driven by OpenClaw over a chat channel — the untrusted-driver profile.
• editors Use Contenox from Zed Drive your chains from inside the Zed editor over the Agent Client Protocol.
• providers Anthropic Connect Contenox to Anthropic's Claude models via the Anthropic API.
• providers AWS Bedrock Connect Contenox to Amazon Bedrock — Claude, Llama, Mistral, and Nova models on your AWS account.
• providers Google Gemini Connect Contenox to Google Gemini via AI Studio or Vertex AI.
• providers Ollama Connect Contenox to a local Ollama instance or Ollama Cloud.
• providers OpenAI Connect Contenox to OpenAI or any OpenAI-compatible endpoint.
• providers Vertex AI (Google Cloud) Configure Contenox to use Gemini on Vertex AI — billed through your GCP project — and renew credentials when they expire.
• tools Local Tools Give a model controlled, policy-scoped access to the filesystem and shell on the machine contenox runs on.
• tools Model Context Protocol (MCP) Connect any MCP server — local, SSE, or HTTP — with persistent, session-scoped connections instead of one-shot calls.
• tools Remote Tools Point at any HTTP service's OpenAPI spec and every operation becomes a callable, allowlistable tool — no client code required.

use-cases/

• Any API, a tool you authored 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 HITL isn't a checkbox. It's a policy file you wrote.
• The oracle 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 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 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 Read and write your HubSpot CRM through HubSpot's own MCP server — OAuth 2.1 + PKCE, tokens stored locally.
• Leads → 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 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 The vendor doesn't choose your failure mode. You do.
• The nested permission bomb Why inheriting human permissions is a privilege escalation vulnerability, and how to author actual AI boundaries.
• Notion as a Tool Connect contenox to your Notion workspace via the official MCP server — read, create, and update pages like any chat message.
• Authoring your tool inventory Expose a curated subset of an OpenAPI spec as agent tools — least privilege at registration time.
• Browser Automation with Playwright MCP Register Microsoft's Playwright MCP server and drive a real browser from the terminal — navigation, clicks, snapshots, and more.
• Automated 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 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 Give a model a persistent memory graph, the local filesystem, and live web pages through native MCP — state that survives across calls.

reference/

• agents.toml The config file behind agent declarations — budgets, loop bounds, the envelopes that transpile into HITL policy, and what each tool name resolves to.
• Configuration Backends, defaults, and workspace state — all stored in SQLite, managed with CLI commands.
• Contenox CLI Reference Every contenox subcommand, flag, and environment variable.

specification/

• Handlers Every task handler type and the fields valid for each.
• Transitions & Branching How a chain decides which task runs next — operators, edges, and on_failure.
• Annotated Examples Full working task chains with commentary, from tool use to error handling.
• The 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.

development/

• The hard parts Things that only show up once an agent harness is real — cache prefixes, rule ordering, silent field loss, environments a shell can read. What each one costs and what contenox does about it.
• The ACP client library and its verification harnesses
• Build requirements
• Chains
• Engine event contract
• Release pipelines
• The scripted test backend A backend that replays a JSON dialog instead of calling a model, so the whole stack — chain engine, tool dispatch, HITL gate, sessions, beam — can be driven end to end deterministically. It tests the machinery, not the agent's judgement.
• Windows Development

rnd/

• The HTTP API layer and OpenAPI generator apiframework and a from-scratch OpenAPI 3.1 generator that derived a byte-deterministic spec straight from Go route annotations, with CI gates against drift.
• The attention oracle A second agent that triaged a mission's questions so unattended runs would not stall. Removed 2026-08-14, brought back the same day with a wider contract. What the removal got right, what it got wrong, and what the attempt settled.
• beam: the terminal client The lab record of the first beam — a full-screen terminal client for agent sessions, chat, plan, shell and file edits in one scrollback, approvals answered inline — and the 2026-08 addendum withdrawing its closing verdict.
• Beam Desktop: the client as a peer An Electron shell that deleted HTTP from the loading path entirely — window loaded from disk, runtime spawned as a child process, and one NDJSON pipe carrying both ACP and a private editor method family.
• Beam: the original web UI The React admin and chat SPA that first carried the Beam name — served from a single Go binary, with a diff-backed approval gate and a live agent workspace view.
• The schema-validated app generator A declarative page format, a validator that never stops at the first problem, and a bounded AI draft-and-repair loop that turned a plain-English ask into a working page bound to real backend operations.
• Bob: the hosted document & search dashboard A multi-tenant SaaS dashboard that turned per-tenant connectors, a real embedding model, and a hosted-apps catalog into one workspace a team could sign up for and run.
• The editor agent A VS Code extension that bundled the runtime and registered as a native language-model vendor, and an Agent Client Protocol implementation that made approval a blocking protocol operation — in both directions.
• Event-driven chains: three stories Three working shapes for the beta event tier: a phone buzz when a mission asks for a human, a completion summary written when a mission ends, and the firing record that makes both inspectable.
• The event plane The consumer side of a durable event log — cursors, primary-key firing claims, stale-claim takeover, reversible outcomes, listeners, and staged delay — extracted into the importable libevents, and the operator-authored triggers that fire task chains on it.
• The generation loop Two codebases in the same domain by the same author, one written by hand in 2025 and one AI-assisted in 2026, measured side by side. Size was never the variable. Readability, deletion, and naming were.
• Hooks became tools The external-capability boundary contenox shipped before the industry settled on a name for it — one repo interface, five wire protocols, OpenAPI tool discovery, and an approval decorator that MCP later slotted into unchanged.
• modeld: the local inference daemon Contenox's cross-backend local inference daemon — a live-hardware capacity planner, lease-based single-slot ownership, and llama.cpp/OpenVINO backends behind one stateful session contract.
• The MVP: Telegram and GitHub bots on one chain engine A Telegram co-pilot and an autonomous GitHub PR bot that ran off the same declarative task-chain engine and job-dispatch substrate — first shipped April 2025, before the runtime it depended on grew into this repo.
• runnerd: the self-hosted simulation runner A self-hosted agent that enrolled once, dialed home outbound-only, and turned a scenario into many branching AI-driven exercises with an auditable evidence trail.
• @contenox/ui: the component library A versioned, Storybook-catalogued React 19 + Tailwind design system spanning chat, terminal, and visual workflow components, built to power Beam.
• vald-operator: a Kubernetes operator for per-tenant vector search A Kubernetes controller that turned one declarative object into a full vector-search cluster per tenant, with its unsafe fields made immutable at the API boundary itself.

internal/

• How contenox is developed and released The public repository is a release mirror — one commit per release, a signed tag per release, binaries built from the tag — and a contribution travels through it by being carried upstream.