Ocean OS

Ocean OS is the local Rust runtime for Ocean. A long-running daemon owns agent
turns, provider calls, permission-gated tools, sessions, and event delivery.
The terminal UI, CLI, ACP bridge, and sibling product surfaces are clients of
that daemon; they are not separate agent runtimes.

What this repository owns

clients (TUI / CLI / ACP / Ocean Surface)
  -> ocean-daemon (:4780; HTTP + SSE authority)
  -> ocean-agent (sessions, prompts, capabilities)
  -> ocean-runtime (agent loop, tools, permissions, cancellation)
  -> ocean-protocol + ocean-providers (provider wire + model/auth routing)

The canonical package, entry-point, and narrow-test index for all workspace
members is crates/AGENTS.md. The cross-repository boundary
is docs/OCEAN_PROJECT_MAP.md.

Ocean OS does not own product UI chrome, agent-package content, or the shared
Bedrock data plane:

• ocean-surface owns the
  Leptos UI and its browser, extension, and Tauri hosts.
• ocean-agents owns editable
  assistant profiles, specialist packages, and couriers.
• ocean-bedrock owns the
  authenticated shared files, ledger, ingest, graph, and semantic-search plane.

Quick start

Prerequisites: Rust 1.88 or newer and a configured model/provider. See
docs/OPERATIONS.md for credentials, supported build
lanes, supervision, and recovery.

cargo build --workspace --release

# The daemon intentionally refuses a repository cwd. Start it from a neutral
# directory so an unbound turn cannot accidentally bind to this checkout.
OCEAN_MODEL=<model-alias> \
  sh -c 'cd "$HOME" && /absolute/path/to/ocean-os/target/release/ocean-daemon'

curl -fsS http://127.0.0.1:4780/health

# In another terminal:
./target/release/ocean-rs prompt "Reply with: pong"
./target/release/ocean-tui

For the supervised macOS service, use ops/install-ocean-daemon.sh rather than hand-copying a daemon binary. The script enforces the main branch; operators must separately verify a clean tree and HEAD == origin/main as documented in docs/OPERATIONS.md.

Runtime contracts

• The daemon is the execution and HTTP/SSE authority.
• Product clients create or select a session, subscribe to that session's
  events, and submit turns carrying session_id, cwd, and client_type.
• Session persistence lives in ocean-agent; a session defect affects every
  first-party client.
• Mutating tools remain permission-gated unless the operator explicitly selects
  a trusted bypass.
• The daemon must run from a neutral cwd.
• Durable collaboration uses /v1/rooms/persistent/*; the retired Track-0 room
  projection is not an active client contract.

Documentation

Start at docs/README.md.

Plans and characterization reports under docs/specs/ are evidence, not the
current architecture unless a current contract explicitly says otherwise.
Completed or superseded context belongs under docs/.agentarchive/.

Development gate

cargo xtask docs-check       # docs/index/archive integrity
cargo xtask ci               # canonical local merge gate
cargo xtask ci --dry-run     # print the executable manifest

Compatibility lanes also run supported daemon features and release builds on
stable Rust and the default/supported feature paths on pinned Rust 1.88. See
AGENTS.md and xtask/README.md.

Contributing

Read AGENTS.md before editing and then follow every nearer
AGENTS.md on the path to the target file. See
.github/CONTRIBUTING.md for the contribution flow
and NOTICE.md for third-party attributions.