A stone cairn on a rocky cape under a dark storm sky, with the article title about running the Cairn pentest framework with Claude Code or Codex
Cover based on a photo by APneunzehn74, via Wikimedia Commons, CC0 1.0

The Cairn pentest framework doesn't call a model itself. Its workers are coding agents you already know: Claude Code, Codex or Pi. So to run Cairn with Claude Code or Codex on a custom LLM endpoint, you set each worker's base URL, key and model in dispatch.yaml, and Cairn passes them to the CLI it launches. This guide shows that setup with RedRouter as the endpoint, for authorized pentests, CTFs and labs.

Cairn is in the news this month for the wrong reasons. On October 30, 2026, Google Threat Intelligence Group and Mandiant reported that threat actors have used open-source agentic pentest frameworks, naming ARTEX, HexStrike, PentAGI and CAIRN, during intrusions they investigated. Help Net Security covered the report on November 9. Defenders and red teams now have a reason to know how it works.

Use Cairn only on systems you own, isolated labs, CTFs, or targets you have written authorization to test. Cairn's own README says the same, and it's the only way this guide applies.

Diagram of a Cairn pentest framework setup: the Cairn server holds facts, intents and hints, the dispatcher schedules Claude Code, Codex or Pi workers, each worker sends model requests to RedRouter, and the workers act only on an authorized lab or in-scope target
Diagram of a Cairn pentest framework setup: the Cairn server holds facts, intents and hints, the dispatcher schedules Claude Code, Codex or Pi workers, each worker sends model requests to RedRouter, and the workers act only on an authorized lab or in-scope target Image: RedRouter, Original

What the Cairn pentest framework is

Cairn (sometimes misspelled Carin) is an AGPL-3.0 project from oritera with about 5,100 GitHub stars when we checked on November 13, 2026. It isn't related to other security projects that use the CAIRN name. The README describes it as a general-purpose "state-space search" engine, with penetration testing as the first domain it was validated on: you give it an origin (a target) and a goal (a shell, a flag), and it searches for the path.

It works on a shared board with three kinds of entries:

  • Facts: confirmed findings written to the board.
  • Intents: directions to explore next, not yet run.
  • Hints: guidance a human adds at any time, which agents pick up on their next read.

Agent workers read the whole graph, decide what to explore, run it, and write new facts back. They have no fixed roles, and they coordinate only through the board. The README lists three task types: Bootstrap (try to solve the problem directly at the start), Reason (is the goal met, and what should be explored next) and Explore (claim one intent, run it, report one fact).

The pieces are a Cairn server (keeps the graph consistent, port 8000), a dispatcher (schedules tasks and starts workers) and the workers themselves. By default each project gets its own Docker worker container; a local mode runs workers directly on the host instead.

The README reports that Cairn solved 54 of 54 challenges and placed third at the second Tencent Cloud Hackathon AI penetration testing challenge. That's the project's own claim; we haven't reproduced it.

Why the model is set per worker

Cairn has no general OPENAI_BASE_URL setting. Each worker in dispatch.yaml has a type (claudecode, codex or pi) and an env block, and those variables configure the CLI that runs the task. From the official dispatch.example.yaml and the worker adapters in the repo (checked November 13, 2026):

Worker typeModelBase URLKey
claudecodeANTHROPIC_MODELANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN
codexCODEX_MODELCODEX_BASE_URLOPENAI_API_KEY
piPI_MODELPI_BASE_URLPI_API_KEY, plus PI_PROVIDER_API

That means any endpoint that speaks the Anthropic Messages API or the OpenAI Responses or Chat Completions APIs can drive a Cairn worker. RedRouter serves all three. Per the RedRouter compatibility docs, the Messages base URL is https://redrouter.org and the OpenAI-compatible base URL is https://redrouter.org/v1. If you don't have a key yet, the API quickstart covers it.

Step 1: Install Cairn in a lab environment

The README's prerequisites are macOS or Linux, Python 3.12 or newer, and Docker for container mode. Pull the worker image and copy the example config:

git clone https://github.com/oritera/Cairn.git
cd Cairn
docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest
cp dispatch.example.yaml dispatch.yaml

Run this on a lab host or VM, not your daily machine. Workers run their CLIs with permission prompts turned off (more on that below), so the isolation has to come from where you run them.

Step 2: Point a Claude Code worker at RedRouter

Replace the example worker in dispatch.yaml with one that uses RedRouter's Messages API. Keep the rest of the file as shipped until the first worker is healthy.

workers:
  - name: "claudecode_red-cyber-1"
    type: "claudecode"
    task_types: [bootstrap, reason, explore]
    max_running: 2
    priority: 0
    env:
      ANTHROPIC_MODEL: "red-cyber-1"
      ANTHROPIC_BASE_URL: "https://redrouter.org"
      ANTHROPIC_AUTH_TOKEN: "your-redrouter-api-key"

Use the origin without /v1. Cairn's health check posts to ANTHROPIC_BASE_URL plus /v1/messages, and Claude Code adds the same path, so https://redrouter.org/v1 would produce a doubled /v1/v1. The RedRouter Claude Code docs list the full set of variables for running Claude Code by hand, and our Claude Code, OpenCode and Cline guide covers the client in more depth.

Step 3 (optional): Add a Codex or Pi worker

Workers can be mixed. The example's comments note that lower priority numbers are preferred and that slower backends benefit from a lower max_running. A Codex worker for explore tasks:

  - name: "codex_glm-5.3-flash-red"
    type: "codex"
    task_types: [explore]
    max_running: 2
    priority: 1
    env:
      CODEX_MODEL: "glm-5.3-flash-red"
      CODEX_BASE_URL: "https://redrouter.org/v1"
      OPENAI_API_KEY: "your-redrouter-api-key"

Cairn's Codex adapter builds its own provider config with wire_api="responses", which matches what the RedRouter Codex CLI docs require, and it health-checks CODEX_BASE_URL plus /responses. The RedRouter docs also note that WebSockets aren't available and their own profile selects HTTP; Cairn's adapter doesn't set that option, so if a Codex worker fails while the Claude Code worker works, run Codex alone with the RedRouter profile first to see which setting differs. For more on Codex and other OpenAI-compatible clients, see OpenAI-compatible API for security agents.

A Pi worker follows the example's commented block: PI_BASE_URL: "https://redrouter.org/v1", your key in PI_API_KEY, a model ID in PI_MODEL, and PI_PROVIDER_API: "openai-completions", which makes Cairn's health check call /chat/completions.

Step 4: Start Cairn and check the workers

The README's recommended path is Docker Compose:

docker pull ghcr.io/astral-sh/uv:python3.13-trixie
docker compose up --build

That starts cairn-server on port 8000 and the dispatcher once the server is healthy, with data in ./datas/cairn/. To run the pieces by hand, or just test your worker config:

uv run --project cairn cairn serve
uv run --project cairn cairn dispatch --config dispatch.yaml --startup-healthcheck-only

The health check sends a tiny "ping" request to each worker's endpoint with its model and key. Fix any failure here before you create a project. We haven't asserted a full Cairn run against RedRouter in this guide; the health check is your first real test.

Local mode: no Docker, no sandbox

Cairn's local mode (runtime.execution: local, from dispatch.local.example.yaml) runs workers as processes on the dispatcher host and reuses the claude, codex or pi CLIs already installed and logged in there. The example config sets no keys, base URLs or models, so each CLI uses its own configuration. To use RedRouter in local mode, configure the CLIs themselves, for example with the environment variables from the Claude Code docs or the Codex profile from the Codex docs, exported in the shell that starts the dispatcher.

Be careful here. The README says local-mode agents "run with your user's permissions and no sandbox." Use it only on a dedicated lab machine.

Safety and scope

Two details in the code are worth knowing before you point Cairn at anything:

  • The Claude Code worker launches claude with --dangerously-skip-permissions, and the Codex worker uses --dangerously-bypass-approvals-and-sandbox. There's no per-command approval inside a Cairn run. RedRouter's own docs recommend manual permissions for interactive Claude Code use, and RedRouter doesn't classify tool calls on the server, so with Cairn the controls are the container or lab boundary, the network you give it, and the target you write in the project.
  • The container config uses network_mode: "host", and the example notes that extra Linux capabilities such as NET_RAW should be added only when a task needs them.

Put the written scope in the project's origin and goal, and use hints to steer agents away from anything out of scope. With a model built for authorized security work, that scope is there to keep agents on target, not to talk a model past a refusal.

Cairn is AGPL-3.0, and the README asks commercial users who don't want AGPL obligations to contact the author for a commercial license. Check that before using it on paid engagements.

Which model to use

Cairn's reason and explore loops send the whole graph and long tool output back to the model, so context length and tool calling matter most.

  • GLM 5.3 Flash Red (glm-5.3-flash-red) costs $0.25 per 1M input tokens, $0.10 per 1M cached input tokens and $1.00 per 1M output tokens, with a 1,048,576-token context window and tool calling. It suits high-volume explore workers. See its model page and pricing.
  • red-cyber-1 (Beta) costs $0.28 input, $0.10 cached input and $1.10 output per 1M tokens, also with a 1M-token context. RedRouter's docs present it as the featured model for authorized pentesting and use it in the Claude Code setup. See the red-cyber-1 page.

Both are text-only, so workers should pass tool output as text. Prices can change, so check the model pages before a long run. Splitting models by task type, with one model on bootstrap and reason and another on explore, is a reasonable way to start.

Data handling during an engagement

A Cairn board fills up with hostnames, credentials and findings, and every worker request carries that context. Decide on retention first. Each RedRouter API key has a store_content setting, and new keys default to storage off. Account-wide zero data retention (ZDR) is a separate, opt-in setting that's off by default; the data handling docs cover how it works and who can turn it on, and what RedRouter keeps explains it in plain terms. Cairn also stores its own data in ./datas/cairn/ and keeps stopped containers by default (completed_action: "stop"), so clean those up per your engagement rules.

Troubleshooting

  • Health check returns 401. The key is wrong or missing. For claudecode workers it goes in ANTHROPIC_AUTH_TOKEN; for codex, OPENAI_API_KEY; for pi, PI_API_KEY.
  • Health check returns 404. Usually the base URL. Claude Code workers take https://redrouter.org; Codex and Pi workers take https://redrouter.org/v1.
  • A model ID isn't found. Use an exact ID from the RedRouter model catalog, such as red-cyber-1 or glm-5.3-flash-red.
  • Local mode can't find a worker. The dispatcher checks that each CLI is on PATH. Run it on the host, not in Docker, and log the CLIs in first.

Other frameworks call the model directly, so their guides set a base URL in the framework itself: see ARTEX with RedRouter and PentAGI with an OpenAI-compatible API. For the wider process around tools like these, see the AI bug bounty workflow.

FAQ

What is the Cairn pentest framework?

Cairn is an open-source, AGPL-3.0 engine from oritera that runs AI agents against a shared board of facts, intents and hints to find a path from a target to a goal. Penetration testing is its first validated use, and it also targets CTFs and vulnerability research.

Is it Cairn or Carin?

Cairn. The project's GitHub description notes that it's sometimes misspelled Carin.

Can I use Cairn with Claude Code?

Yes. claudecode is one of Cairn's three worker types. Set ANTHROPIC_MODEL, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in the worker's env block in dispatch.yaml, or use local mode with a logged-in claude CLI.

Does Cairn work with an OpenAI-compatible API?

Yes, through its codex and pi workers. A Codex worker takes CODEX_BASE_URL, OPENAI_API_KEY and CODEX_MODEL and uses the Responses API. A Pi worker can use Chat Completions with PI_PROVIDER_API: "openai-completions".

Is Cairn safe to run?

It runs agents with permission prompts turned off, and local mode has no sandbox. Run it in an isolated lab, limit its network access, and point it only at systems you're authorized to test. A model built for authorized security work refuses legitimate in-scope tasks less often, but it doesn't replace that isolation.

Sources

All read on November 13, 2026 (PT).