Octomus Agent

Your repository's next improvement, ready for review.

Octomus is a self-hosted service for one operator and one or more repositories. It discovers improvements, has independent agents review the proposals, executes accepted work through Codex or OpenCode, verifies the result, and delivers a pull request. A cycle may reject everything and do nothing. The operator decides what merges.

Maintenance delivery is an opt-in exception: a small, reviewed and verified maintenance pull request may be squash-merged only when fresh GitHub checks and repository protections allow it. It requires the separate maintenance merge setup.

This image uses synthetic browser-test data.

Operating model

• Planning grounds proposals in the repository, its instructions, history and owned pull requests. External pull requests are read-only targets.
• Each task has its own checkout, a fresh full-diff review and bounded verification. Durable state lets the service recover interrupted work and reconcile publication.
• Docker is the default boundary: runners and verification commands run in short-lived, non-root sandboxes without the GitHub credential. A dedicated VM can run with --sandbox off; its service account and host are then the boundary.

Read the threat model and sandbox guide before running repository content.

Quick start

For prerequisites, installation and the first run, follow Getting started. In short:

1. Deploy the Docker stack or the dedicated-VM service.
2. Sign in the runner and open the loopback dashboard through SSH.
3. Enter and save the repository, routes and verification commands.
4. Check the saved configuration, then start with Run an audit or Run once.

The dashboard starts paused. Session admissions are operating limits, not dollar budgets; see cost and usage.

Documentation

Document	Use it for
Getting started	Prerequisites and the first run
Deployment	Docker/VM installation, operations, recovery, backups, CLI and API
Configuration	Saved policy fields, routes, checks and limits
Model routing	Codex and OpenCode route setup
Configuration example	Complete saved-policy shape and defaults
Architecture	Durable runtime and design contract
Sandbox	Isolation lifecycle, egress and self-test
Threat model	Trust boundaries and residual risk
Run evidence	RunEvidenceV1 export and its limits
Slack and Discord chat	Talk to Octomus from chat: commands, alerts and the daily digest
Cost

Security and contribution

Repository content, dependencies and model output are untrusted. Keep the dashboard on loopback behind SSH, use a random operator token and restrict the GitHub token to this repository. Report vulnerabilities privately using SECURITY.md.

Contribution rules and the repository map are in CONTRIBUTING.md and AGENTS.md. License: Apache-2.0.