Run your first Holon task

Start here when Holon is installed and you want one task to reach a result. Pick the example that matches what you are doing; each one is short and self-contained. If you have not installed Holon yet, do Getting started first. Exact flags and configuration live in Reference.

1. One-Shot Question

Ask a question without creating a persistent agent:

holon run "Explain how Rust ownership works in three sentences"

Use --json for machine-readable output:

holon run --json "List files in the current directory"

2. Create an Agent

Create a named agent that persists across sessions:

holon agent create reviewer

Create an agent from an installed or synced template:

holon agent create reviewer --template code-reviewer

Then interact with it:

holon run --agent reviewer "Review the changes in src/runtime/turn.rs"

3. Switch Models

Change the global default model:

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

Set a per-agent model override:

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

Check which model an agent uses:

holon agent model get reviewer

4. Run as a Background Daemon

Start the daemon:

holon daemon start

Check daemon status:

holon daemon status

View daemon logs:

holon daemon logs

Stop the daemon:

holon daemon stop

Start with a specific access mode:

holon daemon start --access tunnel

5. Use the Terminal UI (TUI)

Launch the interactive terminal UI locally:

holon tui

Connect to a remote daemon via TUI:

holon tui --connect http://your-server:8787 --token "your-token"

Or read the token from a file:

holon tui --connect http://your-server:8787 --token-file ~/.holon/remote.token

Use a stored token profile:

holon tui --connect http://your-server:8787 --token-profile my-profile

If the terminal renders incorrectly, disable the alternate screen:

holon tui --no-alt-screen

In the TUI, type / to open the slash command menu. Use /model to switch models, /agent to manage agents, and /help to see all commands. See the TUI guide for the full slash command reference.

6. Start the HTTP Server

Expose the control plane as an HTTP API:

holon serve --port 8787

With access control:

holon serve --port 8787 --token "your-secret-token"

7. Set Up API Credentials

Store an API key securely (preferred method):

holon config credentials set --kind api_key --stdin deepseek
# Paste your API key and press Enter, then Ctrl+D

Or use an environment variable:

export DEEPSEEK_API_KEY="sk-..."
holon run "Hello"

Verify credentials are working:

holon config doctor

8. Inspect Configuration

View all current configuration:

holon config list

See all available configuration keys with defaults:

holon config schema

List configured providers:

holon config providers list

List available models:

holon config models list

9. Run a Multi-Turn Task

Limit the maximum number of turns:

holon run --max-turns 5 "Write a Rust function that reverses a string, with tests"

Run in a specific workspace:

holon run --workspace-root /path/to/project "Analyze this codebase"

10. Create an Agent with a Custom Workspace

holon agent create my-builder
holon run --agent my-builder --workspace-root /path/to/project "Build the project"