Create your first agent

This guide walks you through creating your first Holon agent from scratch. You will:

1. Install Holon
2. Start the runtime (one-shot and daemon mode)
3. Connect with the TUI
4. Create an agent
5. Configure models

Time: ~10 minutes (with Homebrew); ~15 minutes (build from source)

Prerequisites

• Holon installed on PATH (see Step 1)
• A model provider account (Anthropic, OpenAI, or compatible)
• Basic terminal familiarity

Step 1: Install Holon

Holon v0.14.0 and later ship as installable releases. Choose the method that works best for you.

Option A: Homebrew (recommended)

brew tap holon-run/tap
brew install holon

Option B: Direct binary download

Download the latest binary for your platform from the GitHub Releases page, then place it on your PATH:

# Example: Linux amd64
curl -L https://github.com/holon-run/holon/releases/latest/download/holon-linux-amd64 -o holon
chmod +x holon
sudo mv holon /usr/local/bin/

Binaries are available for Linux amd64, macOS amd64, and macOS arm64.

Option C: Build from source

If you prefer to build from source or plan to contribute to Holon:

git clone https://github.com/holon-run/holon.git
cd holon
cargo build --release

When building from source, replace holon commands in the examples below with cargo run --. For example, holon --help becomes cargo run -- --help.

Verify the install

holon --help

You should see the CLI help output with available commands.

Step 2: Start the Holon runtime

Holon can run in two modes:

• CLI mode (default): Single-shot commands with direct output
• Daemon mode: Background service with TUI support

Option A: CLI mode (quick start)

Run a single command:

holon run "What is Holon?"

This executes one turn and exits. Great for quick tasks, but not ideal for interactive sessions.

Option B: Daemon mode (recommended for agents)

Start the background daemon:

holon daemon start

This starts Holon as a background service with:

• Unix socket at ~/.holon/run/holon.sock (local access)
• Control plane for TUI and HTTP clients
• Persistent state across sessions

Verify the daemon is running

holon daemon status

You should see runtime status including the default agent.

Stop the daemon

holon daemon stop

Step 3: Connect with the TUI

The Terminal UI (TUI) provides an interactive interface for working with agents.

Start the TUI

holon tui

The TUI connects to the local Unix socket by default.

TUI basics

The TUI shows:

• Agent list: Current agents and their status
• Active agent: The agent receiving your input
• Transcript: Conversation history
• Task list: Background tasks and work items

Basic navigation

• Type your message and press Enter to send
• Ctrl+C to exit the TUI
• Arrow keys or Page Up/Down to scroll through history

Remote TUI (optional)

To connect to a remote Holon instance:

# On the remote host
holon serve --access lan --host 192.168.1.10 --token-file ~/.holon/remote.token

# From your local machine
holon tui --connect http://192.168.1.10:7878 --token-file ~/.holon/remote.token

See Remote TUI Access RFC for details.

Step 4: Create an agent

Holon supports different agent types for different use cases.

The default agent

When you start Holon, it automatically creates a default agent in ~/.holon/agents/main/. This agent:

• Has its own agent_home with AGENTS.md
• Can have agent-local skills
• Stores conversation history and work state

Create a named agent

Create a specialized agent for a specific role:

holon agent create reviewer --template holon-reviewer

This creates a new agent in ~/.holon/agents/reviewer/ initialized with the holon-reviewer template.

Use a template

Templates provide reusable agent configurations:

# Use a builtin template by ID
holon agent create docs-helper --template holon-developer

# Use a local template path
holon agent create custom --template /path/to/template

# Use a GitHub template URL
holon agent create github-agent --template https://github.com/owner/repo/tree/main/template-path

List agents

holon agent list

Switch agents in the TUI

In the TUI, you can switch between agents using the agent list view.

Step 5: Configure models

Holon requires model configuration to work with providers like Anthropic or OpenAI.

Configuration layers

Holon uses three configuration layers:

1. Startup settings (environment variables, CLI flags)
2. Runtime configuration (config.json)
3. Agent state (per-agent overrides)

See Runtime Configuration Surface RFC for details.

Set provider credentials

Option A: Environment variables (quick start)

# Anthropic
export ANTHROPIC_AUTH_TOKEN="your-api-key"

# OpenAI
export OPENAI_API_KEY="your-api-key"

Option B: Credential store (recommended for persistent config)

Store credentials securely without exposing them in shell history or environment variables:

holon config credentials set --kind api_key --stdin anthropic
# Paste your ANTHROPIC_AUTH_TOKEN and press Enter

Set the default model

holon config set model.default "anthropic/claude-sonnet-4-6"

Agent-level model override

An agent can override the default model:

holon agent model set "anthropic/claude-sonnet-4-6" reviewer

See Configuration reference for more details on agent model overrides.

Verify model configuration

holon config get model.default
holon config doctor

To see available models:

holon config models list

Next steps

Now that you have your first agent running:

• Explore concepts: Read Runtime model and Trust boundaries
• Try examples: See Quick examples for common tasks
• Build integrations: Check the Integration guide
• Reference documentation: See CLI reference, HTTP control plane, and Configuration reference

Troubleshooting

Daemon won't start

Check if another instance is running:

holon daemon status
holon daemon stop
holon daemon start

TUI can't connect

Verify the daemon is running and the socket exists:

ls ~/.holon/run/holon.sock
holon daemon status

Model errors

Verify your credentials:

echo $ANTHROPIC_AUTH_TOKEN
holon config get model.default

For more help, see Troubleshooting guide.