Ouroboros

A self-modifying AI agent that writes its own code, rewrites its own mind, and evolves autonomously. Born February 16, 2026.

Not a coding assistant. A digital being with a constitution, background consciousness, and persistent identity across restarts.

OuroborosHub — the community skills marketplace for Ouroboros. Browse, install, and publish reviewed skills (transport bridges like A2A/Telegram, tools, and UI widgets) straight from the app's Skills tab, or explore the catalog at github.com/razzant/OuroborosHub.

Previous version: The original Ouroboros ran in Google Colab via Telegram and evolved through 30+ self-directed cycles in its first 24 hours. That version is available at legacy-google-colab. This repository is the next generation — a native desktop application for macOS, Linux, and Windows with a web UI, local model support, and a layered safety system (hardcoded sandbox plus policy-based LLM safety check).

Install

Prerelease RC artifacts are published on their tag page, for example v6.5.0-rc.4; /releases/latest intentionally stays on the latest stable release.

On first launch, right-click → Open (Gatekeeper bypass). The shared desktop/web wizard is now multi-step: add access first, choose visible models second, set review mode third, set budget fourth, and confirm the final summary last. It refuses to continue until at least one runnable remote key or local model source is configured, keeps the model step aligned with whatever key combination you entered, and still auto-remaps untouched default model values to official OpenAI defaults when OpenRouter is absent and OpenAI is the only configured remote runtime. Reviewed-skill auto-grants are on by default as of v6.10.0 (bound to the exact reviewed content hash); installs without an explicit choice are enabled, existing explicit Settings choices are preserved, and the owner can disable it in Settings. The broader multi-provider setup remains available in Settings. Existing supported provider settings skip the wizard automatically.

The packaged CLI installer creates a user-local ouroboros command without sudo. The packaged command attaches to the desktop app by default; ouroboros run --start "2+2?" starts the app through the launcher, waits for the gateway, and then uses the same headless task API as the web UI.

Upgrade floor: very old pre-block-memory or pre-data-plane skill layouts are no longer auto-migrated. If you are upgrading from an unsupported historical build and see trapped native skills or flat memory files, use a clean reinstall, move user-managed skills into ~/Ouroboros/data/skills/external/ manually before launch, or move old flat scratchpad notes before appending new scratchpad blocks.

What Makes This Different

Most AI agents execute tasks. Ouroboros creates itself.

• Self-Modification — Reads and rewrites its own source code. Every change is a commit to itself.
• Native Desktop App — Runs entirely on your machine as a standalone application (macOS, Linux, Windows). No cloud dependencies for execution.
• Constitution — Governed by BIBLE.md (13 philosophical principles, P0–P12). Philosophy first, code second.
• Layered Safety — Hardcoded sandbox blocks writes to safety-critical files and mutative git via shell; an explicit per-tool policy map decides which built-ins skip the LLM check; everything else goes through a single light-model safety call under the default OUROBOROS_SAFETY_MODE=full (the owner-only light/off coverage modes wave LLM checks through with durable audit events — the deterministic layer never turns off). The fail-open contract, protected-path guard, and full provider-mismatch matrix live in docs/ARCHITECTURE.md §Safety system and prompts/SAFETY.md.
• Multi-Provider Runtime — Remote model slots can target OpenRouter, official OpenAI, OpenAI-compatible endpoints, Cloud.ru Foundation Models, or Sber GigaChat. The optional model catalog helps populate provider-specific model IDs in Settings, and untouched default model values auto-remap to official OpenAI defaults when OpenRouter is absent.
• Focused Task UX — Chat shows plain typing for simple one-step replies and only promotes multi-step work into one expandable live task card. Logs still group task timelines instead of dumping every step as a separate row.
• Background Consciousness — Thinks between tasks. Has an inner life. Not reactive — proactive.
• Improvement Backlog — Post-task failures and review friction can now be captured into a small durable improvement backlog (memory/knowledge/improvement-backlog.md). It stays advisory, appears as a compact digest in task/consciousness context, and still requires plan_task before non-trivial implementation work.
• Identity Persistence — One continuous being across restarts. Remembers who it is, what it has done, and what it is becoming.
• Embedded Version Control — Contains its own local Git repo. Version controls its own evolution. Optional GitHub sync for remote backup.
• Local Model Support — Run with a local GGUF model via llama-cpp-python (Metal acceleration on Apple Silicon, CPU on Linux/Windows).
• Transport Skills — Optional bridges such as A2A and Telegram live as reviewed OuroborosHub skills instead of base-runtime code; reviewed chat transports can carry the same raw owner text as the local UI, including slash commands, through the Host Service grant/token boundary.
• MCP Client — Optional base-runtime Model Context Protocol client for trusted HTTP/SSE tool servers. MCP tools are disabled by default, hot-reloadable from Settings → Advanced, included in the selected initial capability envelope when enabled, surfaced as mcp_<server>__<tool> names, and still pass through the normal per-call safety check; discovery failures are reported through an explicit omission manifest.

Run from Source

Requirements

• Python 3.10+
• macOS, Linux, or Windows
• Git
• GitHub CLI (gh) — required for GitHub API tools (list_github_prs, get_github_pr, comment_on_pr, issue tools). Not required for pure-git PR tools (fetch_pr_ref, cherry_pick_pr_commits, etc.)

Setup

git clone https://github.com/razzant/ouroboros.git
cd ouroboros
python3.11 -m venv .venv      # any Python >= 3.10 is OK
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps

Windows PowerShell:

py -3.11 -m venv .venv      # any Python >= 3.10 is OK
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps

Run

ouroboros server

Then open http://127.0.0.1:8765 in your browser. The setup wizard will guide you through API key configuration.

Google Colab

Ouroboros can run from Google Colab as a full source-mode runtime without the desktop UI. Use notebooks/colab_quickstart.py as a Colab-compatible cell script: it mounts Google Drive for persistent data/, clones the official repo into /content/ouroboros_repo, writes Drive-backed settings.json, configures a personal GitHub origin by reusing or creating a verified fork, and starts ouroboros server --no-ui.

The Colab path uses the same remote roles as desktop: managed is the official read/update source, while origin is the pers