---
title: Create your first agent
summary: "From zero to your first Holon agent: install, start, TUI basics, create an agent, and configure models."
order: 20
updated: 2026-05-23
---

# 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)

```bash
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](https://github.com/holon-run/holon/releases/latest),
then place it on your `PATH`:

```bash
# 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:

```bash
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

```bash
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:

```bash
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:

```bash
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

```bash
holon daemon status
```

You should see runtime status including the default agent.

#### Stop the daemon

```bash
holon daemon stop
```

## Step 3: Connect with the TUI

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

### Start the TUI

```bash
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:

```bash
# 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](https://github.com/holon-run/holon/blob/main/docs/rfcs/remote-tui-access.md) 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:

```bash
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:

```bash
# 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

```bash
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](https://github.com/holon-run/holon/blob/main/docs/rfcs/runtime-configuration-surface.md) for details.

### Set provider credentials

#### Option A: Environment variables (quick start)

```bash
# 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:

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

### Set the default model

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

### Agent-level model override

An agent can override the default model:

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

See [Configuration reference](/reference/configuration.md) for more details on agent model overrides.

### Verify model configuration

```bash
holon config get model.default
holon config doctor
```

To see available models:

```bash
holon config models list
```

## Next steps

Now that you have your first agent running:

- **Explore concepts**: Read [Runtime model](/concepts/runtime-model.md) and [Trust boundaries](/concepts/trust-boundaries.md)
- **Try examples**: See [Quick examples](/guides/quick-examples.md) for common tasks
- **Build integrations**: Check the [Integration guide](/guides/integration.md)
- **Reference documentation**: See [CLI reference](/reference/cli.md), [HTTP control plane](/reference/http-control-plane.md), and [Configuration reference](/reference/configuration.md)

## Troubleshooting

### Daemon won't start

Check if another instance is running:

```bash
holon daemon status
holon daemon stop
holon daemon start
```

### TUI can't connect

Verify the daemon is running and the socket exists:

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

### Model errors

Verify your credentials:

```bash
echo $ANTHROPIC_AUTH_TOKEN
holon config get model.default
```

For more help, see [Troubleshooting guide](/guides/troubleshooting.md).