README.md

Orb Documentation

Orb is the client application; Core (formerly sandboxed.sh) is its Rust backend. Existing binary names (sandboxed-sh, sandboxed-node, sandboxed-mcp, palomactl) remain compatible.

   

---

1. Quick Start & Installation

• Getting Started — Connect Orb (macOS & iOS) to your backend, configure subscriptions/harnesses, and launch your first agent.
• Docker Installation — Run the backend, web admin console, and pre-installed CLIs in a single container.
• Native Ubuntu 24.04 Installation — Bare-metal systemd setup with systemd-nspawn containers, missions.slice cgroups, and optional private networking. See Lean-Mesh for the deployed fleet.

2. Orb Client & Mission Capabilities

• Orb Desktop (../orb/README.md) — Tauri v2 + SolidJS macOS app, keyboard shortcuts, local voice input, and browser tests.
• Orb iOS (../ios_dashboard/README.md) — Native SwiftUI iOS client (SandboxedDashboard/Orb), synced project colors, transcripts, and settings.
• Shared Project Context & Offline Local Starts — Bi-directionally synced @context directories and offline local mission creation (~/.orb/local-origins/).
• Project Skills — Synchronized per-project skills/<name>/SKILL.md discovery across Codex, Claude Code, Antigravity, OpenCode, and Grok.
• Native Plan Mode (/plan) — Interactive planning with native question/approval cards and checklist progress tracking.
• Side Agents (/btw) — Independent side-panel agent sessions (⌘⇧J) with incremental transcript excerpts and @conversation archives.
• Cross-Machine Mission Transfer — Move idle missions (Change machine…) across your computer, Core, and fleet nodes with SHA-256 verified checkpoints and Git bundles.
• Scheduled Continuations — Durable mission wake-ups (schedule_wakeup / schedule_job_wakeup).
• File Attachments & Uploads — Native multi-file picker and 20 MiB destination-routed uploads (POST /api/uploads).
• Codex Cyber Access — Per-mission Standard, Daybreak, and Automatic access program selection.
• Orb Settings — Backend, Providers and Machines settings in Orb.
• Model Routing Settings — Ordered fallback chains, provider health, and fallback event inspection.

3. Execution, Harnesses & Fleet

• Execution Architecture (../AGENTS.md) — Per-workspace CLI execution, missions.slice cgroup isolation, disk-backed container /tmp, and the "Lean Decides, Rust Does" formal Lean 4 C-ABI kernel (lean/Orb/Kernel.lean & lean/Orb/Spec.lean, 35/35 tight specs, 23 C-ABI gates).
• Harness System — How Claude Code, Codex, Antigravity (agy), OpenCode, and Grok execute inside host and container workspaces.
• Google Antigravity (agy) — Workspace-native agy CLI execution, model discovery (agy models), and managed node profiles.
• Managed Fleet Harnesses — Atomic /opt/sandboxed-tools/<harness>/<version>/ installations and daily fleet reconciliation.
• Agent Software Inventory & Updates — Inspecting and updating host CLI versions from Orb's Machines page (GET /api/software).
• Remote Runner Nodes & Spark Offload — sandboxed-node lease architecture, remote_launch capability matrix, and Lean 4 build offload.
• Lean-Mesh (wg-leanmesh0) — Formally verified WireGuard + nftables zero-trust mesh (10.88.0.0/16) replacing Tailscale in both Orb-integrated and standalone CLI modes.
• Biometric JIT Privilege Broker, Deploy Gate & Bunker Mode — Touch ID P-256 always_signed privilege grants (orb-privd / orb-sudo), production deploy gate, 4-state Bunker Mode, and the 180s dgx-spark Dead-Man's Switch.
• Workspaces — Host vs systemd-nspawn container workspaces, Library templates, and stdio MCP allowlists.
• Storage Lifecycle Policy — Dry-run-by-default storage inventory and retention rules.

4. Subscriptions, Providers & Identity

• OAuth Credential Ownership & CLIProxyAPI — Preventing OAuth refresh-token races with SANDBOXED_OAUTH_OWNER=cli-proxy and UI login flows.
• Inference Protocols & Reasoning Continuity — Wire format routing (Anthropic Messages, OpenAI Responses, Chat Completions) to preserve reasoning blocks.
• Model Catalog — Live provider model discovery and compiled-in fallback snapshots.
• AI Provider Configuration — Configuring API keys and custom provider endpoints.
• Shared Development Identity — Operator-managed Bitwarden Secrets Manager profile for GitHub, OpenPGP commit signing, and fleet SSH.

5. Control Plane, Cloud Agents & Hermes

• Agent Control Plane Constitution & Roadmap — The canonical abstraction tower: portfolio → project → track → attempt → action → receipt → evidence.
• Hermes Orchestration & Autonomous Controllers — How Hermes crons drive projects through control conversations and MCP.
• Hermes Cloud Conversations in Orb — Launching durable Hermes conversations directly from Orb → Cloud agent.
• Cloud Agents (cloud-agents/STATUS.md)** — Cursor Cloud and Grok Bot hosted sessions.
• Unified MCP (sandboxed-mcp) — Scoped mcp1. sessions, executor/coordinator/operator profiles, and idempotent action receipts.
• Writer Dispatch Admission, Codex Native Continuity, Codex Goal Lifecycle, & Validation Campaigns.
• palomactl — CLI for project-state reconciliation.

6. API & Streaming Reference

• Mission API — Mission CRUD, snapshots, cursor-paginated events, SSE streaming, and automations.
• Streaming Contract — Canonical SSE, WebSocket, and historical event replay contract.
• Workspace API — Workspace CRUD, container builds, command execution, and diagnostics.
• Backend API — Harness discovery and configuration endpoints.
• Capability Matrix — CI-enforced feature parity across API, Web, and iOS (capabilities/matrix.v1.json).

---

Historical incident postmortems, one-off validation receipts, and retired migration guides live in docs/archive/.