Getting started
Holon ships as an installable release. This section gives you the shortest path from install to a running agent, then shows where to branch based on what you want to do next.
Fastest path
brew tap holon-run/tap && brew install holon
holon onboard
holon daemon start
Open http://localhost:7878 or run holon tui. A successful first session
means you can:
- send a bounded request to the default main agent;
- see the agent inspect a real workspace or run an approved tool;
- receive a concise result or an explicit request for the next decision.
The walkthroughs below cover provider setup, installation, connecting with the TUI, and creating your first agent.
For the first durable workflow, choose a responsibility with a natural wait: following a pull request through CI, investigating an issue while waiting for evidence, or coordinating a release with explicit human approval.
Which runtime mode should I use?
Holon gives you three ways to interact with the runtime:
| Mode | Command | Best for |
|---|---|---|
| One-shot | holon run "..." | Quick single-turn tasks — no daemon needed |
| Daemon + TUI | holon daemon start + holon tui | Interactive agent sessions with state, queues, and workspaces |
| Daemon + HTTP | holon daemon start + HTTP client | Integrations, automation, control-plane consumers |
The first agent tutorial uses daemon + TUI because it gives you the full interactive experience. For one-shot runs, see the quick examples.
Evaluate or explore?
If you're already familiar with Holon or want to jump straight into specifics:
- Run your first Holon task — one-shot and common task patterns
- Run a long-lived task — work that waits, survives disconnects, and delivers
- Delegate work to another agent — hand a scoped task to a child agent
- Automate Holon over HTTP — drive Holon from code
- Concepts — the mental model before diving into internals
- CLI reference — full command surface
- Troubleshoot a Holon task — diagnose common setup problems
Contribute or develop?
If you plan to modify or contribute to Holon itself:
- Run Holon locally — conservative development workflow
- Documentation workflow — how to build and preview this site
- Repository
docs/directory — RFCs, implementation decisions, and architecture notes
Requirements
- Holon installed on
PATH(Homebrew or direct binary; see the walkthrough below) - A model provider API key (Anthropic, OpenAI, or compatible)
Community & feedback
- Join the Holon Pioneers Google Group to exchange experience, discuss recipes, and test early releases.
- Follow @holonrun on X for product announcements and runtime highlights.
- Report issues and request features on GitHub Issues.
Looking for contributor specifications?
If you are contributing to the Holon runtime engine or need internal lifecycle state machine contracts, consult the Runtime specs and repository development guidelines.