# Talon.setup.docker

> Use when setting up Talon from the starter bundle (docker-based install) for the first time, adding channels or personas, changing the AI provider, or troubleshooting. Triggers on phrases like "set up talon", "configure talon", "add channel", "switch provider", "talonctl …".

- Skill: `ivo-toby/talon-setup-docker` (Agent Skill)
- Install (CLI): `npx get-skill add ivo-toby/talon-setup-docker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivo-toby/talon-setup-docker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ivo-toby (https://skillmd.com/u/ivo-toby)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/ivo-toby/talon-setup-docker

---


# Talon setup — docker bundle

Guide the user through configuring the Talon starter bundle. This is a
conversational wizard — **one question at a time**, act on the answer,
move on.

## Core principles

- **Docker-first.** The bundle ships a published image and a host-side
  `talonctl` wrapper. Never run `npx talonctl`, `npm install`, or
  `node dist/index.js`.
- **`talonctl` requires the daemon to be running.** The wrapper is a
  `docker exec` into the `talond` container. For first-time setup, the
  user edits `.env` and `config/talond.yaml` manually, then boots the
  daemon, then `talonctl` is available for everything else.
- **One question at a time.** Never dump a wall of options.
- **No secrets.** Never ask for or write actual tokens. Only show
  `${ENV_VAR}` placeholders in `config/talond.yaml` and MCP `headers` / `env`
  fields. Real values go in `.env`.
- **Show output.** When you run a command, show what came back.

## Detect state first

Before asking anything, look at the bundle directory:

```bash
ls -la                                                              # bundle layout
test -f .env && echo ".env present" || echo ".env missing"           # exists?
grep -oE '^[A-Z][A-Z0-9_]*' .env 2>/dev/null | sort -u                # which env vars set? (names only)
test -f config/talond.yaml && echo "yaml present" || echo "yaml missing"
docker ps --filter name=talond --format '{{.Names}} {{.Status}}'    # daemon running?
```

**Never print secret values.**

- `.env` contains real secrets — only inspect variable *names*, never
  `cat .env`.
- `config/talond.yaml` *should* only contain `${ENV_VAR}` placeholders,
  but some users hand-paste literal keys. Don't `cat` it either. When
  the daemon is running, use `talonctl config-show` (auto-masked). Until
  then, inspect specific sections you need with `grep -A` for the keys
  you're checking, and never display lines that match `apiKey:`,
  `botToken:`, `password:`, `secret`, or `token:` patterns with a
  literal value.

If you need to *show* a config snippet to the user, use:

```bash
talonctl config-show 2>/dev/null         # post-boot, masked
# OR pre-boot, redact inline:
sed -E 's/^(  *(apiKey|botToken|.*[Tt]oken|.*[Ss]ecret|password): )(.+)$/\1***MASKED***/' config/talond.yaml
```

Use the state to skip steps:

| State | Action |
|-------|--------|
| `.env` missing | Run `cp .env.example .env`, fill in step 2 |
| `config/talond.yaml` missing | Run `cp config/talond.example.yaml config/talond.yaml`, edit in step 3 |
| Daemon already running | Skip to talonctl-based additions (step 6) |
| All configured + daemon running | Present the menu (see "Returning user menu") |

### Returning user menu

If everything is configured:

```
What would you like to do?
  a) Switch AI provider
  b) Add another channel (Telegram, Slack, …)
  c) Add or modify a persona
  d) Bind/unbind a persona to a channel
  e) Manage scheduled tasks
  f) Run health check (talonctl doctor)
  g) Show current config (talonctl config-show)
  h) View daemon logs (docker compose logs -f talond)
  i) Restart the daemon
```

## Available talonctl commands (post-boot)

All commands run via the bundle's `bin/talonctl` wrapper (or the
installed `talonctl` if `./install.sh` has been run):

| Command | Purpose |
|---------|---------|
| `talonctl status` | Daemon health, active runs, queue depth |
| `talonctl doctor` | Validate config + environment |
| `talonctl config-show` | Show current config (secrets masked) |
| `talonctl env-check` | List config and MCP env references (names/status only) |
| `talonctl list-channels` | Configured channels |
| `talonctl add-channel --name <n> --type <t>` | Add a channel |
| `talonctl remove-channel --name <n>` | Remove a channel |
| `talonctl list-personas` | Configured personas |
| `talonctl add-persona --name <n>` | Scaffold a persona dir + add to config |
| `talonctl remove-persona --name <n>` | Remove a persona |
| `talonctl bind --persona <p> --channel <c>` | Bind persona to channel |
| `talonctl unbind --persona <p> --channel <c>` | Remove a binding |
| `talonctl add-mcp --skill <s> --name <n> --transport <stdio|sse|http> ...` | Add an MCP server to a skill |
| `talonctl auth-mcp <skill>:<server> --docker` | Authorize an HTTP MCP server from the host browser |
| `talonctl list-providers` | Configured AI providers |
| `talonctl add-provider --name <n> --command <c> [--context both] [--type <t>]` | Add a provider |
| `talonctl set-default-provider --name <n> --context <ctx>` | Set default provider |
| `talonctl test-provider --name <n>` | Verify a provider connects |
| `talonctl list-capabilities` | All available capability labels |
| `talonctl set-capabilities --persona <p> --add <labels>` | Add capabilities |
| `talonctl set-capabilities --persona <p> --remove <labels>` | Remove capabilities |
| `talonctl list-schedules` | Configured scheduled tasks |
| `talonctl add-schedule --persona <p> --channel <c> --cron <expr> --label <l> --prompt <text>` | Add a scheduled task |
| `talonctl remove-schedule <id>` | Remove a scheduled task |

Use these for all post-boot mutations. **Do not edit `config/talond.yaml`
by hand** once the daemon is running — talonctl handles it correctly.

## First-time setup flow

### Step 1: Pick an AI provider

Ask: **"Which AI provider do you want to use?"**

```
a) Codex (Anthropic API)            — default, smartest, costs $
b) OpenAI-compatible endpoint        — local Ollama, vLLM, Groq, Together, custom
c) Gemini CLI                        — Google's CLI, preinstalled in the image
d) Codex CLI                         — OpenAI's CLI, preinstalled in the image
```

All four work out of the box. `Codex` (bundled in the Agent SDK),
`codex`, and `gemini` ship in the container image; `openai-compatible`
runs in-process.

For (a) ask for nothing else here — defaults work.

For (b) ask four things, **one at a time**:
- "What should this provider be called? (default: `openai-compatible`; use a
  distinct name like `ollama-mac` when keeping another OpenAI-compatible
  endpoint too)"
- "What's the base URL? (e.g. `https://api.groq.com/openai/v1`,
  `http://host.docker.internal:11434/v1` for local Ollama, etc.)"
- "What model name does the endpoint serve?
  (e.g. `qwen3-coder:30b`, `llama-3.3-70b-versatile`)"
- "Does this foreground provider expose `/v1/responses`, and does it support
  stateful `previous_response_id` chaining?" → if yes to both, remember to add
  `--api-mode responses --session-mode previous_response_id` or
  `agentRunner.providers.*.options.apiMode: responses` plus
  `agentRunner.providers.*.options.sessionMode: previous_response_id`
- "Does the endpoint need an API key?" → if yes, ask the env var name
  to use (default: `OPENAI_COMPATIBLE_API_KEY`)

For (c)/(d), note one caveat: Gemini CLI and Codex CLI store auth/config
under `~/.gemini` / `~/.codex` inside the container, which is wiped on
container recreation. Recommend API-key auth (`GOOGLE_AI_API_KEY` /
`OPENAI_API_KEY` in `.env`, read fresh each run). OAuth state needs a
`/home/talond` bind-mount to persist — see `docs/providers.md`.

### Step 2: Configure `.env`

If `.env` doesn't exist: `cp .env.example .env`

Ask: **"Which channel do you want to connect first?"** Answer determines
which env var the user needs to fill:

| Channel | Env var(s) |
|---------|-----------|
| Telegram | `TELEGRAM_BOT_TOKEN` (from @BotFather) |
| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `SLACK_SIGNING_SECRET` |
| Discord | `DISCORD_BOT_TOKEN` |
| WhatsApp Business | `WHATSAPP_API_KEY` |
| WhatsApp Baileys | (no env, uses QR-code auth at first boot) |
| Email | IMAP/SMTP credentials (see add-email skill) |
| Terminal | `TERMINAL_TOKEN` (just `talonctl chat`) |

Plus the provider env from step 1 (e.g. `ANTHROPIC_API_KEY` for Codex).

Tell the user **exactly** which lines to uncomment/fill in `.env`.
Do not write the actual secrets to disk.

### Step 3: Configure `config/talond.yaml`

If `config/talond.yaml` doesn't exist:
`cp config/talond.example.yaml config/talond.yaml`

The default config uses Codex + Telegram. If the user picked something
else in step 1, walk them through the edits:

#### Edit the persona

Find:
```yaml
personas:
  - name: assistant
    model: Codex-sonnet-4-6
    provider: Codex
```

If provider is OpenAI-compatible:
```yaml
    model: <model from step 1>
    provider: <provider name from step 1>
```

If Gemini CLI:
```yaml
    model: gemini-2.5-pro
    provider: gemini-cli
```

#### Replace the `agentRunner.providers` block

For Codex (default), no change.

For OpenAI-compatible — replace the `Codex:` block under
`agentRunner.providers:` with:

```yaml
    <provider name from step 1>:
      enabled: true
      type: openai-compatible       # omit only when the provider name itself is openai-compatible
      command: node
      contextWindowTokens: 32000
      options:
        baseUrl: <base URL from step 1>
        defaultModel: <model from step 1>
        providerId: <a short slot name, e.g. "groq" or "ollama">
        # OpenAI-compatible /v1/responses endpoints only.
        # Add sessionMode only for stateful previous_response_id chaining.
        # Stored response ids are scoped by provider + model, so model swaps start fresh.
        # Omit sessionMode for Ollama, vLLM, Groq, Together, and chat-completions-only endpoints.
        # apiMode: responses
        # sessionMode: previous_response_id
        toolOutputCap: 4000
```

Apply the same change to `backgroundAgent.providers` (or set
`backgroundAgent.enabled: false` if you don't need background work).

For post-boot changes, prefer talonctl instead of editing YAML:

```bash
talonctl add-provider --name <provider name> \
  --type openai-compatible \
  --command node \
  --context both \
  --context-window 32000 \
  --default-model <model from step 1> \
  --base-url <base URL from step 1> \
  --provider-id <slot name> \
  --enabled
```

For foreground endpoints that expose `/v1/responses`, append
`--api-mode responses`. Add `--session-mode previous_response_id` only when the
endpoint supports stateful response-id chaining. Talon scopes stored response
ids by provider and model, so changing the model on the same provider starts a
fresh session and replays assembled prior-conversation state.

#### Replace `auth.providers`

For Codex, the default block is fine.

For OpenAI-compatible:
```yaml
auth:
  mode: api_key
  providers:
    <slot name from above>:
      baseURL: <base URL from step 1>
      # apiKey: ${YOUR_ENV_VAR}   # uncomment if the endpoint needs one
```

#### Set the channel's `allowedChatIds` / equivalent

For Telegram, find the channels block and set the chat ID the bot is
allowed to talk to (find your ID via [@userinfobot](https://t.me/userinfobot)):

```yaml
channels:
  - type: telegram
    name: personal-telegram
    config:
      botToken: ${TELEGRAM_BOT_TOKEN}
      allowedChatIds:
        - "<your-numeric-chat-id>"        # must be a string, not a number
      pollingTimeoutSec: 30
```

For other channels, refer to the matching `add-*` skill.

### Step 4: Boot the daemon

```bash
./install.sh                                  # ensures data/ + userdata/ exist + installs talonctl wrapper
docker compose up -d                          # detached
docker compose logs --tail=50 talond          # confirm clean boot — no -f, no head; just the last 50 lines
```

Look for `bootstrap: config loaded`, the channel connector starting,
and `daemon: running`. If the daemon exits, the logs will say why
(usually a config validation error).

### Step 5: Verify

```bash
talonctl status                # health, queue depth, channels, personas
talonctl doctor                # full validation
talonctl list-channels         # confirms the channel is registered
talonctl test-provider --name <provider-name>   # round-trips a request
```

Then ask the user to **send a real message** to the configured channel
(Telegram DM, Slack message, etc.) and confirm a reply lands. Tail
`docker compose logs -f talond` while they do.

### Step 6: Optional additions

Once boot is verified, anything else uses `talonctl`:

- **Add another channel** — invoke the matching channel skill (`/add-slack`,
  `/add-discord`, etc.) OR `talonctl add-channel` directly.
- **Add another persona** — `talonctl add-persona --name <n>`, then edit
  the generated `personas/<name>/system.md`.
- **Bind persona ↔ channel** — `talonctl bind --persona <p> --channel <c>`.
- **Adjust capabilities** — `talonctl set-capabilities --persona <p> --show`
  to see current, then `--add` or `--remove`.
- **Enable image handling** — an Inspection needs exactly two things: `vision`
  listed under the persona's `subagents` key in `talond.yaml` (there is no
  `talonctl` flag for persona sub-agent assignment) plus the existing
  `subagent.invoke` capability. The shipped `vision` manifest declares
  `requiredCapabilities: []`, so no image capability is part of an Inspection.
  `image.read:thread` is an **independent** grant: it exposes `image_lookup`, the
  model-free reader for the thread's Images and saved Findings, needs no vision
  assignment and never calls a model, and is recommended (so a persona can re-read
  an existing Finding instead of paying for a repeat Inspection) rather than
  required. None of it is automatic on upgrade. Uploads are ingested and described
  regardless. Pixels go only to the `vision` sub-agent; the persona itself stays
  text-only, so a text-only foreground model still supports images. Only
  `anthropic`, `openai`, `google`, and `ollama` may appear in a vision chain — a
  text-only override such as `claude-code` or `codex-sandbox` is rejected at
  config load, not silently skipped.

  The published image bundles Sharp and proves it at build time: each release
  target (linux/amd64 and linux/arm64, both glibc) loads Sharp and normalizes a
  tiny JPEG during its build, so image support needs no extra packages inside the
  container. That gate is architecture-specific — a custom base image or a
  musl/Alpine variant is not covered by it, so re-run the same check before
  claiming image support there. Normalized JPEGs live under `dataDir`
  (`threads/<thread_id>/attachments/images/`), so the `talond-data` volume must
  persist across restarts or Inspections lose their files. Retention deletes only
  the JPEG, after `images.retentionHours` (default 24h); Image records, GPS/EXIF
  and Findings persist until separately deleted and can appear in replies.
  Inspections work from normal messages and scheduled tasks, not from background
  agents. The `images:` block's defaults suit most setups; `maxInputPixels`
  (default 100 MP) guards against decompression bombs and `maxNormalizedBytes`
  (default 3.75 MB) should be lowered if the vision provider has a smaller
  per-image limit. Changing `images` needs a container restart — `talonctl
  reload` keeps the running values.
- **Schedule tasks** — `talonctl add-schedule …` (see `/manage-schedules`).
- **Add MCP servers** — `talonctl add-mcp …`. Pre-built MCP servers for
  GitHub, Atlassian, Gmail, Slack, etc. are documented in
  `starter/docs/troubleshooting.md` and the upstream MCP server registry.

#### MCP authentication

For static HTTP tokens or stdio credentials, use `${ENV_VAR}` placeholders
and keep the values in `.env`:

```bash
talonctl add-mcp --skill work-search --name internal-search --transport http \
  --url https://search.example.com/mcp \
  --headers 'Authorization=Bearer ${SEARCH_API_TOKEN}'
talonctl env-check
```

For OAuth, use an HTTPS resource URL, add the server with `--auth oauth2`, then
authorize it from the host browser:

```bash
talonctl add-mcp --skill work-search --name glean --transport http \
  --url https://search.example.com/mcp --auth oauth2
talonctl auth-mcp work-search:glean --docker
```

If the authorization server does not support Dynamic Client Registration,
provide `--client-id-env`, pin it with `--authorization-server-issuer https://<issuer>`,
and optionally set `--client-secret-env` when adding it.
The optional `--token-endpoint-auth-method` is `client_secret_post` or
`client_secret_basic`. The starter publishes the temporary OAuth callback on
`127.0.0.1:8788` only; custom `--port` values must match the Compose mapping.
The daemon reads the new token bundle on its next agent run, so no restart is
needed. `env-check` scans MCP headers, stdio env values, and OAuth client
references without showing secret values.
On OAuth-backed runs, native shell/filesystem tools are disabled while Talon
tools and configured MCP servers remain available. Codex CLI is rejected
because it cannot disable those built-ins; this is not OS-level isolation from
same-user processes. Use `--scopes` to request only the OAuth scopes the persona
needs; Talon does not automatically request every advertised scope.
Re-run `auth-mcp` after changing the MCP resource URL or configured scopes;
cached credentials are bound to both.
Talon expands MCP header/stdio env references once and rejects resulting
values that still look like provider environment-variable syntax.

#### MCP request timeout and tool-output cap

When an MCP server returns large results or makes slow calls, set per-server
limits to keep the agent's context under control. Both keys live under
`config` in the skill's MCP JSON (mounted under `/skills`): add
`"timeoutMs": <integer ≥ 1000>` and `"toolOutputCap": <integer ≥ 0>`, and
`talonctl add-mcp` accepts the same values as `--timeout-ms` /
`--tool-output-cap` flags:

```bash
talonctl add-mcp --skill work-search --name glean --transport http \
  --url https://search.example.com/mcp --auth oauth2 \
  --timeout-ms 180000 --tool-output-cap 12000
```

- `timeoutMs` (integer ≥ 1000): per-MCP-request timeout. Omitted → Mastra's
  60 000 ms default. The outer query timeout still wins.
- `toolOutputCap` (integer ≥ 0): caps a tool result before it enters message
  history. `0` disables excerpting for that server only. Omitted →
  provider-level `toolOutputCap` or 4 000. Precedence: server > provider >
  4 000; provider-level `0` disables only the fallback — an explicit positive
  per-server cap still applies.

Provider compatibility: only the Mastra / OpenAI-compatible provider honors
these limits; native Claude, Gemini, and Codex CLI runs omit the metadata, so
the limits have no effect there. The caps bound MCP model-history injection,
not network bytes: when any effective MCP cap is positive, MCP results (also
zero-cap servers) stay in a run-local in-memory store retrievable via
`fetch_tool_output` in up to 8 000 content-character slices (framing
additional) when available — a discovered MCP tool that already owns that
reserved name takes it and the synthetic recovery is skipped; with all
effective MCP caps at `0` no wrapper/recovery is injected. Built-in
file/shell tools are unchanged.

For an existing server, edit only the two numeric keys under `config` in the
mounted skill JSON directly (preserving name/URL/transport/headers/env/auth)
— `add-mcp` rejects duplicate names. Specifically for Glean: the repository
definition (`skills/glean/mcp/glean.json`) pre-sets `timeoutMs: 180000` /
`toolOutputCap: 12000`, but that file is git-ignored and NOT packaged in the
Docker image or either starter bundle; rebuilding the image does not update a
Glean JSON you already copied into your mounted `skills/` tree. Add or replace
the two keys under `config` in your existing copy (generic URL, preserve your
real URL/auth):

```json
{
  "name": "glean",
  "config": {
    "name": "glean",
    "transport": "http",
    "url": "https://search.example.com/mcp",
    "timeoutMs": 180000,
    "toolOutputCap": 12000
  }
}
```

Until packaging bundles the Glean skill, any release claiming bundled Glean
limit defaults is a release blocker.

#### Subscription-backed sub-agents

Only offer this when the user explicitly wants a small, bounded sub-agent task
to use a Claude Code or Codex subscription instead of an API credential. It is
not a foreground/background provider and does not use `talonctl add-provider`.
Do not offer direct Codex CLI as a sub-agent model: its agentic mode cannot yet
enforce Talon's filesystem-read boundary.

The CLI executable and its authenticated subscription state must exist inside
the running `talond` container for this to work; a host-machine login is not
automatically visible in Docker. For a headless Claude subscription setup,
inject the official `CLAUDE_CODE_OAUTH_TOKEN` into the container's environment
instead. For Codex, enable the `codex-sandbox` Compose profile, authenticate
with `CODEX_HOME=/auth` inside its own `codex-runner` volume, and use a dedicated
Codex account; never mount the host's `~/.codex`, Talon data/config, or a Docker
socket into that runner. Before enabling it, explain that each attempt is a
single isolated generation with no Talon tools, MCP servers, persona tools, or
persistent session. Claude Code has tools disabled. The Codex runner requires
ChatGPT auth and fails closed on built-in tool activity. Subscription quota is
external to Talon and no API-dollar estimate is produced. `docker compose
--profile codex-sandbox up -d` starts the runner with `restart: unless-stopped`,
so it returns after reboots; never start a runner Node process in the Talon
container or on the host. Talon waits for the authenticated runner before it
starts channels or queue processing when `codex-sandbox` is enabled.

There is no `talonctl` command for `subagentCli` or `subagentSandbox` yet. With
user approval, make the narrow manual `config/talond.yaml` change shown in the
README's **Subscription-backed sub-agents** section, then run `talonctl doctor` and
restart the daemon with `docker compose restart talond`; `talonctl reload` does
not rebuild the sub-agent resolver. Do not make a live sub-agent invocation
solely as a test, because it would consume subscription quota.

Each mutation modifies `config/talond.yaml`. The daemon **does not
auto-reload** — after a mutation, tell the user to apply it:

```bash
talonctl reload          # hot-reload via IPC; works for most changes
# or for changes that require a full restart:
docker compose restart talond
```

After `add-channel` or `add-provider`, also run:
```bash
talonctl env-check       # confirm any new ${ENV_VAR} placeholders are set in .env
talonctl test-provider --name <n>   # if a provider was added
```

## Rules

1. **Never write actual secrets.** Use `${ENV_VAR}` references in
   `config/talond.yaml` and MCP `headers` / `env`; real values are in `.env`,
   edited by the user.
2. **Use `talonctl` for all post-boot mutations.** Exceptions: persona
   `system.md` files (these are agent-facing prompts and benefit from
   hand-editing) and `.env`.
3. **One question per message.** Do not batch.
4. **Show command output.** Let the user see what happened.
5. **Don't start or stop the daemon** without telling the user. Boot
   only after they've confirmed the config is ready. Use
   `docker compose up -d` (detached) so logs don't block their terminal.
6. **Always validate.** After meaningful changes, run `talonctl doctor`
   and `talonctl env-check`. After provider changes, run
   `talonctl test-provider`.
7. **Tell users when something is broken or unsupported.** Some channel
   skills (add-telegram, add-slack, …) were lifted from the native-install
   workflow and still reference `npx talonctl`; treat their guidance as
   *informational* and execute the equivalent via the docker wrapper.

## Differences from `talon-setup` (native)

This skill replaces the native-install `talon-setup` skill for users of
the docker starter bundle. Key differences:

- No prereq check for `node_modules/`, `dist/`, or local `node --version`
  — the image ships everything.
- No `npx talonctl setup` or `talonctl migrate` step — the daemon
  bootstraps + migrates on first boot.
- Provider menu lists OpenAI-compatible as a first-class option.
- Service install via systemd is skipped — `docker compose up -d`
  + `restart: unless-stopped` is the equivalent.
- Daemon start is `docker compose up -d`, never `node dist/index.js`.

