Config Reference¶

Complete field-by-field reference for leo.yaml.

Config lives at ~/.leo/leo.yaml (the Leo home directory).

defaults¶

Settings inherited by all tasks and templates unless overridden.

Custom Anthropic-compatible endpoints (z.ai GLM, OpenRouter, Moonshot, DeepSeek, MiniMax, …) are configured via each scope's own env: map (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN) — see Harnesses → providers is gone.

harness_options by harness¶

Every scope's harness_options map is strictly validated by that scope's resolved harness: — unknown keys, wrong types, and invalid enum values are all rejected at config load and before every web-UI save. Full behavior (merge rules, resume, MCP bridge, auth, etc.) is in Harnesses.

claude (7 keys):

codex (1 key):

opencode (1 key):

web¶

When enabled, the daemon serves a web dashboard with agent monitoring, task management, agent dispatch, config editing, and cron preview.

Authentication¶

Both browser and API access require the same token. On first start the daemon mints a random 64-hex-char token and writes it to ~/.leo/state/api.token (mode 0600).

Browser login. Visit the dashboard and you'll be redirected to /login. Paste the token there and a 7-day session cookie is set (HttpOnly, SameSite=Strict). For convenience:

leo web login-url

prints a one-click URL (http://<bind>:<port>/login?token=...) — the login page auto-submits if the token is in the query string. The URL contains the token; don't share it.

Click Sign out at the bottom of the sidebar to destroy the session.

API access. /api/* endpoints take the token in an Authorization: Bearer header:

curl -H "Authorization: Bearer $(cat ~/.leo/state/api.token)" \
  http://127.0.0.1:8370/api/status

Rotate the token by deleting api.token and restarting the daemon. Existing browser sessions remain valid until they expire (7 days).

Token scope. There are two tokens, with different privileges:

The operator token grants access to the full daemon API — including routes that restart the service, mutate config, and write prompt files. Treat it like a root credential.

Agents get the narrower token so a credential that escapes an agent — into a transcript, a log, a channel message — cannot be exchanged for a web session. It is rejected at /login and on the config editor, which renders template env: values in full. Rotate either by deleting its file and restarting the daemon.

This bounds blast radius; it is not a sandbox. Agents run as your user and can read ~/.leo/leo.yaml directly, so any credential in config is reachable by an agent that goes looking. Don't install a channel plugin you wouldn't trust with the contents of your config.

Non-loopback access¶

bind defaults to 127.0.0.1. To expose the web UI on your LAN:

web:
  enabled: true
  bind: 0.0.0.0
  port: 8370
  allowed_hosts:
    - 192.0.2.10      # the IP your LAN will use to reach this host
    - leo.local      # or a hostname

allowed_hosts entries are checked against the incoming Host and Origin headers to defend against DNS-rebinding and drive-by cross-origin POSTs. Entries must be bare hostnames or IPs — no port, no scheme. allowed_hosts is required when bind is non-loopback; leo validate will fail otherwise.

The daemon prints a startup warning when bind is non-loopback.

client¶

Remote-host definitions used by the leo agent CLI when leo is invoked as a client of a different machine. Empty on server configs.

Each entry under hosts has:

client:
  default_host: prod
  hosts:
    prod:
      ssh: alice@leo.example.com
      ssh_args: ["-p", "2222"]
      leo_path: /usr/local/bin/leo
      tmux_path: /opt/homebrew/bin/tmux
    dev:
      ssh: alice@devbox.local

Why leo_path exists: SSH runs a non-interactive shell on the remote, which doesn't source .zshrc / .bashrc. If leo lives in ~/.local/bin and PATH is only extended in .zshrc, bare leo won't resolve. The default full path avoids that; set leo_path explicitly when the remote installs leo elsewhere (Homebrew, /usr/local/bin, etc.).

Resolution order for the target host: --host flag → LEO_HOST env → default_host → first entry sorted by key → localhost (only when no hosts are configured). --host localhost is a hard override. See the Remote CLI guide.

Channels¶

Leo does not ship with any built-in messaging channel. Channels are Claude Code plugins the user installs separately (e.g. Telegram, Slack, webhook). In leo.yaml they are referenced by plugin ID strings like plugin:telegram@claude-plugins-official on the channels: field of templates and tasks.

Leo passes the resolved list to the spawned Claude process via the LEO_CHANNELS environment variable. The plugin owns its own credentials, routing, and inbound-message handling.

To install a channel plugin:

claude plugin install telegram@claude-plugins-official

Then reference it:

templates:
  assistant:
    workspace: ~/agents/assistant
    channels: [plugin:telegram@claude-plugins-official]

Development Channels¶

For channel plugins that aren't yet published to a registry (or for local plugin development), templates and tasks accept a parallel dev_channels: field. Leo passes each entry to Claude Code via --dangerously-load-development-channels <id> and exports the list in LEO_DEV_CHANNELS.

templates:
  assistant:
    workspace: ~/agents/assistant
    channels: [plugin:blackpaw-telegram@blackpaw-plugins]
    dev_channels: [plugin:blackpaw-telegram@blackpaw-plugins]

Validation matches channels — each entry must be a valid plugin ID.

Claude Code displays a confirmation prompt before loading development channels. For supervised agents, Leo watches the tmux pane and auto-accepts the prompt so the agent starts non-interactively. Silent/nonexistent entries are ignored by Claude Code without warning — verify spellings carefully.

tasks¶

Each task is a named entry under the tasks map. Tasks are invoked by the in-process cron scheduler or manually via leo run <task>.

tasks:
  daily-briefing:
    schedule: "0 7 * * *"
    timezone: America/New_York
    prompt_file: prompts/daily-briefing.md
    enabled: true

Silent Mode¶

When silent: true, Leo prepends a preamble instructing the agent to work without narration. The agent should deliver its final message via a configured channel plugin or output NO_REPLY if there's nothing to report.

templates¶

Templates are reusable blueprints for spawning ephemeral agents. Dispatch them via the HTTP API, a channel plugin that exposes agent commands, or the web UI.

templates:
  coding:
    model: sonnet
    workspace: ~/agents
    harness_options:
      remote_control: true
      permission_mode: auto

When dispatching with a repo (/agent coding owner/repo via a channel plugin, or leo agent spawn coding --repo owner/repo), Leo clones the repo into <workspace>/<repo> using gh. The agent session is named leo-<template>-<owner>-<repo>. A repo is optional — leo agent spawn coding with no repo runs the template as-is directly in workspace, and the agent is named after the template (coding in this example).

Templates also back persistent tasks (runtime: persistent): a task with template: <name> delivers its prompts into that template's agent instead of spawning claude -p, spawning/resuming it on demand rather than at leo service boot. Multiple tasks can share one template: and therefore one agent and one FIFO queue. A runtime: persistent task with no template: gets an implicit target instead — an agent named after the task, synthesized from the task's own fields. See Persistent Tasks for the full mechanics (ensure-exists, queueing, completion reporting, leo agent reset).

Idle-suspend¶

Ephemeral agents can be suspended after a period of inactivity to free local resources (the claude process and tmux session are killed) while preserving the workspace and conversation. Off by default — enable it by setting an interval:

defaults:
  idle_suspend_after: "24h"      # global default

templates:
  reviewer:
    idle_suspend_after: "30m"    # per-template override

Or per spawn: leo agent spawn reviewer owner/repo --idle-suspend 24h.

The cascade is spawn flag → template → defaults; the resolved interval is stamped onto the agent at spawn time. Behavior:

• Activity is measured by the agent's tmux session_activity — injected prompts, interactive typing in an attached pane, and the agent's own output all count.
• An agent with a client attached is never suspended, even past the interval (so reading scrollback won't yank the session out from under you).
• A suspended agent shows as suspended in leo agent list. It auto-resumes on the next incoming message (e.g. leo_send_message), rejoining its prior conversation via --resume. You can also resume or suspend manually:

leo agent suspend <name>
leo agent resume <name>

• Suspended agents stay suspended across daemon restarts (they are not resurrected at boot), and their worktrees are never pruned.

State directory¶

Leo's runtime state lives under ~/.leo/state/ (or <home>/state for a non-default leo home): sessions.json (session-id bookkeeping — including the post-hoc-discovered codex/opencode session ids, see Harnesses → Session driver semantics), history.json, and api.token (see Authentication). There is no more per-harness state directory — codex and opencode drive a resident tmux TUI the same way claude does, so their session ids live in the same sessions.json store rather than separate per-tmux-session files.

If you're updating from a pre-uniform-tmux-TUI build, stale state/opencode/*.json and state/transcripts/*.log files from the old model are inert and safe to delete; see the migration note in Harnesses.

Override Cascade¶

Task and template settings override defaults:

effective value = task/template value OR defaults value