Quickstart

Install, connect a model, declare an agent, and talk to it. Five steps, and the last one is the one that pays.

1. Install

macOS / Linux (one line):

curl -fsSL https://contenox.com/install.sh | sh

Or download the binary directly from GitHub Releases.

The whole path — install, setup, first prompt — in one take:

2. Connect a model

contenox setup is the entry point. For the local path, install Ollama and pull a model first:

ollama pull qwen3:8b
contenox setup          # pick Ollama, then pick your model from the list

When Ollama is running, the wizard reads the models you have actually pulled and offers them as a numbered menu — press Enter to take the suggested one.

See the Ollama guide for details, including Ollama Cloud.

Then confirm the model is ready:

contenox doctor

Its first line is the verdict, and it names what to run next:

Ready: yes — run: contenox beam

If it says Ready: no, the line under it names the one command that fixes it.

3. Initialize a workspace

Run this once in each project directory you want Contenox to work in:

contenox init

This creates the project-local .contenox/workspace.id marker; agents/ and agents.toml are seeded into ~/.contenox/, shared by every project on the machine (contenox init --local seeds workspace copies that shadow them instead). The approval envelopes are transpiled from agents.toml into ~/.contenox/.generated/, the shipped chains sit under ~/.contenox/system/; a workspace-local file with the same name overrides its global counterpart.

4. Declare an agent

An agent is one file. .contenox/agents/reviewer.md:

---
name: reviewer
description: Reviews a file for correctness problems
---

You are a code reviewer. Read the file you are asked about, then list the
problems you can point at in what you actually read.

No build step — the next run picks it up:

contenox agent list

The frontmatter says how to run it, the body becomes its system prompt. Budgets, retries and shell allowlists go in agents.toml beside it. See Declaring agents.

5. Start working

contenox beam

That is the front door. contenox on its own opens the same thing.

A first terminal conversation with a local model — backends listed, then a question answered in place:

The transcript is your native terminal scrollback, so it scrolls, copies and searches the way everything else in that window does. The composer takes / for commands and @ to put a file in front of the agent. The status line carries the live model, the session, and how much context is left.

The first thirty seconds look like this:

1. Type what you want — @payments.go what breaks if the retry budget is exhausted mid-write? — and read the answer as it lands. Reads run silently; the shipped envelope allows them.
2. Ask for something that changes the world — a file written, a command run. The call stops in front of you as an approval card: the tool, the exact arguments, and the rule that gated it.
3. Answer it with one keystroke. Approve and the call runs and the turn continues; deny and the agent is told so and works around it.

Nothing about that card is beam being careful. The envelope decided it before the surface saw it, so the same call gates the same way in an editor, in a mission, or on your phone. That is the whole idea: see Human gates and envelopes.

Answering the card continues the same turn: the gated tool runs and the reply carries on. The ask was a durable row before the card appeared, so it is equally answerable from another terminal or your phone, it resolves to its on_timeout verdict if the wait runs out, and quitting checkpoints the run so you can answer it later from anywhere. See the durable ask.

6. Scripted and background work

Once the agent does what you want at the keyboard, the same declaration runs without you.

A program is the caller — CI, cron, a Makefile. contenox run takes the task, prints the report to stdout, and exits 0 when the work landed:

contenox run reviewer "review payments.go"
contenox run "summarise what changed under ./internal since Friday"

With no agent named it runs the preseeded run declaration.

Or fire it and walk away. A mission is a one-line intent at a declared agent under a named envelope, with a durable record — reports, plan, and questions that survive the terminal you closed:

contenox mission fire reviewer "review the payment retry change" --wait

7. Optional editor use

Contenox also runs inside editor or desktop clients that speak ACP. The same agents, model config, tools, and HITL policy are used either way; per the protocol the editor owns the workspace, so a session works in the project you already have open:

• Use from Zed
• Use from JetBrains
• Use from AionUi
• Use from OpenClaw

Cloud providers

Contenox needs at least one model to work. Pick the option that fits:

If you’re not sure, start with Ollama for a fully local setup, or Gemini for a free hosted key.

Next steps

• Your first agent — one file, what contenox builds behind it, and where the knobs are
• CLI reference — beam, run, serve, and every flag
• Missions — unattended runs, their envelopes, and the durable record they leave
• Declaring agents — the full frontmatter, skills, and the tools an agent brings with it
• Core concepts — how agents, chains, tasks, and tools fit together
• Writing a chain by hand — for the agent that has outgrown a declaration
• How contenox compares — what it shares with the coding agents, and the three things that are built differently
• MCP integration — connect external tools
• Pairing a machine with a relay — reach a running session from your phone: one typed key, optional always, free for you and three teammates (one machine each)
• AI sovereignty & the EU AI Act — hosting, state, and oversight controls you own