Contenox

AI workflows you can run, review, and own.

Contenox is an open-source, local-first AI workflow runtime for developers. It turns repeatable coding and tool workflows into versioned Chains: files that declare prompts, model/provider routing, tool allowlists, retries, branches, budgets, and human approval gates. Run the same workflow from the CLI, VS Code, or any ACP-compatible client, using local models, Ollama, or hosted providers while sessions, config, telemetry, and runtime state stay on your machine.

It is built for specific, reviewable AI work, not vague promises of fully autonomous agents.

📖 contenox.com

---

What would I use this for?

Package a repeatable AI task as a chain, then run it the same way every time:

• Review a diff — run the tests, summarize the risk, and gate on your approval before it acts.
• Draft release evidence — turn git log, PRs, and CI output into a changelog and reviewer packet.
• Wrap an internal API — expose a safe, curated tool subset with approval required on mutating calls.
• Automate repo chores — take an issue, produce a patch, run the tests, write the PR description.
• Ask a local model — codebase chat and one-off prompts from the CLI or your editor, no API key required.

The same chains run from the CLI, VS Code, or any ACP client, against local or hosted models, with sessions and state staying on your machine. Detailed examples are in What it is good for below.

---

Install

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

---

Quick Start

# Scaffold a workspace and register the local backend
contenox init

# Pull a model — first pull becomes the default-model automatically
contenox model pull granite-3.2-2b

# Use it
contenox "say hello world in python"
contenox chat -e                        # open $EDITOR to compose a prompt

That's it. No API key, no external server, no backend add ceremony — init registers the local llama.cpp backend pointed at ~/.contenox/models/, model pull populates it. Resume past sessions with contenox session list and contenox session switch <name>. To use a cloud provider instead, see Backends below.

---

What you author

The workflow behavior is a chain file. Every decision is a JSON key:

{
  "id": "review",
  "tasks": [
    {
      "id": "review",
      "handler": "chat_completion",
      "system_instruction": "You are a code reviewer. Analyze the diff, run the tests if tools are available, then give a concise review.",
      "execute_config": {
        "model": "{{var:model}}",
        "provider": "{{var:provider}}",
        "tools": ["local_shell", "local_fs"],
        "tools_policies": {
          "local_shell": { "_allowed_commands": "go,make,npm,cargo,grep,cat" }
        }
      },
      "transition": {
        "branches": [
          { "operator": "equals", "when": "tool_call", "goto": "run_tools" },
          { "operator": "default", "goto": "end" }
        ]
      }
    },
    {
      "id": "run_tools",
      "handler": "execute_tool_calls",
      "input_var": "review",
      "transition": {
        "branches": [
          { "operator": "default", "goto": "review" }
        ]
      }
    }
  ]
}

System prompt, model, tool policy, allowed commands, retry budget, and transitions are all visible. Save the chain and pipe in a diff:

git diff | contenox run --chain ./review.json

Walk through your first chain step by step: contenox.com/docs/guide/first-chain.

---

What it is good for

Contenox is strongest when the workflow is specific and repeatable: known inputs, known tools, known output shape, and explicit review gates.

Examples of workflows you can package as chains:

Release evidence pack
Input: git log, PRs, tickets, CI output
Output: changelog, risk notes, deployment checklist, reviewer packet
Gate: human approval before publishing

API-to-workflow wrapper
Input: internal OpenAPI spec
Output: curated tool subset, hidden tenant/env args, auth handling, HITL policy
Gate: approval for mutating calls

Repo maintenance chain
Input: issue or migration request
Output: patch, test run, PR description
Gate: shell/filesystem approval and human merge

State lives locally in SQLite. Sessions persist across invocations. The AI provider is a config line — Ollama, OpenAI, Anthropic, Mistral, Gemini, AWS Bedrock, vLLM, Vertex (Gemini), or in-process llama.cpp. Use a cloud model, a local server, or a local GGUF model depending on the workflow and data boundary.

---

Where it fits

Contenox is the agent layer you control from terminal to editor. The category is local-first AI workflow runtime; the architecture is developer agent runtime.

Nearby world	Why Contenox is different
Cursor / IDE copilots	Runtime-first, not editor-first. The same engine works from the terminal, VS Code, and ACP clients.
Aider / CLI coding agents	Broader workflow, session, tool policy, and provider scope than a single coding loop.
LangChain / agent frameworks	End-user executable product, not just a library you wire into an app.
Dify / n8n / web AI workflow tools	Local desktop/workspace-first, not web-app/SaaS-first.
Ollama wrappers	Provider-neutral and workflow/tool/HITL-oriented, with local and hosted models.

---

Connect your stack

Anything you can reach over MCP, an OpenAPI spec, or a shell command can become a scoped tool in a chain:

# Any MCP-compatible server (Notion, Linear, Playwright, GitHub, Postgres, …)
contenox mcp add notion https://mcp.notion.com/mcp --auth-type oauth

# Any HTTP API with an OpenAPI spec (no glue code required)
# Slice a monolithic API into safe subsets by pointing --spec at a curated local file
contenox tools add erp_billing --url https://erp.internal.example.com --spec ./billing-subset.yaml

# The shell, with your own command policy declared in the chain
contenox --shell "check Proxmox and flag anything red"

---

Use it from Zed (or any ACP client)

ACP/editor support is an optional way to run the same local chains inside an editor. Contenox speaks the Agent Client Protocol over stdio. Drop this into ~/.config/zed/settings.json:

{
  "agent_servers": {
    "Contenox": {
      "type": "custom",
      "command": "contenox",
      "args": ["acp"]
    }
  }
}

Open Zed's agent panel and pick Contenox. Your chain runs inside the editor: tool calls render as cards with the actual command/path, HITL prompts route through Zed's permission UI, and session history replays when you reopen the project. Chain selection lives at ~/.contenox/default-acp-chain.json (or set CONTENOX_ACP_CHAIN_PATH). Full guide → contenox.com/docs/guide/zed.

JetBrains (GoLand, IntelliJ IDEA, …) reads agent servers from ~/.jetbrains/acp.json — same binary, different schema (no "type" field):

{
  "default_mcp_settings": { "use_custom_mcp": true, "use_idea_mcp": false },
  "agent_servers": {
    "Contenox": {
      "command": "contenox",
      "args": ["acp"]
    }
  }
}

Verified with GoLand 2026.1.2. Full guide → contenox.com/docs/guide/jetbrains.

AionUi — a free, local, open-source desktop chat UI for ACP agents. Add a Custom Agent: command contenox, args ["acp"]. Verified with AionUi 2.0.0. Full guide → contenox.com/docs/guide/aionui.

---

Backends

The local backend (in-process llama.cpp) is registered automatically by contenox init and lives at ~/.contenox/models/. Populate it with contenox model pull <name> — never type backend add local yourself. To add anything else:

# Other local servers
contenox backend add ollama    --type ollama
contenox backend add myvllm    --type vllm   --url http://gpu-host:8000

# Cloud providers
contenox backend add openai    --type openai    --api-key-env OPENAI_API_KEY
contenox backend add anthropic --type anthropic --api-key-env ANTHROPIC_API_KEY
contenox backend add mistral   --type mistral   --api-key-env MISTRAL_API_KEY
contenox backend add gemini    --type gemini    --api-key-env GEMINI_API_KEY
contenox backend add bedrock   --type bedrock   --url https://bedrock-runtime.us-east-1.amazonaws.com
contenox backend add vertex    --type vertex-google --url "https://us-central1-aiplatform.googleapis.com/v1/projects/$GOOGLE_CLOUD_PROJECT/locations/us-central1"

# Set your defaults
contenox config set default-model qwen2.5:7b
contenox config set default-provider ollama

---

Build from source

Requires Go 1.25+.

git clone https://github.com/contenox/runtime
cd runtime
make build-contenox

---

Questions: hello@contenox.com