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 processes, tasks, and templates unless overridden.

web¶

When enabled, the daemon serves a web dashboard with process 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 in the top-right of the dashboard 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. The bearer token grants access to the full daemon API — including /web/* routes that can restart the service, mutate config, send keys to supervised processes, and write prompt files. Treat it like a root credential. Supervised Claude processes receive this token via LEO_API_TOKEN so the built-in MCP server can call /api/*; if you don't trust a channel plugin with full daemon access, don't install it as a supervised process.

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 processes 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:

processes:
  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), processes, tasks, and templates 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.

processes:
  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 processes, Leo watches the tmux pane and auto-accepts the prompt so the session starts non-interactively. Silent/nonexistent entries are ignored by Claude Code without warning — verify spellings carefully.

processes¶

Each process is a named entry under the processes map. Processes define long-running Claude sessions supervised by the daemon.

processes:
  assistant:
    channels: [plugin:telegram@claude-plugins-official]
    remote_control: true
    enabled: true

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
    remote_control: true
    permission_mode: auto
    workspace: ~/agents

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>.

Override Cascade¶

Process, task, and template settings override defaults:

effective value = process/task/template value OR defaults value