Cairn — General State-Space Search Engine
A general-purpose problem-solving engine for well-defined origins and goals, proven on autonomous penetration testing.
- Source repo
- oritera/Cairn
- Stars
- ★ 3.6k
- Last updated
- 1mo ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 39/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Security teams automating authorized penetration tests, from reconnaissance to exploitation, against specified targets.
- Not a fit if
- Teams wanting a battle-tested, well-documented tool
- Users on shared hosts who can't accept unsandboxed agent permissions
- Source review
- 39/100 · Major gaps 3 safety controls not found
What does this agent do, and when should you use it?
Cairn is a general-purpose problem-solving engine built on a Blackboard Architecture with an explicit fact-intent graph. It defines no roles or workflows; given an origin and a goal, it searches for a path through an unknown state space. Penetration testing is the first validated domain, but it also applies to CTF, vulnerability research, and other similarly structured problems. The system comprises a Cairn Server that maintains graph consistency, a Dispatcher that reads the graph and schedules tasks, and per-project Worker Containers running multiple Agent Workers that execute an OODA loop, coordinating only via the shared blackboard (stigmergy). Supported worker backends include Claude Code, Codex, and Pi. Deployment offers Docker Compose, manual setup, and a local mode without Docker. In a Tencent Cloud hackathon, it solved 54/54 problems, the only team to achieve an AK, ranking 3rd. Licensed under AGPL-3.0, commercial use requires a separate license.
Cairn executes three task types: Bootstrap (attempts direct problem-solving at project start), Reason (reads the full graph, evaluates whether the goal is met, and proposes next intents), and Explore (claims an Intent, runs the exploration, and reports a Fact). The Dispatcher schedules tasks and manages worker containers, while Agent Workers receive prompts via the API and return structured output. The system runs via commands: cairn serve to start the server, cairn dispatch --config dispatch.yaml to start the dispatcher. It supports Docker Compose for containerized deployment, and local mode where workers run directly on the host using pre-installed CLIs (claude, codex, pi). Inputs are the origin (e.g., target IP) and goal (e.g., shell or flag); outputs are accumulated facts and completion states. Hints can be injected anytime by humans to guide exploration.
- Security teams automating authorized penetration tests, from reconnaissance to exploitation, against specified targets.
- CTF participants using Cairn to automatically discover exploitation chains and capture flags.
- Vulnerability researchers performing black-box testing to explore unknown attack surfaces in a structured way.
- Researchers applying the engine to other goal-directed problems such as mathematical proof search or decision-making.
- Red team operators evaluating autonomous agent efficiency in internal exercises.
- Developers testing Cairn in local mode without Docker, reusing existing CLI tools and configurations.
How do you install or deploy this agent?
Prerequisites: macOS or Linux, Python ≥ 3.12, Docker (for container mode). Pull the worker image: docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest. Copy configuration: cp dispatch.example.yaml dispatch.yaml and fill in LLM endpoints and API keys. For Docker Compose, pull the base image docker pull ghcr.io/astral-sh/uv:python3.13-trixie, then run docker compose up --build. For manual setup, start the server with uv run --project cairn cairn serve and the dispatcher with uv run --project cairn cairn dispatch --config dispatch.yaml. Local mode: copy dispatch.local.example.yaml to dispatch.yaml; ensure claude/codex/pi CLIs are installed and logged in on the host.
How do you use this agent?
After configuring dispatch.yaml with LLM credentials, start the server and dispatcher: uv run --project cairn cairn serve and uv run --project cairn cairn dispatch --config dispatch.yaml. The system creates per-project worker containers; multiple workers run concurrently inside. Coordination is via the shared blackboard: facts, intents, and hints. The dispatcher handles scheduling: bootstrap at start, reason on each cycle, and explore for pending intents. Use --startup-healthcheck-only for a quick check. In local mode, run the dispatcher directly on the host, and workers use the host's CLIs with no sandbox. Run tests with uv run --project cairn --group dev pytest.
What are this agent's strengths and limitations?
- General engine not tied to a specific domain; applicable to any problem with defined origin and goal.
- Proven in a competitive setting: achieved 54/54 problems, the only team to AK, ranking 3rd among 610 teams.
- Blackboard architecture and stigmergy allow scalable concurrent workers without direct communication.
- Multiple worker backends and local mode reduce infrastructure overhead and vendor lock-in.
- Early-stage project, not battle-tested beyond one competition; limited documentation and community.
- Relies on external LLM API endpoints; requires API keys and incurs token costs.
- Local mode requires manual CLI authentication and lacks sandboxing, increasing risk on shared hosts.
- AGPL-3.0 license restricts commercial use without a separate license, which may deter adoption in companies.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Cairn — General State-Space Search Engine This agent | 39 · Major gaps | Self-hosted serviceFree + model costs | ★ 3.6k | 1mo ago | Python | Codex · Claude Code |
| VulnClaw | 48 · Major gaps | CLIFree + model costs | ★ 3.7k | 13d ago | Python | — |
| HackSkills — Offensive-Security Skills for AI Agents | 31 · Major gaps | CLIFree | ★ 2.5k | 1mo ago | CSS | — |
| HexStrike AI MCP | 22 · Major gaps | MCP serverFree | ★ 13k | 2mo ago | Python | Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: local mode explicitly warns agents run with user permissions and no sandbox, but no least-privilege mechanism; config requires API keys but no storage/access control details; container mode uses Docker but no isolation hardening. Deductions: no user confirmation, insufficient data flow transparency, missing sensitive data handling details, no dependency security, no rollback, partial source attribution (README mentions author but unverified).
Evidence shows: tests cover config validation and container path safety, but not runtime behavior; dependency availability not mentioned; failure messages not detailed. Deductions: self-consistency partially met, but dependency availability and failure messages lack evidence.
Evidence shows: README clearly defines target audience (security testers) and scenarios (pentest, CTF), and capability boundaries (general state-space search); but trigger precision (task generation logic) not detailed; environment fit (macOS/Linux, Docker) documented. Deductions: trigger precision lacks evidence.
Evidence shows: README well-structured, install notes detailed, license clear (AGPL-3.0), but missing versioning/changelog, naming stability, and known limitations incomplete. Deductions: no changelog, naming stability not mentioned, known limitations partial.
Evidence shows: output is structured facts and intents, but usability not described; marginal value supported by competition results, but cost-benefit not quantified. Deductions: output usability lacks evidence, cost-benefit not quantified.
Evidence shows: README claims competition results but no reproducible steps; tests exist but not covering all claims; facts vs inferences not clearly separated. Deductions: claim traceability insufficient, cross-source corroboration limited, fact-inference separation unclear.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Local mode runs without sandbox, agents run with user permissions, posing security risks.
- API key management not documented, potential leakage.
- Dependency security not addressed, supply chain needs review.
- Competition results not independently verifiable.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Highlights This patch release improves dispatcher stability for large project graphs and long-running worker executions. Cairn now avoids OS argument-size failures by passing large graph snapshots through files inside the worker container, while keeping worker command argv small and preserving the existing dispatcher execution flow. What's New * Store large graph snapshots in worker containers via Docker archive copy instead of embedding full graph YAML in command arguments …View on GitHub ↗ -
Release notes excerpt
Highlights This release adds Pi as a supported dispatcher worker backend. Cairn can now run with Claude Code, Codex, or Pi workers, enabling more flexible agent orchestration for autonomous security exploration workflows. What's New - Added Pi worker support in the dispatcher - Added Pi session recovery and JSONL output parsing - Added conclude-phase compatibility for Pi execution flows - Added Pi worker configuration example to dispatch.yaml Notes - Pi support has been validated across bootstrap, reason, explore, and conclude flows …View on GitHub ↗ -
Release notes excerpt
First public open-source release of Cairn. Cairn is a general-purpose problem-solving engine built around explicit state-space search. It was first validated on autonomous penetration testing and CTF-style tasks, but the underlying architecture is designed for broader goal-directed problem solving. Highlights - Explicit fact-intent graph for modeling progress through an unknown state space - Blackboard-based coordination model with shared, objective state - Three-task execution loop: Bootstrap, Reason, and Explore …View on GitHub ↗