# Talon.setup

> Use when setting up Talon for the first time, adding channels or personas to an existing config, or running validation. Also use when the user says "configure talon", "add a channel", "add a persona", "add provider", "set up the daemon", "add schedule", or "configure providers".

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

---


# Talon setup skill

Guide the user through setting up and configuring Talon interactively. This is a
conversational wizard. Ask one question at a time, act on the answer, move on.

## Core principles

- **One question at a time.** Never dump a wall of questions.
- **Detect state first.** Skip steps that are already done.
- **Use talonctl commands.** Never edit talond.yaml directly except system prompts and task prompts.
- **No secrets.** Never ask for or write actual tokens. Use `${ENV_VAR}` references in config and MCP `headers` / `env` values only.
- **Show what you do.** When running commands, show the output.

## Available talonctl commands

All config mutations go through these commands:

| Command | Purpose |
|---------|---------|
| `npx talonctl setup` | Bootstrap (dirs, config, migrations) |
| `npx talonctl add-channel --name <n> --type <t>` | Add a channel |
| `npx talonctl add-persona --name <n>` | Scaffold persona + add to config |
| `npx talonctl add-skill --name <n> --persona <p> [--format <fmt>]` | Add a skill to a persona |
| `npx talonctl bind --persona <p> --channel <c>` | Bind persona to channel |
| `npx talonctl unbind --persona <p> --channel <c>` | Remove binding |
| `npx talonctl add-mcp --skill <s> --name <n> --transport <stdio|sse|http> ...` | Add MCP server |
| `npx talonctl auth-mcp <skill>:<server>` | Authorize an HTTP MCP server with OAuth |
| `npx talonctl add-provider --name <n> --command <c> [--context both] [--type <t>]` | Add a provider |
| `npx talonctl set-default-provider --name <n> --context <ctx>` | Set default provider |
| `npx talonctl test-provider --name <n>` | Test a provider works |
| `npx talonctl list-providers` | Show all providers |
| `npx talonctl list-channels` | Show channels |
| `npx talonctl list-personas` | Show personas |
| `npx talonctl list-skills` | Show skills |
| `npx talonctl list-schedules` | Show scheduled tasks |
| `npx talonctl add-schedule --persona <p> --channel <c> --cron <expr> --label <l> --prompt <text>` | Add scheduled task |
| `npx talonctl remove-schedule <id>` | Remove a scheduled task |
| `npx talonctl list-capabilities` | Show all available capability labels |
| `npx talonctl set-capabilities --persona <p> --allow <labels>` | Set persona capabilities |
| `npx talonctl set-capabilities --persona <p> --add <labels>` | Add capabilities to persona |
| `npx talonctl set-capabilities --persona <p> --remove <labels>` | Remove capabilities from persona |
| `npx talonctl set-capabilities --persona <p> --show` | Show persona's current capabilities |
| `npx talonctl env-check` | Audit env var placeholders |
| `npx talonctl config-show` | Show effective config (secrets masked) |
| `npx talonctl remove-channel --name <n>` | Remove a channel |
| `npx talonctl remove-persona --name <n>` | Remove a persona |
| `npx talonctl migrate` | Run database migrations |
| `npx talonctl doctor` | Validate configuration |

## State detection

Before starting, check the current state:

```
Check these files/directories:
- talond.yaml              → config exists?
- node_modules/            → dependencies installed?
- dist/                    → project built?
- data/                    → data directory exists?
- data/talond.sqlite       → database initialized?
- .env                     → env file with secrets?
```

### Entry points

| State | Action |
|-------|--------|
| No `talond.yaml` | Full flow from step 1 |
| Config exists, no providers configured | Skip to provider setup |
| Config exists, no channels | Skip to channel configuration |
| Config exists, has channels and personas | Show menu |

### Returning user menu

If setup is already complete, present:

```
What would you like to do?
  a) Add or configure a provider (Codex, Gemini)
  b) Add a channel
  c) Add a persona
  d) Add a skill to a persona
  e) Add or manage scheduled tasks
  f) Bind/unbind persona to channel
  g) Run validation (doctor)
  h) Show current config summary
  i) Test a provider
  j) Check environment variables
```

## Skill formats

When adding a skill, choose a format with `--format`:

- **SKILL.md** (`--format skillmd`, recommended for new skills): Single markdown file with YAML frontmatter for metadata and markdown body for instructions. No separate prompts directory.
- **skill.yaml** (`--format yaml`, default/legacy): Separate YAML manifest file plus a `prompts/` directory for prompt fragments.

Example:
```bash
# New style (recommended)
npx talonctl add-skill --name my-skill --persona assistant --format skillmd

# Legacy style (default if --format is omitted)
npx talonctl add-skill --name my-skill --persona assistant
```

## Full setup flow

### Step 1: Prerequisites

Check each prerequisite. Report status. Fix what can be fixed automatically.

```
1. Node.js >= 22          → check `node --version`
2. Dependencies installed → check node_modules/, run `npm install` if not
3. Project built          → check dist/, run `npm run build` if not
4. AI providers installed → check `Codex --version` and/or `gemini --version`
```

For provider binaries not on PATH, ask for the full path (e.g. `/home/user/.npm-global/bin/gemini`).

At least one provider must be installed and authenticated. Check both:

- **Codex**: `Codex --version`. Auth: `Codex auth login` or valid Anthropic API key.
- **Gemini CLI**: `gemini --version`. Auth: run `gemini` once interactively for OAuth, or set `GEMINI_API_KEY`.

If neither is installed, stop and explain how to install at least one.

### Step 2: Bootstrap

Skip if `talond.yaml` already exists.

Run: `npx talonctl setup`

This creates directories, generates default config, runs migrations, validates.

### Step 3: Provider configuration

This step configures which AI providers Talon uses for interactive conversations and background tasks.

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

```
a) Codex only (default)
b) Gemini CLI only
c) Both (recommended if both are installed)
d) OpenAI-compatible / Ollama endpoint
```

For each selected provider, run `add-provider`:

```bash
# Codex (if selected)
npx talonctl add-provider --name Codex \
  --command Codex \
  --context both \
  --context-window 200000 \
  --threshold-ratio 0.5 \
  --enabled

# Gemini (if selected)
npx talonctl add-provider --name gemini-cli \
  --command <path-to-gemini> \
  --context both \
  --context-window 1000000 \
  --threshold-ratio 0.8 \
  --enabled
```

For Gemini, ask: **"Which Gemini model? (default: gemini-2.5-pro)"**

Available models: gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite.

If a model is specified, add `--default-model <model>` to the add-provider command.

For an OpenAI-compatible endpoint such as local Ollama, Ollama Cloud, vLLM, or
Groq, use a unique provider name when multiple endpoints should coexist. Use
`type: openai-compatible` via the CLI flag so the provider name remains
distinct for persona routing and run history:

```bash
npx talonctl add-provider --name <provider-name> \
  --type openai-compatible \
  --command node \
  --context both \
  --context-window <tokens> \
  --default-model <model> \
  --base-url <https-or-http-base-url-ending-in-/v1> \
  --provider-id <auth-provider-id> \
  --enabled
```

If the foreground endpoint exposes `/v1/responses`, add `--api-mode responses`.
If it also supports stateful `previous_response_id` chaining, add
`--session-mode previous_response_id`. That makes Talon resume conversations
with `previous_response_id` so oMLX-style endpoints can reuse their
response-state chain and prefix/KV cache. Talon scopes those stored response
ids by provider and model, so testing a different model on the same provider
starts a fresh session and receives assembled prior-conversation state. Do not
use `previous_response_id` session mode for background-only providers, Ollama,
vLLM, Groq, or ordinary chat-completions-only endpoints.

Examples:
- Existing Ollama Cloud can remain named `openai-compatible` with
  `providerId: ollama`.
- A separate local Mac endpoint can be named `ollama-mac` with
  `--type openai-compatible --base-url http://<mac-host>:11434/v1
  --provider-id ollama-mac`.
- A local oMLX endpoint can be named `omlx-local` with
  `--type openai-compatible --base-url http://<mac-host>:8000/v1
  --provider-id omlx-local --context agent-runner --api-mode responses
  --session-mode previous_response_id`.

Add matching credentials under `auth.providers.<provider-id>` if the endpoint
requires them. Local Ollama usually does not require an API key.

If both providers are configured, ask: **"Which should be the default for conversations?"**

```bash
npx talonctl set-default-provider --name <choice> --context agent-runner
```

Then: **"And for background tasks?"** (explain: background tasks run async, cheaper/faster models work well here)

```bash
npx talonctl set-default-provider --name <choice> --context background
```

Test each configured provider:

```bash
npx talonctl test-provider --name Codex
npx talonctl test-provider --name gemini-cli
npx talonctl test-provider --name <openai-compatible-alias>
```

If a test fails, troubleshoot:
- Binary not found → check the command path, `which Codex` or `which gemini`
- Auth failure → Codex: `Codex auth login`. Gemini: run `gemini` interactively once for OAuth.
- JSON parse failure → Gemini CLI version too old, see https://github.com/google-gemini/gemini-cli for upgrade instructions

#### Optional: subscription-backed sub-agents

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

First confirm that the selected CLI is installed and already authenticated as
the same OS user that runs `talond`, or that the official
`CLAUDE_CODE_OAUTH_TOKEN` is supplied for a headless subscription setup. For
Codex, first ensure Docker or rootless Podman is available on Linux/macOS, then
follow the README's managed runner login and container commands using a dedicated
Codex account; never add the user's host `~/.codex` directory as a Talon mount
or start `node dist/codex-runner/index.js` on the Talon host. For a Linux
systemd deployment, use `deploy/install-service.sh --codex-runner`; it starts
the contained runner before Talon automatically on future boots. On macOS, use
the documented `--restart unless-stopped` container and a container runtime that
starts at login. Show the user the `subagentCli`, `subagentSandbox`, and
`subagents` example from the README's **Subscription-backed sub-agents** section. Explain the limits before
they enable it: one isolated generation per task, no Talon tools/MCP/persona
tool access, no persistent session, and no estimated API-dollar cost. Claude
Code has tools disabled. Codex runs only in the `codex-runner` container with
no Talon data/config mounts or Docker socket, uses ChatGPT auth only, and fails
closed on built-in tool activity. The configured sub-agent timeout aborts the
runner request before failover; `maxTokens` is advisory. When the Codex runner
is enabled, Talon waits for its authenticated readiness endpoint at startup and
does not start channels or dequeue work until it is ready.

There is no `talonctl` configuration command for `subagentCli` or
`subagentSandbox` yet, so make this narrowly-scoped manual YAML exception only
after user confirmation. Run
`npx talonctl doctor --config talond.yaml` after the edit, then restart the
daemon because hot reload does not rebuild the sub-agent resolver. Do not run a
live sub-agent merely to test it: that would consume the user's subscription quota.

### Step 4: Channel configuration

Ask: **"Which channel do you want to connect first?"**

```
a) Telegram
b) Slack
c) Discord
d) WhatsApp
e) Email
f) Terminal (for CLI chat)
g) Skip for now
```

Invoke the matching per-channel skill for the full setup walkthrough:

| Channel | Skill to invoke |
|---------|----------------|
| Telegram | `/add-telegram` |
| Slack | `/add-slack` |
| Discord | `/add-discord` |
| WhatsApp | `/add-whatsapp` |
| Email | `/add-email` |
| Terminal | `/add-terminal` |

Each skill handles: bot/app creation, credentials, config, env vars, verification, and troubleshooting.

Ask: **"Add another channel?"** Loop until done.

### Step 5: Persona configuration

Ask: **"Let's create a persona. What should this agent be called?"**

1. Accept a name (suggest "assistant")
2. Run: `npx talonctl add-persona --name <name>`
3. Ask these questions one at a time:
   - **"What should {name} do?"** (purpose)
   - **"What tone?"** (professional/casual/technical/friendly)
   - **"Any specific constraints?"** (optional)
4. Generate a system prompt from the answers
5. Show it to the user for review
6. Write the approved prompt to `personas/{name}/system.md`
7. Ask which channels to bind:
   - Run: `npx talonctl list-channels` to show options
   - For each selected: `npx talonctl bind --persona <name> --channel <channel>`

Ask: **"Add another persona?"** Loop until done.

### Step 5b: Capability configuration

After creating a persona, show what capabilities it has and what's available.

1. Run: `npx talonctl set-capabilities --persona <name> --show`
2. Run: `npx talonctl list-capabilities`
3. Explain: "Your persona was created with sensible defaults: memory access, HTTP requests,
   and schedule management. Here are all available capabilities."
4. Ask: **"Want to adjust capabilities for {name}?"**

If yes, help the user decide which to add or remove:

- For agents that should message other channels: `npx talonctl set-capabilities --persona <name> --add "channel.send:*"`
- For agents that need database access: `npx talonctl set-capabilities --persona <name> --add "db.query:own"`
- For agents that run background tasks: `npx talonctl set-capabilities --persona <name> --add "subagent.background"`
- For agents that invoke sub-agents: `npx talonctl set-capabilities --persona <name> --add "subagent.invoke"`
- For agents that should discuss uploaded images: `npx talonctl set-capabilities --persona <name> --add "subagent.invoke:*"` — plus `vision` in that persona's `subagents` list; see **Image handling** below

Repeat for each persona.

**Image handling** is a two-part Inspection setup plus one independent lookup
grant. None of it happens automatically on upgrade.

An **Inspection** needs exactly two things — the shipped `vision` manifest declares
`requiredCapabilities: []`, so no image capability is involved:

1. `vision` listed under the persona's `subagents` key in `talond.yaml`. There is
   no `talonctl` flag for persona sub-agent assignment, so edit the config.
2. `subagent.invoke` — the existing capability on the invoke tool:

```bash
npx talonctl set-capabilities --persona <name> --add "subagent.invoke:*"
```

`image.read:thread` is a **separate** permission, not part of an Inspection. It
exposes `image_lookup`, the model-free reader for the thread's Images and saved
Findings; it needs no vision assignment, never calls a model, and downloads
nothing, so it is safe to grant where you would not grant vision. Recommended (so
the persona can re-read an existing Finding instead of paying for a repeat
Inspection), but optional:

```bash
npx talonctl set-capabilities --persona <name> --add "image.read:thread"
```

Uploads are ingested and described regardless of all of the above. When confirming
setup, mention that:

- Pixels go only to the `vision` sub-agent; the main persona stays text-only.
- Only `anthropic` / `openai` / `google` / `ollama` may be in the vision chain;
  a text-only override is rejected at config load, not skipped.
- Normalized image files are deleted after `images.retentionHours` (default 24h),
  but Image records, GPS/EXIF and Findings persist until separately deleted and
  may appear in replies — including in admitted group chats.
- Inspections work from normal messages and scheduled tasks, not from background
  agents (those are refused before any model is called).
- The defaults in the `images:` block suit most setups. If the operator wants to
  tune it: `maxInputPixels` (default 100 MP, a decompression-bomb guard, max
  ~268 MP) and `maxNormalizedBytes` (default 3.75 MB; lower it if the vision
  provider has a smaller per-image limit — oversized images are re-encoded smaller
  automatically). Any `images` change needs a daemon restart; `talonctl reload`
  keeps the running values. See `config/talond.example.yaml`.
- On a sequential connector an image-bearing message delays other traffic on that
  connector — Telegram polling is the example, waiting up to ~120 seconds (a fixed
  60-second remote-fetch budget plus a separate 60-second normalization deadline).
  WhatsApp handles each chat in order but chats in parallel, so a text sent right
  after a photo waits for that photo while other chats keep flowing; a downloaded
  WhatsApp image still carries the same per-message 60-second fetch + 60-second
  normalization budgets. Email does no remote fetch — its bytes
  already arrived with the message — so only the shared 60-second normalization
  deadline applies there.

### Step 6: Scheduled tasks

Ask: **"Do you want to set up scheduled tasks?"**

Explain what they are: the agent runs a task prompt on a cron schedule and sends results to a channel. This makes the agent proactive instead of reactive.

Recommend starting with memory grooming (required for long-term health):

```bash
npx talonctl add-schedule \
  --persona assistant \
  --channel <primary-channel> \
  --cron "0 3 */2 * *" \
  --label "Memory grooming" \
  --prompt "Run the memory-grooming task prompt"
```

Explain: without memory grooming, the agent's stored memory fills up with stale and duplicate entries. Every 2-3 days at a quiet hour is the recommended cadence.

Then offer other common schedules:

```
Suggested schedules (optional):
  a) Morning briefing (weekdays 7am) — calendar, email, Jira, GitHub summary
  b) End-of-day summary (weekdays 6pm) — recap and tomorrow preview
  c) Weekly review (Friday 4pm) — stale tickets, forgotten follow-ups
  d) Week planning (Sunday 7pm) — upcoming week overview
  e) Custom schedule
  f) Done, skip the rest
```

For each selected, the user needs a task prompt file at `personas/<name>/prompts/<prompt-name>.md`. Either use the defaults that ship with the assistant persona or help the user write one.

Create each schedule with:

```bash
npx talonctl add-schedule \
  --persona <persona> \
  --channel <channel> \
  --cron "<expression>" \
  --label "<label>" \
  --prompt "Run the <prompt-name> task prompt"
```

Common cron expressions for reference:
- `0 7 * * 1-5` — weekdays at 7am
- `0 18 * * 1-5` — weekdays at 6pm
- `0 16 * * 5` — Friday at 4pm
- `0 19 * * 0` — Sunday at 7pm
- `0 3 */2 * *` — every 2 days at 3am

### Step 7: Database setup

Run: `npx talonctl migrate --config talond.yaml`

### Step 8: Validation

Run: `npx talonctl doctor --config talond.yaml`

For failures, provide specific remediation steps.

### Step 9: Environment check

Run: `npx talonctl env-check`

Show which env vars are missing. Tell the user to add them to `.env`.

### Step 10: Provider verification

Test every configured provider one more time:

```bash
npx talonctl test-provider --name Codex
npx talonctl test-provider --name gemini-cli
```

Only declare setup complete if at least one provider passes.

### Step 11: Systemd service (Linux only)

Ask: **"Want to install talond as a systemd service?"**

If yes, tell the user to run:
```bash
sudo ./deploy/install-service.sh --user $(whoami) --dir $(pwd)
```

### Step 12: Summary

Run these to build the summary:
```bash
npx talonctl list-providers
npx talonctl list-channels
npx talonctl list-personas
npx talonctl list-schedules
npx talonctl env-check
```

Print results and instructions to start the daemon:

```bash
node dist/index.js          # foreground with logs
# or if systemd service is installed:
sudo systemctl start talond
```

## MCP authentication

For static HTTP tokens or stdio credentials, use a `${ENV_VAR}` placeholder
and store the actual value in `.env`:

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

For OAuth, use an HTTPS resource URL, `--auth oauth2`, and then authorize the server:

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

If the authorization server has no Dynamic Client Registration endpoint,
provide `--client-id-env` and, if required, `--client-secret-env` when adding
the server, and pin the issuer with `--authorization-server-issuer https://<issuer>`.
`--token-endpoint-auth-method` accepts `client_secret_post` or
`client_secret_basic`. 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. Request only
needed scopes with `--scopes`; Talon does not request all provider-advertised
scopes automatically. Environment checks report variable names and status,
not values. Talon expands MCP header/stdIO env references once and rejects
resulting values that still look like provider environment-variable syntax.
Re-run `auth-mcp` after changing the MCP resource URL or configured
scopes; cached credentials are bound to both. For Docker Desktop, use `auth-mcp ... --docker`; see the Docker
setup skill for the host-local callback requirements.

## MCP request timeout and tool-output cap

When a persona's 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 (`skills/<skill>/mcp/<server>.json`):
add `"timeoutMs": <integer ≥ 1000>` and `"toolOutputCap": <integer ≥ 0>`,
and `talonctl add-mcp` accepts the same values as `--timeout-ms` /
`--tool-output-cap` flags:

```bash
npx 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 JSON file directly
(preserving name/URL/transport/headers/env/auth) — `add-mcp` rejects
duplicate names.

## Shared memory between agents

Talon supports shared memory between personas using the [Anthropic Memory MCP server](https://github.com/anthropics/memory). This is a knowledge graph stored in a single JSON file. When multiple personas use the same file, they share knowledge automatically.

How to set it up: for each persona that should share memory, add the memory MCP server to one of its skills:

```bash
npx talonctl add-mcp --skill <skill-name> --name memory \
  --transport stdio \
  --command npx \
  --args "-y @anthropic-ai/memory --memory-path data/shared-memory.json"
```

All personas point to the same `--memory-path`. Use `data/shared-memory.json` as the default location.

When to suggest this: when the user has multiple personas and asks about sharing context between them. Don't suggest it proactively during initial setup.

## Rules

1. **Never write actual secrets.** Only `${ENV_VAR}` placeholders in config and MCP `headers` / `env` fields.
2. **Use talonctl commands for all config mutations.** Exceptions: system prompt files, task prompt files, and `.env`. Narrow exception: the two numeric keys `timeoutMs` / `toolOutputCap` under `config` in an existing MCP server JSON (`skills/<skill>/mcp/<server>.json`) may be edited manually — no other manual MCP JSON or config edits.
3. **One question per message.** Do not batch questions.
4. **Show command output.** Let the user see what happened.
5. **Don't start the daemon.** Setup only. The user starts it themselves.
6. **Validate at the end.** Always run doctor, env-check, and test-provider before declaring setup complete.
7. **Test providers.** After any provider change, run `test-provider` to verify.

