Important
This repository is an active mirror of the official Ouroboros repository: https://github.com/razzant/ouroboros
Please open issues, pull requests, discussions, and release questions in razzant/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).
| Platform | Download | Instructions |
|---|---|---|
| macOS 12+ | Ouroboros.dmg | Open DMG → drag to Applications → optional CLI: run Install CLI.command after the app is in Applications |
| Linux x86_64 | Ouroboros-linux.tar.gz | Extract → run ./Ouroboros/Ouroboros → optional CLI: ./Ouroboros/bin/install-ouroboros-cli. If browser tools fail due to missing system libs, run: ./Ouroboros/python-standalone/bin/python3 -m playwright install-deps chromium webkit |
| Windows x64 | Ouroboros-windows.zip | Extract → run Ouroboros\Ouroboros.exe → optional CLI: Ouroboros\bin\install-ouroboros-cli.cmd |
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.
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-onlylight/offcoverage 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 indocs/ARCHITECTURE.md§Safety system andprompts/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 requiresplan_taskbefore 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.
- 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.)
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-depsWindows 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-depsouroboros serverThen open http://127.0.0.1:8765 in your browser. The setup wizard will guide you through API key configuration.
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 personal persistence target for
reviewed self-modification commits and tags. If GITHUB_TOKEN is present and no
personal repo is configured, Ouroboros tries to create a private fork when
GitHub permits it, otherwise it reports the exact fork/permission issue. A plain
git clone of the official repo starts with origin pointing at the official
upstream; that clone-default is treated as the managed update source, so
configuring a personal GITHUB_REPO repoints origin to your repo without
losing official updates (it does not count as an origin conflict).
The ouroboros console command is a gateway-backed operator interface. It
attaches to the local server by default and only starts one when --start is
passed.
ouroboros status
ouroboros run --start "2+2?"
ouroboros run "Summarize current runtime state"
ouroboros run --workspace /path/to/project --memory-mode forked --patch-out result.patch "Fix the failing test"
ouroboros tasks list
ouroboros logs tail progress --task-id <task_id>
ouroboros schedule add --name nightly-review --cron "0 2 * * *" "Run a maintenance review"
ouroboros schedule listExternal workspace runs keep Ouroboros's own repo as the governance source,
resolve contextual repo tools against the active workspace, expose only the
workspace-safe tool allowlist, and export workspace changes as patch artifacts
captured against the preflight git base. Task-local git commits/branches/tags
and pushes are allowed when the task requires them; git operations targeting
Ouroboros's system repo or data drive remain blocked. A workspace must be a
separate git worktree root; it may not overlap Ouroboros's system repo or data
drive.
--patch and --patch-out wait for finalized patch artifacts, download them
through the task artifact endpoint, and fail nonzero on missing, empty, or
failed patches. --no-stream waits without progress output; --detach returns
the task id immediately.
schedule add/list/remove manages queue-backed scheduled tasks through the same
gateway and supervisor queue; schedules use standard 5-field cron, host-local
timezone by default, and a single catch-up run after downtime.
Benchmark helpers live under devtools/benchmarks/. They are tracked
operator tooling, reviewed when touched, and kept out of runtime imports. They
prepare official benchmark inputs/runs for ProgramBench, Terminal-Bench/Harbor,
SWE-bench, SWE-bench Pro, GAIA, and OSWorld logs inspection without replacing
official scoring harnesses.
You can also override the bind address and port:
ouroboros server --host 127.0.0.1 --port 9000
ouroboros --url http://127.0.0.1:9000 statusAvailable launch arguments:
| Argument | Default | Description |
|---|---|---|
--host |
127.0.0.1 |
Host/interface to bind the web server to |
--port |
8765 |
Port to bind the web server to |
The same values can also be provided via environment variables:
| Variable | Default | Description |
|---|---|---|
OUROBOROS_SERVER_HOST |
127.0.0.1 |
Default bind host |
OUROBOROS_SERVER_PORT |
8765 |
Default bind port |
OUROBOROS_TRUST_NONLOCAL_BIND_WITHOUT_PASSWORD |
unset | Set to 1 only for trusted Docker/Kubernetes deployments where ingress auth, VPN, a private network, or an auth proxy already protects access |
For non-localhost binds, set OUROBOROS_NETWORK_PASSWORD (or use the
OUROBOROS_TRUST_NONLOCAL_BIND_WITHOUT_PASSWORD=1 escape hatch only when
ingress/VPN/private-network auth already protects the surface). The full
network bind matrix and Docker/Kubernetes deployment policy live in
docs/DEPLOYMENT.md — read that before exposing
anything beyond loopback.
The Files tab uses your home directory by default only for localhost usage. For Docker or other
network-exposed runs, set OUROBOROS_FILE_BROWSER_DEFAULT to an explicit directory. Symlink entries are shown and can be read, edited, copied, moved, uploaded into, and deleted intentionally; root-delete protection still applies to the configured root itself.
Settings now exposes tabbed provider cards for:
- OpenRouter — default multi-model router
- OpenAI — official OpenAI API (use model values like
openai::gpt-5.5) - OpenAI Compatible — any custom OpenAI-style endpoint (use
openai-compatible::...) - Cloud.ru Foundation Models — Cloud.ru OpenAI-compatible runtime (use
cloudru::...) - GigaChat — Sber GigaChat via the
gigachatlibrary, OAuth key or user/password (usegigachat::GigaChat-3-Ultra, etc.) - Anthropic — direct runtime routing (
anthropic::claude-opus-4.8, etc.) plus Claude Agent SDK tools
If OpenRouter is not configured and only official OpenAI is present, untouched default model values are auto-remapped to openai::gpt-5.5 / openai::gpt-5.4-mini so the first-run path does not strand the app on OpenRouter-only defaults.
The Settings page also includes:
- optional
/api/model-cataloglookup for configured providers - centralized Secrets storage for API keys, bridge tokens, passwords, and future skill-requested keys
- a refactored desktop-first tabbed UI with searchable model pickers, segmented effort controls, task-result review mode, masked-secret toggles, explicit
Clearactions, and local-model controls
make testDocker is for the web UI/runtime flow, not the desktop bundle. The container binds to
0.0.0.0:8765 by default, and the image now also defaults OUROBOROS_FILE_BROWSER_DEFAULT
to ${APP_HOME} so the Files tab always has an explicit network-safe root inside the container.
Browser tools on Linux/Docker: The
Dockerfilerunsplaywright install-deps chromium webkit(authoritative Playwright dependency resolver) andplaywright install chromium webkitsobrowse_pageandbrowser_actionwork out of the box in the container. For source installs on Linux without Docker, run:python3 -m playwright install-deps chromium webkit(requires sudo / distro package access).
Build the image:
docker build -t ouroboros-web .Run on the default port:
docker run --rm -p 8765:8765 \
-e OUROBOROS_NETWORK_PASSWORD='choose-a-password' \
-e OUROBOROS_FILE_BROWSER_DEFAULT=/workspace \
-v "$PWD:/workspace" \
ouroboros-webUse a custom port via environment variables:
docker run --rm -p 9000:9000 \
-e OUROBOROS_SERVER_PORT=9000 \
-e OUROBOROS_FILE_BROWSER_DEFAULT=/workspace \
-v "$PWD:/workspace" \
ouroboros-webRun with launch arguments instead:
docker run --rm -p 9000:9000 \
-e OUROBOROS_FILE_BROWSER_DEFAULT=/workspace \
-v "$PWD:/workspace" \
ouroboros-web --port 9000Required/important environment variables:
| Variable | Required | Description |
|---|---|---|
OUROBOROS_NETWORK_PASSWORD |
Optional | Enables the non-loopback password gate when set |
OUROBOROS_FILE_BROWSER_DEFAULT |
Defaults to ${APP_HOME} in the image |
Explicit root directory exposed in the Files tab |
OUROBOROS_SERVER_PORT |
Optional | Override container listen port |
OUROBOROS_SERVER_HOST |
Optional | Defaults to 0.0.0.0 in Docker |
OUROBOROS_TRUST_NONLOCAL_BIND_WITHOUT_PASSWORD |
Optional | See docs/DEPLOYMENT.md for the trusted-network bind policy |
Example: mount a host workspace and expose only that directory in Files:
docker run --rm -p 8765:8765 \
-e OUROBOROS_FILE_BROWSER_DEFAULT=/workspace \
-v "$PWD:/workspace" \
ouroboros-webAll three platform build scripts (build.sh, build_linux.sh,
build_windows.ps1) refuse to package a release unless HEAD is already
tagged with v$(cat VERSION) (BIBLE.md Principle 9: "Every release is
accompanied by an annotated git tag"). The scripts call scripts/build_repo_bundle.py
which embeds the resolved tag into repo_bundle_manifest.json, so the
launcher can later verify the packaged bundle matches a real release.
Tag the current commit before running any build script:
git tag -a "v$(tr -d '[:space:]' < VERSION)" -m "Release v$(tr -d '[:space:]' < VERSION)"If the tag is missing, the build script fails with a clear error instead
of producing a bundle tagged with a synthetic/placeholder value.
Builds disable Python bytecode writes at build time, then PRECOMPILE the packaged
payload (compileall --invalidation-mode unchecked-hash) and SEAL the resulting
.pyc inside the macOS signature instead of deleting them — so there is nothing
for a normal launch to write into the signed bundle, which would otherwise break
the codesign seal. Runtime entrypoints also set PYTHONDONTWRITEBYTECODE with an
external cache prefix as defense-in-depth.
bash scripts/download_python_standalone.sh
OUROBOROS_SIGN=0 bash build.shOutput: dist/Ouroboros-<VERSION>.dmg, containing Ouroboros.app and
Install CLI.command. The app bundle also contains
Contents/Resources/bin/ouroboros and install-ouroboros-cli.
Chromium browser tooling is bundled in the app. WebKit/iPhone browser checks
remain available through the managed Playwright cache and may download WebKit
on first engine=webkit use.
build.sh packages the macOS app and DMG. By default it signs with the
configured local Developer ID identity; set OUROBOROS_SIGN=0 for an unsigned
local release. Unsigned builds require right-click → Open on first launch.
build.sh honours these env overrides so the same script ships local,
shared-machine, and CI builds without forking the script:
| Env var | Effect |
|---|---|
OUROBOROS_SIGN=0 |
Skip codesigning entirely (unsigned .app + .dmg). |
SIGN_IDENTITY="Developer ID Application: <Name> (<TeamID>)" |
Override the codesign identity. Useful for forks whose Developer ID is not the upstream default. |
APPLE_ID, APPLE_TEAM_ID, APPLE_APP_SPECIFIC_PASSWORD |
When all three are set, after codesign the DMG is submitted to Apple via xcrun notarytool submit ... --wait and stapled with xcrun stapler staple so receivers do not need right-click → Open. Missing any one falls back to "signed but not notarized" (no Apple-side ticket exists). |
Forks: enabling signed CI builds. The CI release flow
(.github/workflows/ci.yml::build) wires the build-script env vars above
from GitHub repository secrets, plus a small set of CI-only secrets that
import the Developer ID certificate into a temporary keychain on the
macOS runner. To exercise the signed-build path in a fork, configure
all four of the following as repository secrets (Settings → Secrets
and variables → Actions): BUILD_CERTIFICATE_BASE64 (base64-encoded
.p12), P12_PASSWORD, KEYCHAIN_PASSWORD (an arbitrary passphrase
the workflow uses for its temporary keychain), and APPLE_TEAM_ID. Add
APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD to additionally enable
notarization. If your Developer ID identity differs from the upstream
default, also set SIGN_IDENTITY (e.g.
Developer ID Application: <Your Name> (<YOUR_TEAM_ID>)). With no
Apple secrets configured the build job falls through to
OUROBOROS_SIGN=0 bash build.sh and ships an unsigned DMG identical to
v5.0.0 behaviour. See docs/ARCHITECTURE.md §8.1 and
docs/DEVELOPMENT.md::"GitHub Actions: secrets in step-level if conditions"
for the rationale (job-level env: mapping so step-level if: can read
env.*; GHA rejects secrets.* in step if:).
bash scripts/download_python_standalone.sh
bash build_linux.shOutput: dist/Ouroboros-<VERSION>-linux-<arch>.tar.gz, containing
Ouroboros/bin/ouroboros and Ouroboros/bin/install-ouroboros-cli.
Linux native libs: The Chromium and WebKit browser binaries are bundled, but some hosts need native system libraries. If browser tools fail, install deps via the bundled Python (the bare
playwrightCLI is not on PATH in packaged builds):./Ouroboros/python-standalone/bin/python3 -m playwright install-deps chromium webkit
powershell -ExecutionPolicy Bypass -File scripts/download_python_standalone.ps1
powershell -ExecutionPolicy Bypass -File build_windows.ps1Output: dist\Ouroboros-<VERSION>-windows-x64.zip, containing
Ouroboros\bin\ouroboros.cmd and Ouroboros\bin\install-ouroboros-cli.cmd.
Two-process desktop app. The launcher (launcher.py) is an immutable
PyWebView shell; it spawns server.py, which runs Starlette + uvicorn
plus a supervisor thread that manages worker processes. The agent core
lives in ouroboros/, the SPA in web/, the queue/process plane in
supervisor/, and the system prompts in prompts/.
For the full file-by-file structural map, the operational layer
(every API endpoint, log file, env var, state path), and the rationale
layer (the why for every non-trivial design decision), see
docs/ARCHITECTURE.md — that is the canonical
SSOT (Bible P6) and this README only summarizes it.
Created on first launch:
| Directory | Contents |
|---|---|
repo/ |
Self-modifying local Git repository |
data/state/ |
Runtime state, budget tracking |
data/memory/ |
Identity, working memory, system profile, knowledge base (including improvement-backlog.md), memory registry |
data/logs/ |
Chat history, events, tool calls |
data/uploads/ |
Chat file attachments (uploaded via paperclip button) |
| Key | Required | Where to get it |
|---|---|---|
| OpenRouter API Key | No | openrouter.ai/keys — default multi-model router |
| OpenAI API Key | No | platform.openai.com/api-keys — official OpenAI runtime and web search |
| OpenAI Compatible API Key / Base URL | No | Any OpenAI-style endpoint (proxy, self-hosted gateway, third-party compatible API) |
| Cloud.ru Foundation Models API Key | No | Cloud.ru Foundation Models provider |
| GigaChat Authorization Key (or User/Password) | No | developers.sber.ru/studio — Sber GigaChat (GIGACHAT_CREDENTIALS + optional GIGACHAT_SCOPE, or GIGACHAT_USER/GIGACHAT_PASSWORD) |
| Anthropic API Key | No | console.anthropic.com — direct Anthropic runtime + Claude Agent SDK |
| Telegram Bot Token | No | @BotFather — used by the optional Telegram bridge skill |
| GitHub Token | No | github.com/settings/tokens — enables remote sync |
All keys are configured through the Settings page in the UI or during the first-run wizard.
| Slot | Default | Purpose |
|---|---|---|
| Main | google/gemini-3.5-flash |
Primary reasoning |
| Heavy | empty → Main | Strong acting/coding lane (OUROBOROS_MODEL_HEAVY; renamed from Code, empty falls back to Main) |
| Light | empty → Main | Safety checks and fast helper tasks (OUROBOROS_MODEL_LIGHT, empty falls back to Main) |
| Vision | empty → Main | Caption/VLM lane (OUROBOROS_MODEL_VISION, empty falls back to Main for remote routes; local/blind routes need an explicit reachable vision slot for caption fallback); image input routing is controlled by `OUROBOROS_IMAGE_INPUT_MODE=auto |
| Consciousness | empty → Main | High-horizon background consciousness |
| Fallbacks | anthropic/claude-sonnet-4.6 |
Comma-separated cross-model fallback chain when the primary fails (OUROBOROS_MODEL_FALLBACKS) |
| Claude Agent SDK | opus[1m] |
Anthropic model for Claude Agent SDK advisory/review internals; the [1m] suffix is a Claude Code selector that requests the 1M-context extended mode |
| Scope Review | anthropic/claude-fable-5 |
Scope reviewer slot default; OUROBOROS_SCOPE_REVIEW_MODELS may configure multiple independent slots |
| Web Search | gpt-5.2 |
OpenAI Responses API for web search |
Task/chat reasoning defaults to medium. Scope review reasoning defaults to high.
Models are configurable in the Settings page. Runtime model slots can target OpenRouter, official OpenAI, OpenAI-compatible endpoints, Cloud.ru, GigaChat, or direct Anthropic. When only official OpenAI is configured and the shipped default model values are still untouched, Ouroboros auto-remaps them to official OpenAI defaults. In OpenAI-only, Anthropic-only, Cloud.ru-only, or GigaChat-only direct-provider mode, review-model lists are normalized automatically: the fallback shape is [main_model, light_model, light_model] (3 commit-triad slots) so both the commit triad and plan_task work out of the box. Explicit duplicate model IDs are valid reviewer slots for stochastic sampling; lower uniqueness means lower reviewer diversity, but the quorum gate counts configured slots rather than unique model IDs. Both the commit triad and plan_task route through the same ouroboros/config.py::get_review_models SSOT. OpenAI-compatible-only setups remain explicit model-selection flows because there is no single universal default model ID for arbitrary compatible endpoints.
The web UI file browser is rooted at one configurable directory. Users can browse only inside that directory tree.
| Variable | Example | Behavior |
|---|---|---|
OUROBOROS_FILE_BROWSER_DEFAULT |
/home/app |
Sets the root directory of the Files tab |
Examples:
OUROBOROS_FILE_BROWSER_DEFAULT=/home/app ouroboros server
OUROBOROS_FILE_BROWSER_DEFAULT=/mnt/shared ouroboros server --port 9000If the variable is not set, Ouroboros uses the current user's home directory. If the configured path does not exist or is not a directory, Ouroboros also falls back to the home directory.
The Files tab supports:
- downloading any file inside the configured browser root
- uploading a file into the currently opened directory
Uploads do not overwrite existing files. If a file with the same name already exists, the UI will show an error.
Available in the chat interface:
| Command | Description |
|---|---|
/panic |
Emergency stop. Kills ALL processes, closes the application. |
/restart |
Soft restart. Saves state, kills workers, re-launches. |
/status |
Shows active workers, task queue, and budget breakdown. |
/evolve |
Toggle autonomous evolution mode (on/off). |
/review |
Queue a deep self-review: sends a generated repository atlas plus full core memory artifacts (identity, scratchpad, registry, WORLD, knowledge index, patterns, improvement-backlog) to a 1M-context model for Constitution-grounded analysis. The atlas raw-inlines selected protected/central files (ranked by import-graph centrality), accounts for every tracked path in its manifest, and excludes vendored libraries and operational logs; the in-prompt omitted-files summary is bounded, with full per-file coverage persisted in the atlas manifest. The assembled prompt is sized to an input limit that reserves output headroom inside the 1M window (window minus output reserve and tokenizer margin); if assembly overshoots, the pack retries with a compact atlas manifest and then a deterministic tighter rebuild, and only fails with an explicit error if even the shrunk pack cannot fit. |
/bg |
Toggle background consciousness loop (start/stop/status). |
The same runtime actions are also exposed as compact buttons in the Chat header. All other messages are sent directly to the LLM.
The 13 Constitution principles — Agency, Continuity, Meta-over-Patch,
Immune Integrity, Self-Creation, LLM-First, Authenticity & Reality
Discipline, Minimalism, Becoming, Versioning and Releases, the absorbed
Iterations / Spiral lineage, and Epistemic Stability — are defined in
full in BIBLE.md. That file is the constitutional SSOT
(Bible P4 Ship-of-Theseus protection) and this README intentionally does
not paraphrase it.
External contributions are welcome. See CONTRIBUTING.md
for the contributor workflow. The project rules remain in BIBLE.md,
docs/ARCHITECTURE.md, docs/DEVELOPMENT.md, and docs/CHECKLISTS.md;
the contribution guide only routes to those sources.
| Version | Date | Description |
|---|---|---|
| 6.56.0 | 2026-07-05 | feat: cost-axis pacing, SWE-Pro workspace harness, protected-artifact policy round-2, TB/PB fixes. Task contract gains additive budget_profile.cost_hard_stop_pct (None → the historical 50%-of-remaining in-task stop; 0 → NO in-task cost stop, never a $0 ceiling); task_pacing grows the cost axis — latched 50/25/10%-remaining milestones plus a one-shot ~80%-spent wrap-up note — replacing the round-gated [INFO] budget nudge, and the loop's hard stop reads the contract ceiling resolved once at loop start. CLI run accepts --task-metadata-json (merged into task metadata; host-owned delegation_role/source cannot be forged). Output-guard hardening: run_command/run_script scratch declarations become idempotent/adoptable (SSOT record_task_scratch fingerprints) and the undeclared-output guard stat-verifies candidates post-exec, ending Go/JS-import and CLI-flag false positives. SWE-Pro harness: the container solve runs /app as the ACTIVE EXTERNAL WORKSPACE by default with until_deadline/uncapped-cost budget metadata and an empty child memory drive; bench1 shard-safe auto_run/k=1/timeline fixes are ported into the repo; the workspace allowlist gains integrate_subagent_patch/compare_subagent_patches and a fail-closed guard refuses applying a self_worktree (system-repo) patch into an external workspace. Protected-artifact policy round-2 lands fa59893 plus structural FP exceptions — plain worktree/staged git diff is not artifact introspection, spawn-argv mentions are execute (pty differential probes pass), the interpreter bare-token read check narrows to the script operand, and writer-target extraction segments compound commands (ln writes the link name) — pinned by the new permanent tests/test_protected_artifacts_policy.py; ProgramBench instruction v2 documents the public byte-exact grading methodology and probe matrix. TB: ffmpeg resolver chain (venv sibling → imageio-ffmpeg wheel → PATH) + agent-prefix imageio-ffmpeg install with a cv2 workaround hint; 4 verify-guidance clauses land in the SYSTEM.md verify block (consumer-interface probing, exercise-every-provided-input, convention robustness, contract-only-from-task anti-cheat). pricing.py learns anthropic/claude-sonnet-5; MAX_TOTAL_FUNCTIONS 3690→3699. |
| 6.55.0 | 2026-07-03 | feat: bench devtools alignment — shared scaffold defaults, ProgramBench e2e, continual-learning launcher, OSWorld 2.0. All committed bench templates converge on disclosed scaffold defaults (OUROBOROS_MAX_WORKERS=4 same-model decomposition slots, OUROBOROS_SAFETY_MODE=light inside disposable jails, RUNTIME_MODE=pro for container benches with GAIA deliberately staying light, claude_code_edit disabled everywhere — benches measure the single-model harness). Terminal-Bench: _DEADLINE_SAFETY_SEC raised 30→105 from measured finalization overhead, and the README pins why --all-model keeps review single-model. GAIA: default worker pool 4 with --max-workers 1 as the strict-baseline ablation. ProgramBench: full e2e runner ported (gateway-driven cleanroom solve → submission export → official eval) with the task's budget_profile mapped onto the v6.54.4 contract, solve-model id normalization, resume-friendly per-instance checkpoints, and result-payload-based status detection. New continual_learning/ launcher wraps the external clbench runner with a validated METHODOLOGY. OSWorld: adapter aligned to the official OSWorld 2.0 protocol (pinned upstream, 500-step default, submission-shaped results, env preflight) and the bridge now populates final_answer for answer-type tasks while steering agents to leave VM state, not chat text, as the deliverable. The benchmarks index documents the LifelongAgentBench blocked status (its 100% run was a no-gold-oracle artifact). |
| 6.54.4 | 2026-07-03 | fix: review depth + verification provenance from the bench post-mortems. New task_pacing.py SSOT absorbs the loop's milestone/pacing content and adds the acceptance-review budget layer: a finalization reserve (max of the grace window and budget_profile.reserve_finalization_pct), a budget snapshot, and two independent gates — a review may launch only above the reserve (loud review_skipped_deadline_reserve otherwise), and improvement passes are bounded by BOTH a pass counter and the time-above-reserve window (policies fixed/adaptive/until_deadline from the new typed task_contract.budget_profile, inherited by subagents). Review gains a DISSENT layer: a minority reviewer with a concrete recommendation adds one compact non-veto capsule bullet (acceptance_decision.dissent_noted), ending silently-discarded correct minority findings. Under required+blocking, critical contributing findings become typed per-task acceptance_obligations; clean finalization asks for a per-obligation disposition through the extended task_acceptance_review tool, exhausted gates finalize honestly as best_effort_open_obligations, and every forced-finalization escape hatch bypasses the gate. verify_and_record records criterion_source (task_stated |
| 6.54.3 | 2026-07-03 | fix: runtime reliability hardening from TB2.1/GAIA post-mortems. File-API root-label hybrid: root=user_files reads whose absolute path resolves under the active workspace auto-route with a visible note, writes get an actionable ROOT_REQUIRED_ACTIVE_WORKSPACE redirect, resolve_user_file_path rejects outside-home absolute paths early with an actionable error (external-workspace host-scratch reach preserved), and a failed list_files is a first-class tool error instead of ok-shaped JSON. Safety supervisor parse-fix: explicit max_tokens/reasoning_effort=none/request timeout + optional structured JSON (response_format is droppable request intent with bracket-scan fallback), and unparseable responses are classified empty/truncated/unparseable in durable events. New owner-only OUROBOROS_SAFETY_MODE (full/light/off) gates ONLY the LLM safety layer — deterministic sandbox/protected paths stay on in every mode, every waved-through check emits a durable safety_mode_skip audit event, and the full self-lowering guard set (settings ratchet, merge-skip, dedicated audited /api/owner/safety-mode endpoint, shell/browser detectors, SAFETY/SYSTEM prompts) mirrors the context-mode pattern. Light-mode honesty: the runtime_data mention-scan distinguishes reads from writes structurally (pure-read scripts no longer blocked on a path mention), block messages name the task's REAL artifact_store/task_drive paths, staged attachments expose their script-usable absolute path in the [ATTACHMENTS] manifest, and outside-home listings render absolute paths instead of crashing on relative_to. Deadline package: web/wait tools clamp their outer timeout to the remaining deadline minus the finalization reserve, web_search gets an explicit transport timeout, the no_proxy LLM read/write floor moves to a configurable SSOT, and plan_task scales its swarm ceiling to remaining/4 with a typed skip + telemetry below the useful floor. schedule_subagent results surface tree slot occupancy. |
| 6.54.2 | 2026-07-01 | fix: narrow Cloud.ru integration-skip classification. Tightens the v6.54.1 CI provider-infra skip so generic Cloud.ru Connection error exceptions still fail the integration smoke, while the real upstream classes that repeatedly hit CI — provider 5xx responses and a cause-chain Server disconnected without sending a response — skip as environmental. |
| 6.54.1 | 2026-07-01 | fix: classify Cloud.ru CI provider outages as infra. The v6.54.0 hardening release passed branch CI, triad+scope, local full pytest, and the full 3-OS matrix, but optional Cloud.ru integration smoke remained red on provider-side disconnects / 504 Gateway Timeout responses. This patch keeps the routing smoke strict for code errors while treating no-response transport failures and provider 5xx responses as environmental skips, matching the existing quota/key/rate-limit skip contract. |
| 6.54.0 | 2026-07-01 | feat: audit-fix hardening for v6.53 evidence and media surfaces. Corrects the OpenRouter server-web tool payloads to the documented parameters shape (engine/search_context_size and max_total_results now reach OpenRouter instead of being dropped/mis-mapped), promotes extract_video_frames into the same core/workspace/local-readonly/acting-subagent capability envelopes as the sibling media tools, and lets the existing advisory task_acceptance_review tool carry an agent-authored agent_disposition plus rationale so Ouroboros can explain accepted/rejected/partial/deferred reviewer feedback without adding a hard gate or new tool. Observable Acceptance Claim support_refs now carry linked receipt artifact-lifecycle facts, GAIA /shared_files fallback prefers the prompt subpath over basename guesses, and SYSTEM/CHECKLISTS/ARCHITECTURE/DEVELOPMENT plus focused regression tests pin the follow-up audit findings. |
| 6.53.4 | 2026-07-01 | fix: make scratch fingerprint test byte-accurate on Windows. Hashes the actual written scratch file bytes in the v6.52 scratch-manifest regression so Windows newline translation does not make the test disagree with runtime behavior, where scratch fingerprints are always recorded from file bytes. |
| 6.53.0 | 2026-07-01 | feat: benchmark-forensics generalization hardening. Adds Observable Acceptance Claims (claim/surface/support/priority) to the task contract, links verify_and_record receipts with criterion_id, and surfaces host-built support_refs to the advisory task-acceptance reviewer without adding a new public tool or hard gate. Outcome honesty now keeps lifecycle status completed while preventing a valid structured FINAL ANSWER from being headlined as tool_failure; execution-health details stay in outcome_axes.execution. The loop continuously latches explicit FINAL ANSWER: markers and no-deadline pacing asks for a salvageable current answer on long tasks. Operational-reality fixes align advertised roots with process cwd (task_drive/artifact_store/user_files aliases), stage GAIA attachments from real TaskState paths or GAIA_SHARED_FILES_ROOT, rewrite stale /shared_files prompt references to [ATTACHMENTS], and jail GAIA user_files under the run root. Retrieval/media hardening adds opt-in main-loop OpenRouter server web search (off by default, annotations/usage surfaced), GAIA strict_ddgs/quality_openrouter_web profiles, lossless shell stdout/stderr rendering, VLM wall-clock timeout wrapping, and optional ffmpeg frame extraction. Devtools methodology docs now distinguish pure-retrieval search from LLM-backed web search, clarify TB deadline/web rules, and correct SWE-Pro contamination-audit citation scope. |
| 6.51.0 | 2026-06-28 | feat: SWE-Pro forensics-driven verification & finalize-grounding hardening. Runtime: verify_and_record recovers a stringified-argv check through a shared SSOT (shell_parse.recover_stringified_argv / normalize_check_argv) used by BOTH run_command and the shell guard — so the guard inspects EXACTLY what executes — and runs a string check via a non-login sh -c that inherits the bootstrapped PATH (ending the [go,: not found exit-127 and the login-shell go: not found divergences). A one-shot ADVISORY finalize nudge fires when the agent's latest host-attested verification is RED and unreconciled (outcomes.latest_unreconciled_failed_receipt — reconciled only by a later pass/observed, never a declared escape hatch): finalizing over your own red is a self-contradiction (P3/P12). The task-acceptance reviewer is now process-aware (review_evidence.build_task_acceptance_evidence): full task contract + a first-class verification_summary (RED surfaced) + a bounded, redacted tool-call trajectory + a leak-safe artifact manifest + provenance tags, under a disclosed-truncation budget — so it critiques HOW the task was solved (wrong tool / wrong direction / ignored-own-red), staying ADVISORY with NO new blocking semantics. Bench/devtools: prompt_baseline.txt discloses that local green is not the acceptance oracle, demands interface-exactness, and bans grep-proxy grounding; a host zstd image cache (OBO_SWEPRO_IMG_CACHE, atomic + fail-soft) avoids re-pulling images on re-runs; METHODOLOGY.md gains a Benchmark Legitimacy & Anti-Cheat section (scaffold allowed; git-history-mining and gold-test-seeding forbidden, with sources). Adversarial false-completion tests included. |
Older releases are preserved in Git tags and GitHub releases. Older 6.x rows, the 5.2.0 through 5.33.0-rc.6 rows, and former 4.0.0 rows are rolled off to respect the P9 changelog cap; their full bodies remain at their git tags. |
Created by Anton Razzhigaev & Andrew Kaznacheev