octos

Octos

An embeddable AI agent harness kernel, written in Rust.

Octos provides the execution loop, context management, memory, tools, skills, workflows, and agent coordination for applications built around AI agents. Compile the kernel into your own application, or host it behind OUP — the Octos UI Protocol — and control it from a native app, a terminal, a browser, or another agent.

The defining architecture is a reusable kernel with a programmable protocol boundary. Your application owns its interface and product workflow; Octos owns agent execution and runtime state. The same OUP contract lets a human-facing client and an automated controller operate that runtime.

Build with Octos · Control through OUP · Documentation · 中文

Looking for a coding agent to use?

Start with an application built on the kernel:

This repository is for developers embedding, extending, or integrating the harness kernel. Application installation and everyday coding workflows belong in the client repositories above.

Build with Octos

Use Octos as the foundation for a coding application, an agent-powered desktop app, a research service, a workflow engine, or a fleet of cooperating agents. Bring your own interface, model providers, tools, and host environment.

Kernel architecture

Embed the Rust crates or task bindings in your application, or connect through OUP to a hosted runtime. OUP carries both commands into the kernel and responses and events back to the client or controller.

Native kernel and libraries

The Rust workspace lets you compose the parts your application needs:

From a checkout, build the native agent library or a library for a non-Rust host:

cargo build --release -p octos-agent
cargo build --release -p octos-ffi

Pin related Octos crates to the same Git revision when integrating them into another workspace. For other host languages, use the C ABI, native Python binding, or Swift/Kotlin bindings. The C ABI produces shared and static libraries. These bindings expose task execution; OUP provides the session, turn, supervision, and replay interface described below.

Platforms and architectures

Build native applications for Linux, Windows, and macOS. CI configurations include Linux x86-64 and ARM64, macOS ARM64, and Windows x86-64. RISC-V has a manual CI definition, but remains an unverified target: the configuration records that no runner has executed the job. Select the crates, features, and native dependencies for your target; support depends on that combination.

Other operating systems can connect an application through OUP or port the kernel's platform integrations, including process execution, filesystem access, and sandboxing. The application/protocol boundary stays the same.

For browser applications, the WASM crate supplies protocol and utility types. The full agent kernel runs natively, with the browser communicating over OUP.

Control through OUP

OUP (Octos UI Protocol) is a JSON-RPC 2.0 interface for applications and agent controllers. It carries requests, responses, and typed runtime events over WebSocket or newline-delimited stdio. Local runtime adapters also use an in-process connection to the OUP dispatcher.

For a local controller, the reference host is octos serve --stdio, built from octos-cli with the api feature. A WebSocket client connects to a running host's /api/ui-protocol/ws endpoint using that host's authentication settings. Use string JSON-RPC request IDs.

Stdio clients negotiate features with client_hello; WebSocket clients request them through X-Octos-Ui-Features or the ui_feature query parameter. Query config/capabilities/list to discover supported methods, then use the advertised capabilities to choose controls and event formats. The runtime owns conversation history, execution state, compaction, permissions, and committed results; clients render or act on that state through the protocol.

Drive Octos from another agent

A controller integration can expose OUP requests as tools callable by Codex, Claude Code, or another agent. This gives the controlling agent a way to assign work to Octos agents, observe execution, intervene, and collect results. The integration supplies the OUP client or bridge.

A typical controller flow is:

1. Connect and negotiate. Establish a transport, negotiate feature support, and query config/capabilities/list.
2. Open a scoped session. Use session/open with the session identity, profile, and workspace; retain the identity confirmed by the runtime.
3. Assign work. Send turn/start with a fresh turn ID and structured input. The RPC acknowledgement means the turn was accepted; follow the negotiated event stream to its terminal outcome.
4. Observe and intervene. Consume message, tool, task, and progress events. Use turn/steer to add instructions, turn/interrupt to stop a turn, and approval/respond or user_question/respond when an authorized decision or answer is needed.
5. Coordinate and recover. Use peer/prepare to stage a peer's brief and optional worktree, then open its session and start its turn. Gather durable peer results through peer/gather; inspect task output and artifacts through task/*. Rehydrate a session or resume from its committed cursor after a reconnect.

The controller follows the event stream after a turn is accepted. Approvals, questions, and interventions are optional; completion, failure, or interruption ends the turn.

For example, after opening a session, a controller can send this turn/start request. Replace the session placeholder with the confirmed session ID and use a new UUID for each turn:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "turn/start",
  "params": {
    "session_id": "",
    "turn_id": "550e8400-e29b-41d4-a716-446655440000",
    "input": [
      { "kind": "text", "text": "Review the changes in this workspace and report findings with file and line references." }
    ]
  }
}

The same controller can let Octos perform research or implementation, inspect its findings, then steer the next turn. OUP exposes the controls and evidence needed to build that collaboration into your own application.

Kernel capabilities through the OUP lens

OUP makes the harness programmable throughout a task's lifecycle. An application can inspect the context an agent is using, respond to a tool approval, supervise parallel work, and recover committed results through the same runtime contract. The kernel manages execution and persistence; the application decides how to present that state and when to intervene.

The surfaces below depend on the runtime, transport, and negotiated features. Discover them through config/capabilities/list, check supported_methods and supported_features, and consume the negotiated event format. Capability discovery lets an integration adapt to the runtime it is actually connected to.

Context management

Long tasks accumulate conversation, tool output, and intermediate results. Octos manages the model's context budget, compacts older material, and preserves recent tool-call/result relationships. Compaction can use LLM summarization or heuristics. Stable prompt prefixes support provider cache reuse, while changing task state remains part of the evolving conversation.

• Inspect: session/status/read and session/hydrate expose the runtime's context state when context.lifecycle.v1 is negotiated, including compaction metadata. These describe the context available to the model after processing.
• Control: session/compact requests a compaction pass; session/compact/mode/set selects the session's compaction mode.
• Observe: context/compaction_started and context/compaction_completed let an application explain when and how context changed during execution.

A coding app can show context usage and compaction history; an agent controller can inspect that state before assigning the next stage of a long task.

Memory across tasks

The memory layer provides long-term notes and entity pages, episodic task records, and retrieval. Its hybrid index combines keyword search with vector similarity when embeddings are available. An application can retain project conventions, decisions, and useful task outcomes across sessions.

• Inspect stored knowledge: memory/overview and memory/entity expose profile memory on WebSocket connections that advertise auxiliary.rest_to_ws.v1. These methods are unavailable over stdio.
• Use memory during execution: agents equipped with memory tools can retrieve and update knowledge through tools such as recall_memory and save_memory. Those are agent tools, not OUP RPC method names.
• Keep the roles distinct: memory supplies reusable knowledge; session history and event replay record what happened in a particular conversation.

Durable sessions and recovery

Octos owns session identity, workspace scope, conversation history, and committed events. A client can reconstruct the runtime's view of a conversation after a reload, or build a different interface over the same stored session.

• Open and inspect: session/open establishes the session and confirmed workspace. session/hydrate restores messages, turns, pending approvals, and other requested state; turn/state/get inspects a specific turn's lifecycle.
• Reconnect: retain the last applied durable cursor and pass after when reopening the session. The runtime replays retained committed events before live delivery. Uncommitted deltas may be lost, and expired cursors require fresh hydration; replay does not imply an active turn survived a disconnect.
• Branch or rewind: session/fork creates a conversation branch, and session/rollback rewinds conversation turns. Conversation rollback does not undo filesystem changes.

Tools, permissions, and human input

The kernel executes filesystem, shell, web, and MCP tools under the host's tool policy and platform sandbox configuration. Host-configured lifecycle hooks can participate around model calls and tool execution. OUP exposes execution and decision points so the application can provide its own approval interface or delegate authorized decisions to a controller.

• Discover and observe: tool/status/list and mcp/status/list report available integrations. tool/started, tool/progress, and `too