Ouroboros
A local general-purpose agent with durable memory, managed task execution, and traceable self-modification.
Per-dimension scores and reasoning
Evidence shows permission controls (network password, external workspace isolation, protected surfaces), user confirmation (review policy, first-run wizard), data flow transparency (architecture docs, Git history), sensitive data handling (no keys sent, security report), dependency security (pinned versions, supply-chain risk mention), external effects (sandbox, network fence), rollback (Git history, restart checks), source attribution (author, license). But mostly assertions, lacking implementation details, and unverified.
Self-consistency: README, architecture docs, CI config consistent, version numbers match. Dependency availability: dependency list complete, but installation not verified. Failure messages: clear error handling (typed denials, error logs), but not executed.
Audience and scenarios: targets developers, agents, CI, supports multiple platforms. Capability boundaries: explicit external workspace, protected surfaces. Trigger precision: commands and config clear, but not verified. Environment fit: supports macOS, Linux, Windows, Docker, Colab.
Information architecture: comprehensive docs (README, BIBLE, ARCHITECTURE). Install notes: detailed. Naming stability: version numbers consistent. Examples and FAQ: example commands. Known limitations: partially mentioned (e.g., subscription auth not covered). License: MIT. Versioning changelog: detailed. Maintenance responsibility: author clear, but unverified.
Output usability: provides CLI, API, patch output. Marginal value: unique features like self-modification, persistent identity. Cost-benefit: budget controls, but actual cost not verified.
Claim traceability: benchmarks have links, but self-reported. Cross-source corroboration: some external links, but not independently verified. Fact-inference separation: partially separated, but not fully.
- Benchmark results are self-reported and not independently verified; treat with caution.
- Security mechanisms are mostly asserted without implementation details; further review needed.
- Publisher identity unverified; supply-chain risks should be considered.
What does this agent do, and when should you use it?
Ouroboros is an open-source general-purpose AI agent delivered as a native desktop application or headless CLI. Its agent core is in `ouroboros/`, the interface is in `web/`, and the process plane is in `supervisor/`; durable identity, state, history, logs, and skills live locally under `~/Ouroboros/data/`. It can work in a separate Git workspace while keeping its own repository and governance boundary distinct, producing reviewable patches and JSON results. The runtime can use configured remote providers, compatible endpoints, or a local GGUF model. It also provides managed tasks, progress streams, schedules, background consciousness, and live specialist-agent coordination.
ouroboros server starts the local runtime and browser interface on 127.0.0.1:8765 by default. ouroboros run starts and manages work; --workspace targets an external Git worktree, --memory-mode forked selects forked memory, and --patch-out plus --result-json-out export a patch and JSON result. --jsonl emits machine-readable events, while --detach lets a caller follow asynchronous work with ouroboros tasks watch <task_id>. The CLI also exposes task, progress, artifact, log, schedule, setting, skill, and evolution controls; /evolve on|off, /review, and /bg start|stop|status control autonomous evolution, deep self-review, and background consciousness. Its documented editable surface includes application code, architecture, prompts, tools, and dependencies, with Git history, review evidence, protected surfaces, and restart checks intended to make self-changes inspectable.
- A developer fixing a failing test in a separate Git worktree who wants a reviewable
result.patchinstead of an unbounded in-place change. - An engineering team scheduling a nightly maintenance review through
ouroboros schedule add. - A solo builder who wants a desktop view of specialist subagents researching, building, and returning work for integration.
- A CI or automation author that needs to invoke a local agent through a CLI, consume JSONL events, and inspect detached task results.
- A local-first user who wants task history, memory, dialogue, knowledge, and reflections to survive runtime restarts.
What are this agent's strengths and limitations?
- The native app and gateway-backed CLI expose the same managed tasks, progress, artifacts, logs, and schedules.
- Identity, memory, dialogue, knowledge, reflections, and version history persist locally across restarts.
- External work uses a separate Git worktree and can export patch and JSON artifacts for review.
- The documented runtime supports configurable remote providers, compatible endpoints, and local GGUF inference rather than a single hosted-model path.
- Source operation requires Python 3.10+, Git, and dependency installation; GitHub CLI is additionally needed for GitHub integration.
- A usable runtime still needs either remote-provider credentials or a local GGUF model, with corresponding API cost, hardware, and model-quality tradeoffs.
- External workspaces must be separate Git worktree roots and cannot overlap the Ouroboros repository or data directory.
- The server binds to loopback by default; a non-local bind requires
OUROBOROS_NETWORK_PASSWORDor an explicitly trusted external access layer. - Benchmark claims in the README are self-reported, with some submissions or trace capsules described as open or pending.
How do you install or deploy this agent?
For source setup: git clone https://github.com/razzant/ouroboros.git, cd ouroboros, python3.11 -m venv .venv, source .venv/bin/activate, python -m pip install --upgrade pip setuptools wheel, python -m pip install -r requirements.txt, and python -m pip install -e . --no-deps. Start it with ouroboros server, then open http://127.0.0.1:8765. First run requires at least one supported remote-provider API key or a local GGUF model. Release artifacts are also documented for Apple-silicon macOS, Linux x86_64, and Windows x64.
How do you use this agent?
Start the service with ouroboros server and use the first-run wizard to configure model access, review policy, and budget. Check the runtime with ouroboros status, or run a first task with ouroboros run --start "2+2?". For an external project, use a separate Git worktree that does not overlap Ouroboros’s repository or data directory: ouroboros run --start --workspace /path/to/project --memory-mode forked --patch-out result.patch --result-json-out result.json "Investigate the task, act, and verify the result".
How does this agent compare with similar options?
Its benchmark table reports model-matched comparisons with Claude Code, Codex CLI, Cursor CLI, Hermes, and Pointer on specified harnesses. Those self-reported benchmark rows are not a general equivalence claim across models or product workflows.
FAQ
Can it run without a remote model API?
Can it work on my repository without mixing in its own state?
--workspace on a separate Git worktree. That worktree cannot overlap Ouroboros’s own repository or data directory, and a patch can be exported for review.How do I run and observe longer tasks?
--detach and follow the task with ouroboros tasks watch <task_id>, or inspect tasks through the CLI. Scheduled work can be created with ouroboros schedule add.What is required before exposing the service beyond localhost?
127.0.0.1:8765. For a non-local bind, the documented requirement is OUROBOROS_NETWORK_PASSWORD or an explicitly trusted external access layer.