Holon is a local-first AI agent runtime for long-running work in local workspaces.
It is built for agents that should keep working across time: read and edit a local repository, run commands, wait for external changes, wake up later, and return explicit operator-facing results.
The project is part of the Holon Run local-first AI infrastructure stack.
Holon is under active development.
The current main branch is a Rust rewrite of the original Holon line. It
intentionally replaces the earlier Go implementation and does not guarantee
compatibility with older main snapshots or Go-line behavior.
If you need the old Go implementation, use the latest Go-line release
(v0.12.0). The Rust line starts from v0.13.0.
Expect breaking changes while the runtime, CLI, and daemon surfaces are being stabilized.
Holon is:
- a local-first runtime for AI agents
- a headless execution layer for local workspaces
- a control plane for agent state, tasks, wakeups, and daemon lifecycle
- a foundation for coding agents, review agents, and event-driven continuation
Holon is not:
- a chat UI
- an all-in-one agent platform
- a connector marketplace
- a workflow automation GUI
- a full VM or container sandbox product
The core question Holon explores is:
How can an agent keep making progress in a local workspace across time without losing execution boundaries, task state, or trust boundaries?
Build the current checkout from source:
cargo install --path .
holon --helpReleased binaries are published as GitHub Release assets for Linux amd64, macOS amd64, and macOS arm64. Once a release is tagged, install with Homebrew:
brew tap holon-run/tap
brew install holonThe command examples below assume holon is installed on PATH. When working
directly from a source checkout, run cargo install --path . first so the
quickstart matches the released binary surface.
Run a one-shot local task:
holon run "fix the failing test" --json
holon run "review this repository" --mode analysis
holon run "analyze this workspace" --workspace-root /path/to/repo --cwd /path/to/repo/srcStart the long-running runtime in the foreground:
holon serveManage the runtime as a local daemon:
holon daemon start
holon daemon status
holon daemon logs
holon daemon stopOpen the local operator console:
holon tuiInspect state:
holon status
holon agents
holon transcript --limit 50Holon is organized around a few runtime primitives:
agent: a long-lived runtime identity with local statequeue: all inputs become queued workorigin: each input carries source and trust metadatatask: long-running or delegated work is modeled explicitlysleep/wake: the runtime can wait and resume from explicit signalsworkspace: local repositories are attached and projected explicitlybrief: operator-facing output is distinct from internal reasoning
The runtime currently supports:
- local file inspection and mutation
- shell-first repository work
- agent-scoped queues and state
- daemon lifecycle management
- timers, callbacks, webhooks, and remote ingress
- background task orchestration
- managed worktree workflows
- local skill and instruction loading
- Anthropic-compatible providers
- OpenAI Responses via
OPENAI_API_KEY - Codex subscription use through existing local
codex logincredentials
Holon focuses on runtime meaning: agent identity, task continuity, execution state, local workspace projection, and operator-visible results.
Adjacent Holon Run projects cover other layers:
- AgentInbox: source hosting, activation, and delivery
- UXC: unified capability and tool access
- WebMCP Bridge: browser and web-app edge access
When used together, AgentInbox should wake Holon; Holon should decide what the runtime event means.
Run checks:
cargo fmt --all -- --check
cargo test --all-targets -- --test-threads=1Run the benchmark harness:
cd benchmark
npm install
npm testUseful docs: