# oritera/Cairn: An AI State-Space Search Engine Validated on Penetration Testing > Cairn is a general-purpose problem-solving engine built on a Blackboard Architecture with a fact-intent graph. It was validated first on autonomous penetration testing, where it was the only team to solve all 54 problems at a Tencent Cloud hackathon. **oritera/Cairn** — A AI general-purpose state-space search engine, validated first on autonomous penetration testing. - Repository: https://github.com/oritera/Cairn - Stars: 3,149 · Forks: 423 - Language: Python - License: AGPL-3.0 - Published: 2026-09-09 · Updated: 2026-09-09 · Language: en - Canonical page: https://hysenlabs.com/projects/oritera-cairn ## What Cairn Solves and Who It Is For Cairn is an AI search engine for problems that share a specific shape: a known origin, a defined goal, and an unknown path between them. The README frames penetration testing as one instance of this class, alongside vulnerability research, mathematical proof, and CTF challenges. The project defines no roles and no workflows. Given an origin and a goal, it searches for a path through an unknown state space. The target user is an engineer or security researcher who has a problem where the starting point and success condition are clear but the route is not. Cairn does not ask you to describe the steps. It asks you to state where you are and where you want to be. The engine then generates tasks at runtime from the graph's current state rather than from predefined job descriptions. That design choice is what separates it from agent frameworks that ship with fixed roles such as planner, executor, and reviewer. The README states that penetration testing is the first domain Cairn was validated on, and that the engine is built to be general. That claim is backed by the project's hackathon result: 54 out of 54 problems solved, the only team to achieve AK at the Tencent Cloud Hackathon AI Penetration Testing Challenge, 2nd Edition, with a final ranking of 3rd. The README notes the system had never been tested before the competition and came online for the first time at 4 AM on race day, with no training, no tuning, and no domain-specific tooling. ## The Blackboard Architecture and the Fact-Intent Graph Cairn's core mechanism is a Blackboard Architecture with an explicit fact-intent graph. Three primitives are all the engine needs: Fact, Intent, and Hint. A Fact is a confirmed, objective finding written to the board. An Intent is a declared direction of exploration that has not been executed yet. A Hint is human judgment injected at any time, absorbed by agents on the next read. The graph grows from origin toward goal. Every new Fact is a stepping stone; every Intent is a step into the unknown. Agent Workers run an OODA loop: Observe the full graph, Orient to the current state, Decide on next intents, Act to explore, and write findings back as new Facts. Workers have no fixed roles. Tasks are generated at runtime from the graph's current state. Agents coordinate exclusively through the shared board, a pattern the README calls Stigmergy. There is no direct communication between workers and no information silos. The architecture diagram shows a Cairn Server that maintains graph consistency only, a Dispatcher that schedules tasks, manages containers, and is the sole writer to the protocol, and Worker Containers that host multiple Agent Workers. Each project gets its own Worker Container. Agent Workers only receive a prompt and return structured output. There are three task types, all executed by the same Worker. Bootstrap attempts to solve the problem directly at project start and outputs a Fact plus a possible Complete. Reason reads the full graph to check whether the goal is met and what should be explored next, outputting Complete, new Intents, or a no-op. Explore claims one Intent, executes the exploration, and reports one Fact. The separation between Reason and Explore is the part worth noting: one worker decides direction, another executes it, and neither knows the other's identity. ## Installing Cairn with Docker Compose The README lists three prerequisites: macOS or Linux, Python 3.12 or later, and Docker for container execution only. Docker is not needed for local mode. Both setup methods require the worker container image, which the README says to pull with this command: ```bash docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest ``` After pulling the worker image, create your local dispatcher configuration and fill in your LLM endpoints and API keys. The README gives this copy command: ```bash cp dispatch.example.yaml dispatch.yaml ``` The Docker Compose path also requires the base image used to build Cairn. The README specifies this pull: ```bash docker pull ghcr.io/astral-sh/uv:python3.13-trixie ``` Then start the stack: ```bash docker compose up --build ``` According to the README, this starts cairn-server on port 8000 and cairn-dispatcher once the server passes its health check. The dispatcher mounts dispatch.yaml from the project root. The docker-compose.yaml file confirms the port mapping is 8000:8000, that the server command is uv run cairn serve --host 0.0.0.0 --no-access-log, and that the dispatcher command is uv run cairn dispatch --config dispatch.yaml. The dispatcher also mounts /var/run/docker.sock so it can manage worker containers. The server health check polls http://127.0.0.1:8000/projects with a 5-second timeout, retrying 12 times at 10-second intervals. If the server does not pass that check, the dispatcher will not start. ## Local Mode and Worker Backends The README states that Workers can run directly on the dispatcher host instead of in per-project containers, which it calls local mode, and that Docker is not required for this. The repository contains a dispatch.local.example.yaml file alongside dispatch.example.yaml and dispatch_mock.yaml, which suggests three configuration paths: standard dispatch, local dispatch, and a mock dispatcher for testing. The README does not document the contents of dispatch.local.example.yaml or the exact keys required for local mode, so anyone choosing that path should read the file directly before assuming parity with the Docker setup. Supported worker backends are Claude Code, Codex, and Pi. That list is short and specific. If your organization standardizes on a different LLM provider or a self-hosted model without one of these three backends, Cairn will not run out of the box. The README does not describe an adapter interface or a plugin system for adding backends, so the practical choice is between the three supported options. The Dockerfile shows the build uses uv with a frozen lockfile and the Aliyun PyPI mirror, and sets the timezone to Asia/Shanghai. The mirror choice is a detail that matters for build reliability in some networks and is easy to override if needed. ## Where Cairn Is the Wrong Tool Cairn is designed for problems with a clear origin and a clear goal. If you cannot state both, the engine has nothing to search. A task where success is subjective, or where the goal shifts as you learn more, does not fit the fact-intent model without someone continuously injecting Hints to redirect the search. Hints exist for exactly this, but the README does not describe how a Hint interacts with an already-claimed Intent or whether a Hint can cancel in-flight work. The engine also assumes an unknown path. For problems where the steps are known and repeatable, a predefined workflow or a simple script will be cheaper and more predictable. Cairn generates tasks at runtime from the graph's current state, which means the task sequence is not reproducible in the way a fixed pipeline is. That is the trade-off: flexibility in exchange for determinism. Teams that need audit trails of exactly which action ran in which order should look elsewhere. The README does not document rollback, checkpointing, or how to resume a search after a crash. It does not describe cost controls for LLM calls, which matters because every Explore task consumes tokens and the graph can generate many intents. The README also does not state how many concurrent workers a single dispatcher can manage, or what happens when a worker container fails mid-task. These are real gaps for anyone planning a production deployment. The hackathon result is impressive, but a competition run and a long-lived deployment have different failure profiles. ## How Cairn Differs from Agent Frameworks with Fixed Roles The most direct alternative is an agent framework that ships with predefined roles and a fixed workflow, such as a planner-executor-reviewer loop. In that model, the developer decides the stages and the framework routes work between them. Cairn inverts this: the developer provides origin and goal, and the engine derives tasks from the state of the graph. There are no job descriptions. A Worker's next task depends on what Facts and Intents currently exist on the board. The difference shows up in how you debug. With a fixed-role framework, you can trace a known sequence. With Cairn, you inspect the graph. The README's claim that agents coordinate exclusively through the shared board means the graph is the single source of truth, which is a cleaner debugging surface than inter-agent messages, but it also means the graph must be read to understand what happened. The README does not describe a UI beyond the runtime screenshot, so graph inspection likely means querying the server's API on port 8000. A second alternative is a general-purpose LLM agent with tool use and no search structure. That approach works for short tasks but does not maintain a persistent, growing representation of progress. Cairn's fact-intent graph persists across tasks and across worker restarts within a project, which is the property that lets multiple workers contribute to one problem without direct communication. ## Licence and Upgrade Cost Cairn is licensed under AGPL-3.0. That is a strong copyleft licence with a network clause. If you modify Cairn and offer it as a network service, the AGPL requires you to make the modified source available to users of that service. For internal use where you do not distribute the software and do not expose a modified version over a network, the obligation is narrower, but the boundary depends on your deployment. This is not legal advice; consult your own counsel before shipping a modified Cairn as a service. The AGPL choice is consistent with the project's positioning as a general engine rather than a commercial product. It also means that if your organization forbids AGPL dependencies, Cairn is off the table unless you obtain a separate licence, which the README does not mention. On upgrades: the repository's most recent release is v0.2.1 from 2026-05-10, preceded by v0.2.0 on 2026-05-05 and v0.1.0 on 2026-05-03. The last push to the repository was on 2026-09-07. The release cadence shows a burst of three releases in eight days in early May, followed by a gap. The README does not document a migration path between versions or a changelog, so upgrading from v0.1.0 to v0.2.x means reading the diff or the release notes. The Dockerfile uses a frozen lockfile, which means a rebuild will reproduce the same dependency set until the lockfile changes. If you pin to a release tag, you avoid surprise breakage; if you track main, you take on whatever landed between releases. ## Conclusion Cairn suits engineers who need an autonomous search engine for problems with a clear origin, a clear goal, and an unknown path, and who are comfortable with Python 3.12+, Docker, and the AGPL-3.0 licence. It is not for teams that need predefined agent roles, deterministic workflows, or permissive licensing. Before adopting it, verify that your LLM backend matches one of the three supported worker backends (Claude Code, Codex, or Pi), and read dispatch.example.yaml to confirm the configuration keys your deployment needs. ## FAQ ### What is Cairn? Cairn is a general-purpose AI problem-solving engine that searches for a path through an unknown state space given an origin and a goal. It is built on a Blackboard Architecture with a fact-intent graph and was validated first on autonomous penetration testing. ### How do you install Cairn? The README describes two paths: Docker Compose, which starts cairn-server on port 8000 and cairn-dispatcher after a health check, and local mode, which runs workers on the dispatcher host without Docker. Both require pulling the worker container image ghcr.io/oritera/cairn-worker-container:latest. ### Which LLM backends does Cairn support? The README lists three supported worker backends: Claude Code, Codex, and Pi. The README does not describe an adapter interface for adding other backends. ### What licence is Cairn released under? Cairn is licensed under AGPL-3.0, which includes a network clause requiring source disclosure if you offer a modified version as a network service. The README does not mention an alternative commercial licence. ### Does Cairn require Docker? Docker is required for container execution only. The README states that local mode runs Workers directly on the dispatcher host and does not require Docker. ## Sources - [Issues](https://github.com/oritera/Cairn/issues) - [License: AGPL-3.0](https://github.com/oritera/Cairn/blob/main/LICENSE) - [oritera/Cairn on GitHub](https://github.com/oritera/Cairn) - [README](https://github.com/oritera/Cairn/blob/main/README.md) - [Releases](https://github.com/oritera/Cairn/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oritera-cairn