A self-evolving agentic OS.
A new architecture for agent execution, built on operating-system principles, where agents can reshape their environment and the trajectory of their own work.
Octopus is an operating system for persistent agent work. Goals, permissions, runs, tools, context, and external events are explicit, durable records rather than state held inside a model loop. A small Rust kernel forms grants, admits artifact movements, and records them in an append-only ledger. Providers, channels, sensors, and tool rooms attach through registry-owned interfaces.
The macOS client brings these together in Home, Projects, Agents, and Tasks. You can talk by text or voice and grant tools for files, browsers, desktop applications, and connected services. Codex CLI is the first provider ported onto the system: sign in with ChatGPT, or configure another provider. Models and tools operate through declared contracts; neither is the runtime authority.
Self-evolution means shaping the conditions of future work. Under policy, an agent can create and revise goals, change interfaces (triggers), add tools, organize workers, and arrange context and execution environments. These changes persist across tasks and runs: they affect what it notices, when it acts, what it works on, and which capabilities it can use next. The agent changes its environment, and that environment shapes its subsequent behavior. Self-improvement remains the research aim: whether this process actually makes the system better.
Note
This is a research preview, not a claim of AGI or demonstrated autonomous self-improvement. The research question is: can an architecture that lets agents reshape their execution environment support useful initiative and long-term development? A model's ability, available software, permissions, and verification still determine whether a particular task succeeds.
| Home | One continuous conversation with the system. Type or talk. It can put live widgets on the screen while it works. |
| Projects | A goal with its own context and permissions. What an agent may do in one project says nothing about another. |
| Agents | Set one up once: a model, a role, and what it may touch. Underneath, an agent is not a program but two JSON files, so you can run as many as you want. |
| Tasks | A piece of work you hand to an agent. Leave it running, come back later, pick up where it stopped. |
| Terminal client | Chat, tasks, tools, files, and results in your terminal. Shares the same Home, Projects, and Agents with the desktop client. |
| Applications | The outside world, plugged in: chat channels, MCP servers, other model providers. |
| Drivers | Where the work physically happens: a folder, a git worktree, a browser, your desktop, a container, a remote machine. |
Build from source using the steps below, or check GitHub Releases for published Apple Silicon disk images. The getting-started guide covers the installer, requirements, and the ad-hoc signing / Gatekeeper warning. If no binary is published, use the source build.
You need macOS 14+, Swift 6.2+ (Xcode 26 or its Command Line Tools), Node 24, stable Rust, and a ChatGPT account. Without one, you can explore the client in its read-only Test profile (client guide) or configure an API-key, OpenAI-compatible, Claude CLI, Gemini or Vertex provider in Applications.
git clone https://github.com/miuuyy/Octopus-SI-OS.git
cd Octopus-SI-OS
npm ci --prefix appThen package the app, open it, and sign in with ChatGPT. Press Enter in the embedded terminal to start the system, pick what you want it to have, and say something.
Package the app, step by step
The native build needs the headers of the Node version inside the pinned
Electron, independently of the Node version running npm. The runtime helper
downloads and verifies the headers pinned in app/native/runtime.json, then
prints their path. Package and open the app:
headers="$(node app/native/runtime.cjs headers)" &&
OCTOPUS_NATIVE_NODE_HEADERS="$headers" npm --prefix app run package:mac &&
open -n ./app/build/Octopus.appPackaging builds the client, the release runtime, the capability executables, and the provider bridge, and bundles the managed Codex distribution. The result is app/build/Octopus.app, ad-hoc signed for this machine. It is not notarized, so Gatekeeper may warn.
Already running Octopus from this checkout? Do not rebuild the live bundle in place. Use the staged self-update procedure.
First run
- Sign in with ChatGPT. It opens the browser. There is no terminal login.
- Set a local password. It guards the client on this machine.
- Start the system. The embedded terminal prepares a command ending in
octopus up. Press Enter and wait for the ready state. - Pick a starting structure. Projects, names, capabilities. Select Set up Octopus.
- Say something in Home. A reply proves the connection. A task that uses its tools proves that task's setup.
For a new task, create an Agent first: choose a Project and a model, review its capabilities, then select it in the task composer.
Model availability and usage limits belong to your provider account. Voice and some applications ask for their own credentials and macOS permissions.
Start from a setup file
A setup file (*.octopus-setup.json) carries an Octopus's space, projects, capabilities and model, never its keys, accounts or history. On the first setup step, Import setup… fills the wizard from one; Export setup… on the review step, or Settings → General → Setup file, saves yours. Try it with the Legacy watch setup file. More in Setup files.
To use the terminal client, build it from the checkout and open Octopus:
npm --prefix app run build:cli
./octopusSee Terminal client for setup, keyboard controls, existing Home selection, and commands for scripts or other agents.
Two words carry the picture. System is everything Octopus can act on. World is everything else. They meet only at declared interfaces; there is no other route.
Underneath, there are a few primitives and no orchestrator:
- Interface - a typed port identified by its registry folder. Providers, channels, sensors, tool rooms, and workers are all interfaces; their packages own the implementation.
- Artifact - the only thing that crosses a boundary: a message, a diff, a tool call, a memory.
- Run - a durable execution record that parks and wakes on arriving artifacts. Data, not a process.
- Execution environment (EE) - a goal-classified policy scope. Runs live in EEs; nested environments can only narrow authority.
- Worker - what you would call an agent. Here it is a description, not a program: a role and a ceiling on what it may ever touch.
- Worker environment - the room where tools physically act.
- Grant - effective authority, formed at every arrival by intersecting the worker ceiling, EE chain, and run bindings. Policy inputs are stored; the grant is recomputed and enforced outside the model.
- Movement ledger - the append-only record of boundary crossings, including refusals. Projections and indexes are rebuildable views, not the source of truth.
- Mark - the proof that something happened, recorded only after a verifier passes.
One turn, end to end
You type a message in Home and Octopus reads a file to answer it.
sequenceDiagram
participant Op as You
participant Chat as Chat interface
participant K as Kernel
participant Prov as Provider interface
participant Door as Workspace room
Op->>Chat: types a message
Chat->>K: hands in an artifact
Note over K: form the grant, admit, record
K-->>Prov: movement recorded
Prov->>K: hands in a tool call
K-->>Door: movement recorded
Door->>Door: check the grant, run the tool
Door->>K: hands in the result
K-->>Prov: movement recorded
Prov->>K: hands in the reply
K-->>Chat: movement recorded
Chat->>Op: renders the reply
The kernel never pushes anything and never decodes a payload. Each interface is a live process reading its own movements. The provider interface builds what the model sees; the room's door checks the tool against the grant and runs it. The turn continues while the model keeps asking for tools and ends when it replies.
Every "movement recorded" is one row in the ledger. A refusal is a row too - typed, never a silent drop.
Everything attaches the same way: a folder of JSON, plus a script or binary when it needs to run. None of it touches the kernel.
| You want | You add |
|---|---|
| A provider over an existing wire | One interface folder |
| A channel or a sensor | One interface folder, with a process if it must listen - any language |
| A worker (an agent) | A system_worker_<name>/ folder: two JSON files |
| A tool | A tool.json over a room's executable |
| A check | A verifier folder: a descriptor and a script |
The system can do this to itself
A run asked for something it has no sense for - say, to look at you - cannot. So it authors a run for a coder, with the artifacts that run must prove. The coder writes a small camera driver and registers it by creating a new interface folder. A verifier passes it. The descriptor is picked up live.
The first time, that takes as long as a coder needs. The second time there is nothing to build. The system has a new input, and it got it by writing JSON and one script.
More in Scenarios.
The cookbook is Extending Octopus.
Desktop client — voice, tasks, and a view into the system
The optional macOS 14+ client is inspired by the ChatGPT desktop app. It brings together Home and voice calls, Projects and Tasks, split panes, Applications, Drivers, client Extensions, and experimental gesture controls. Topology and Movements expose the architecture behind the conversation.
The runtime works without this client; you can build your own. See the client guide for the screens, their roles, and setup.
The examples collection contains two independently runnable MIT-licensed companion tools:
- mcp-identity-guard: a Rust MCP stdio gateway and trusted process-oracle demonstration. Local synthetic fixtures measured 2.418 ms p50 paired overhead and 0/5 spoof false-accepts versus 5/5 for an optimistic text verifier—not a general security guarantee.
- agent-ready-radar: a zero-dependency Python scanner with a 60-domain, 420-probe survey. In that dated, purposive sample, 20/66 naive HTTP-200 positives across four discovery paths failed structural checks—not a web-wide readiness estimate.
See the collection for three-line quickstarts, compact data, reproduction steps, and the scientific and security scope boundaries. Neither tool requires Octopus.
- Getting started - build, first setup, local data.
- Desktop client - Home, Tasks, voice, Extensions, and the package catalogs.
- Architecture - System and World, the primitives, one turn end to end.
- Scenarios - what the primitives are meant to express.
- Contracts - policy, artifacts, interfaces, workers, environments, tools, verifiers, the ledger.
- Extending Octopus - adding providers, channels, workers, tools, checks.
- Security model - trust boundaries and known risks.
- Glossary · Development · Troubleshooting
Home state is stored locally in ~/.octopus by default; provider calls and
connected applications can send data off-machine. Grants constrain boundary
crossings, and enforced-mode tools run in a deny-by-default sandbox. Full-access
rooms and explicitly unsandboxed processes do not have that isolation - see the
security model. Grant only what you are comfortable granting.
Independent software, not affiliated with or endorsed by OpenAI. Stored formats may change between preview builds.

