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
talonctlwrapper. Never runnpx talonctl,npm install, ornode dist/index.js. talonctlrequires the daemon to be running. The wrapper is adocker execinto thetalondcontainer. For first-time setup, the user edits.envandconfig/talond.yamlmanually, then boots the daemon, thentalonctlis 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 inconfig/talond.yamland MCPheaders/envfields. 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:
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.
.envcontains real secrets — only inspect variable names, nevercat .env.config/talond.yamlshould only contain${ENV_VAR}placeholders, but some users hand-paste literal keys. Don'tcatit either. When the daemon is running, usetalonctl config-show(auto-masked). Until then, inspect specific sections you need withgrep -Afor the keys you're checking, and never display lines that matchapiKey:,botToken:,password:,secret, ortoken:patterns with a literal value.
If you need to show a config snippet to the user, use:
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 --name --transport <stdio | sse |
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 likeollama-macwhen keeping another OpenAI-compatible endpoint too)" - "What's the base URL? (e.g.
https://api.groq.com/openai/v1,http://host.docker.internal:11434/v1for 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 statefulprevious_response_idchaining?" → if yes to both, remember to add--api-mode responses --session-mode previous_response_idoragentRunner.providers.*.options.apiMode: responsesplusagentRunner.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) |
| 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:
personas:
- name: assistant
model: Codex-sonnet-4-6
provider: Codex
If provider is OpenAI-compatible:
model: <model from step 1>
provider: <provider name from step 1>
If Gemini CLI:
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:
<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:
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:
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):
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
./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
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.) ORtalonctl add-channeldirectly.Add another persona —
talonctl add-persona --name <n>, then edit the generatedpersonas/<name>/system.md.Bind persona ↔ channel —
talonctl bind --persona <p> --channel <c>.Adjust capabilities —
talonctl set-capabilities --persona <p> --showto see current, then--addor--remove.Enable image handling — an Inspection needs exactly two things:
visionlisted under the persona'ssubagentskey intalond.yaml(there is notalonctlflag for persona sub-agent assignment) plus the existingsubagent.invokecapability. The shippedvisionmanifest declaresrequiredCapabilities: [], so no image capability is part of an Inspection.image.read:threadis an independent grant: it exposesimage_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 thevisionsub-agent; the persona itself stays text-only, so a text-only foreground model still supports images. Onlyanthropic,openai,google, andollamamay appear in a vision chain — a text-only override such asclaude-codeorcodex-sandboxis 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 thetalond-datavolume must persist across restarts or Inspections lose their files. Retention deletes only the JPEG, afterimages.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. Theimages:block's defaults suit most setups;maxInputPixels(default 100 MP) guards against decompression bombs andmaxNormalizedBytes(default 3.75 MB) should be lowered if the vision provider has a smaller per-image limit. Changingimagesneeds a container restart —talonctl reloadkeeps 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 instarter/docs/troubleshooting.mdand the upstream MCP server registry.
MCP authentication
For static HTTP tokens or stdio credentials, use ${ENV_VAR} placeholders
and keep the values in .env:
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:
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:
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.0disables excerpting for that server only. Omitted → provider-leveltoolOutputCapor 4 000. Precedence: server > provider > 4 000; provider-level0disables 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):
{
"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:
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:
talonctl env-check # confirm any new ${ENV_VAR} placeholders are set in .env
talonctl test-provider --name <n> # if a provider was added
Rules
- Never write actual secrets. Use
${ENV_VAR}references inconfig/talond.yamland MCPheaders/env; real values are in.env, edited by the user. - Use
talonctlfor all post-boot mutations. Exceptions: personasystem.mdfiles (these are agent-facing prompts and benefit from hand-editing) and.env. - One question per message. Do not batch.
- Show command output. Let the user see what happened.
- 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. - Always validate. After meaningful changes, run
talonctl doctorandtalonctl env-check. After provider changes, runtalonctl test-provider. - 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 localnode --version— the image ships everything. - No
npx talonctl setuportalonctl migratestep — 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 -drestart: unless-stoppedis the equivalent.
- Daemon start is
docker compose up -d, nevernode dist/index.js.