Documentation

• Lab The contenox Lab — research built, shipped, and run for real. 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, and blueprints.
• Task Chains The JSON state machine that defines how your agent behaves — composable, inspectable, backend-agnostic.
• Cookbook Copy-paste chains for real work — commit messages, release notes, CRM writes, codebase docs, and browser automation.

guide/

• Confining agents: the sandbox wall How the default filesystem/exec/environment fence and the opt-in network wall confine a foreign ACP agent's process.
• 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.
• The agentic loop The ReAct loop as contenox implements it — an authored task graph you copy and trim, not vendor plumbing you configure.
• 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.
• Chain files: 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.
• Core Concepts How chains, tasks, tools, transitions, and macros fit together in Contenox.
• 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.
• 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.
• Your first chain Walk from a blank file to a working authored chain in five edits.
• HITL Policies Control which tool calls require human approval using named policy presets.
• 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 How /pair 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 Install Contenox and connect a model.
• 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.
• Workspace index & search Build a local semantic index over your workspace and query it — from the CLI or from the agent's workspace_search tool.
• 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.
• 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.

specification/

• Annotated Examples Full working task chains with commentary, from tool use to error handling.
• 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.

integrations/

• 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.
• 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.
• 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 attention oracle (beta) mission fire --oracle mounts an in-process driver that answers routine mission questions so unattended runs finish; consequential asks still wait for you.
• Codebase Documentation Point contenox at your source tree and get living architecture guides, API references, and onboarding docs — without leaving the terminal.
• Git & DevOps Recipes Pipe your diff or log into contenox run and get commit messages, PR summaries, and reviews back — no setup, no sessions.
• HubSpot via MCP Read and write your HubSpot CRM through HubSpot's own MCP server — OAuth 2.1 + PKCE, tokens stored locally.
• Leads → HubSpot Tavily finds fresh leads on the web; an OpenAPI sub-spec writes them straight into HubSpot — companies, contacts, and associations, no glue code.
• 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 Pipe git log into contenox run and get grouped, categorized release notes back — no custom chain, no setup.
• 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/

• Configuration Backends, defaults, and workspace state — all stored in SQLite, managed with CLI commands.
• Contenox CLI Reference Every contenox subcommand, flag, and environment variable.

development/

• The ACP client library and its verification harnesses
• Build requirements
• Chains
• Engine event contract
• Release pipelines
• 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.
• 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.
• 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.