English | 中文

Holon is a local workbench for agents doing continuous work.

Holon itself is not an agent. It provides a local working environment for multiple agents. Agents understand goals and drive execution; Holon treats "work" as the core unit, preserving state, organizing context, recording waits and wakes, so tasks that span sessions, commands, human confirmation, or external events can resume at the right time and eventually deliver results back to the operator.

• What does Holon provide?
• Install
• Provider setup
• Quickstart
• Core concepts
• Status and compatibility
• Project boundaries
• Documentation
• Build from source

Keep agent work alive in your local workspace.

Install the latest release with Homebrew:

brew tap holon-run/tap
brew install holon
holon --help

You can also download prebuilt binaries for Linux amd64, macOS amd64, and macOS arm64 from GitHub Releases.

The examples below assume holon is installed on PATH.

Holon needs a model provider before it can run agents. It mainly supports three setup paths:

• Local credential storage: recommended for daily use. Manage API keys through credential profiles, avoiding dependence on environment variables that must be injected before the daemon starts.
• Built-in providers: supports common providers such as Anthropic, OpenAI, DeepSeek, OpenRouter, Qwen, GLM, Xiaomi, Kimi, and MiniMax.
• External login / custom providers: openai-codex/... can reuse a local codex login session and supports Codex subscriptions. You can also connect custom providers with compatible protocols.

For an interactive first run or repair flow, use:

holon onboard

In a TTY this guides you through the default provider credential setup without echoing the credential material. In scripts, use holon onboard --json for the secret-safe diagnostic report.

The equivalent manual setup is to save the API key first, then point the provider at the corresponding credential profile:

printf '%s' "$DEEPSEEK_API_KEY" \
  | holon config credentials set --kind api_key --stdin deepseek

holon config providers set deepseek \
  --credential-source credential_profile \
  --credential-kind api_key \
  --credential-profile deepseek

holon config set model.default "deepseek/deepseek-v4-pro"

# Or use a local Codex login session / Codex subscription
holon config set model.default "openai-codex/gpt-5.5"

Inspect the configured state with:

holon onboard
holon config doctor
holon config models list

For more about providers, credential profiles, custom providers, and the model catalog, see:

• Configuration Reference
• Supported Models

Start the long-running local runtime first:

holon daemon start
holon daemon status

Connect the TUI:

holon tui

Holon automatically provides a default main agent. There are two ways to create a new agent:

• Tell the main agent in the TUI and let it create one for you.
• Or create one through the CLI:

holon agent create builder --template holon-developer
holon agent list

After that, select an agent in the TUI and start working. After the TUI disconnects, the agent continues running in the daemon.

For more operations, see the TUI command reference and Daemon management.

Holon breaks agent work into a few explicit runtime objects:

• Agent is a long-lived local identity with its own queue, state, history, and working context.
• WorkItem represents a continuously advanceable goal, including a plan, progress, blockers, wait conditions, and a completion report.
• Task represents supervised asynchronous execution, such as a command, background task, or child agent.
• WaitFor / wake lets an agent explicitly declare that it is waiting for a task result, external event, or operator input, and resume when the condition is satisfied.
• Workspace / worktree lets agents execute in local repositories and isolate coding tasks into managed worktrees.
• Origin / brief preserves input origin and trust information while keeping internal execution traces separate from operator-visible delivery.

Together, these concepts solve one problem: agent work should not depend on a single chat or terminal connection. It should be observable, resumable, waitable, delegable, and deliverable.

For more detailed explanations, see Concepts.

The current recommended release is v0.18.1.

v0.15.0 is the baseline release where the Holon Rust runtime enters public compatibility maintenance. Starting from this version, the project will maintain compatibility for the CLI, daemon/API semantics, and local persistent storage.

See the full changes in the v0.18.1 Release Notes.

Holon is under active development. Starting from v0.15.0, the project treats the following surfaces as public contracts that need compatibility maintenance:

• CLI: common commands, arguments, and structured output should remain migratable; breaking changes should be documented with release notes and migration paths.
• Interfaces: daemon client APIs, event semantics, and runtime object fields should remain backward compatible or provide clear versioned evolution paths.
• Persistent storage: local data such as agent state, ledgers, messages, transcripts, WorkItems, and tasks should support upgrades and read compatibility.

The current project focus remains the Rust runtime: agent lifecycle, queues, WaitFor/wake, tasks, WorkItems, trust boundaries, local workspaces, and structured delivery.

Holon focuses on runtime semantics: agent identity, work 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 delivers external events to wake Holon; Holon decides what those events mean inside the runtime.

Holon's documentation is organized into three layers. See documentation layers.

Using Holon:

• Website docs — install, getting started, concepts, guides, and current reference
• Security and execution boundaries

Integrating and operating Holon:

• Local operator troubleshooting
• Release process

Contributing to the runtime:

• Architecture overview — start here
• RFCs — specification and design contracts
• Implementation decisions — design rationale

• GitHub Discussions
• GitHub Issues

cargo install --path .
holon --help

Run checks:

cargo fmt --all -- --check
RUSTFLAGS="-D warnings" cargo check --all-targets
cargo test --all-targets -- --test-threads=1

Run the benchmark harness:

cd benchmark
npm install
npm test

This project is licensed under the Apache-2.0 license.