Installation

Talon runs as a native Node.js daemon. The current first-run checks also expect Docker to be installed and the daemon to be running.

Recommended: Starter Stack (Docker)

The fastest way to a running agent is the Talon + Postgram Starter Stack — a self-contained Docker Compose bundle with persistent memory pre-wired. No build step, no Node install.

# 1. Download and extract
curl -fsSL https://github.com/ivo-toby/talon/releases/latest/download/talon-postgram-stack.tar.gz | tar xz
cd talon-postgram-stack

# 2. Configure secrets
cp .env.example .env
# Edit .env: POSTGRES_PASSWORD, OPENAI_API_KEY, ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN

cp config/talond.example.yaml config/talond.yaml
# Edit config/talond.yaml: set allowedChatIds for Telegram

# 3. Start everything
./bootstrap.sh

The bootstrap.sh script handles ordering, mints a Postgram API key, and wires Talon to the knowledge store. See the Starter Stack guide for full details.

---

Alternative: Build from source

If you prefer to run Talon natively or want to develop on it, follow the steps below.

Prerequisites

• Node.js 24+ — Talon uses process.loadEnvFile, which requires Node 24
• Docker — talonctl setup and talonctl doctor check Docker availability
• Claude Code — the default agent provider. Install and authenticate it: npm install -g @anthropic-ai/claude-code
• SQLite — ships with better-sqlite3, no separate install needed
• Git — to clone the repo

Check your Node version:

node --version  # must be v24.0.0 or higher

Clone and build

git clone https://github.com/ivo-toby/talon.git
cd talon
npm install
npm run build

The build step compiles TypeScript to dist/ and copies SQL migrations. Both dist/index.js (daemon) and dist/cli/index.js (talonctl) are produced.

Verify the build

node dist/cli/index.js --version

You should see the talonctl version string. If you get a module error, confirm Node 24 is active.

Guided setup with Claude Code (recommended)

The fastest way to go from a fresh clone to a running daemon is the talon.setup skill — an interactive wizard built into Claude Code that walks you through the entire setup conversationally.

Prerequisites: Claude Code installed and authenticated (npm install -g @anthropic-ai/claude-code, then claude auth login).

Open the Talon repository in Claude Code and run:

/talon.setup

The skill detects what is already configured and picks up from where you are. On a fresh clone it walks through:

1. Prerequisites — Node version, dependencies, build, AI provider binaries
2. Bootstrap — data directories, talond.yaml, database migrations
3. Provider configuration — Claude Code, Gemini CLI, or both; default provider per context
4. Channel configuration — Telegram, Slack, Discord, WhatsApp, email, or terminal
5. Persona configuration — name, purpose, tone, system prompt authoring, channel bindings
6. Capability configuration — review and adjust per-persona capability grants
7. Scheduled tasks — memory grooming, morning briefings, weekly reviews, custom crons
8. Validation — talonctl doctor, talonctl env-check, talonctl test-provider
9. Systemd service — optional Linux service installation

The skill asks one question at a time, runs talonctl commands on your behalf, and shows you the output at every step. It never writes secrets — only ${ENV_VAR} placeholders.

If setup is already partially complete, /talon.setup presents a menu to add channels, personas, skills, schedules, or providers without repeating what is already done.

Initial setup (manual)

If you prefer to configure everything by hand, run the bootstrap command first. It checks your environment, creates the data/ directory structure, generates a starter talond.yaml, runs migrations, and validates the result:

npx talonctl setup

The setup command runs these steps:

1. OS detection
2. Node version check
3. Docker availability check
4. Data directory creation
5. Config generation
6. Database migrations
7. Config validation

After setup, run talonctl doctor to validate everything:

npx talonctl doctor --config talond.yaml

talonctl doctor checks Node.js, Docker, config validity, database access, and data directories. Fix any failures before starting the daemon.

Apply database migrations

npx talonctl migrate --config talond.yaml

This creates the SQLite database at data/talond.sqlite and applies all schema migrations.

Start the daemon

node dist/index.js --config talond.yaml

Or via npm:

npm run talond

The daemon logs to stdout in structured JSON. Set logLevel: info in your config for normal operation; use debug when debugging connector issues.

Systemd service (Linux servers)

For production, run Talon as a systemd service:

sudo ./deploy/install-service.sh

The install script detects your username, home directory, and Node path, then generates /etc/systemd/system/talond.service. It reads environment variables from .env in the project root.

# Start and enable on boot
sudo systemctl enable --now talond

# Follow logs
journalctl -u talond -f

# Reload config without restarting
npx talonctl reload

The service unit includes security hardening: NoNewPrivileges, PrivateTmp, ProtectKernelTunables, and SystemCallFilter=@system-service.

Custom install options

sudo ./deploy/install-service.sh --user talon --dir /home/talon/talon

Wake-only mode (timer)

For low-traffic deployments, use the systemd timer to wake the daemon periodically instead of running it continuously:

sudo cp deploy/talond-wake.service /etc/systemd/system/
sudo cp deploy/talond.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now talond.timer

Default wake interval is 5 minutes. Adjust OnUnitActiveSec in deploy/talond.timer to change it.

Secrets and environment variables

Never hardcode credentials in talond.yaml. Use ${ENV_VAR} placeholders and load them from .env:

.env

TELEGRAM_BOT_TOKEN=your-token-here
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

Talon loads .env automatically at startup via process.loadEnvFile. Check for missing variables any time with:

npx talonctl env-check --config talond.yaml

Next step

Quick start →