Self-Hosting

Talon can be deployed in multiple ways depending on your needs. From running the desktop app as a server to headless deployments on your own infrastructure, you have full control over where and how Talon runs.

Desktop Mode (Simplest)

The easiest way to get started is to run the desktop application—it is the server.

Simply download and run the Talon desktop app on any machine, and it automatically starts an API server listening on your local network. Other machines and mobile devices can then connect to it remotely through our relay server.

Pros:

• No configuration needed
• Works out of the box
• Same experience as the desktop app

Cons:

• Requires the desktop app to be running
• Limited to desktop-class machines

Headless Server

Deploy the Rust backend without the Tauri GUI for server-only setups.

Build the Backend

Navigate to the src-tauri directory and build the release binary:

cd src-tauri
cargo build --release

The compiled binary will be located at target/release/talon (or talon.exe on Windows).

Configure

Create a talon.json file in your app data directory with your provider credentials and channels:

{
  "provider": "anthropic",
  "api_key": "sk-ant-...",
  "model": "claude-opus-4-6",
  "temperature": 0.7,
  "channels": [
    {
      "name": "desktop",
      "type": "tcp",
      "port": 5000,
      "allow_from": ["192.168.1.*"]
    },
    {
      "name": "relay",
      "type": "websocket",
      "url": "wss://talon.aieduapp.com/ws",
      "auth_token": "your-auth-token"
    }
  ]
}

Run the Server

Execute the binary:

./target/release/talon

Channels will start automatically and be ready to accept connections. Check the logs to confirm everything is running.

Caution

Store your API keys securely. Never commit talon.json with real credentials to version control.

Docker Deployment

A Dockerfile is provided for containerized deployments.

docker build -t talon:latest .
docker run -p 5000:5000 -v /path/to/talon.json:/app/talon.json talon:latest

The container exposes port 5000 by default. Mount your talon.json as a volume to provide configuration and persistent data storage.

Tip

Use environment variables for sensitive data instead of embedding them in talon.json inside the container:

docker run -p 5000:5000 \
  -e TALON_API_KEY="sk-ant-..." \
  -e TALON_AUTH_TOKEN="your-token" \
  talon:latest

Relay Server (Cloudflare Workers)

Deploy your own worker-relay to Cloudflare Workers for mobile and web connectivity without exposing your home network.

Deploy the Worker

cd deploy/worker-relay
wrangler deploy

Configure Authentication

Set a strong auth token as a secret:

wrangler secret put AUTH_TOKEN
# Enter your token (e.g., a random 32-character string)

Clients will need to provide this token when connecting to your relay server.

Caution

Security First: Use a strong, randomly generated AUTH_TOKEN. Change it regularly and treat it like a password.

Connect Your Talon Instance

Update your machine registration to use your relay server:

curl -X POST https://your-relay.workers.dev/register \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{"machine_id": "my-talon"}'

Now mobile and web clients can connect through your relay without needing direct network access.

Web Frontend (Cloudflare Pages)

Deploy the Talon web interface to Cloudflare Pages for easy browser access.

cd deploy/pages-web
./deploy.sh

The script will build and deploy the web app. Your frontend will be available at your Pages URL (e.g., https://talon-myname.pages.dev).

Configure the frontend to point to your Talon instance:

# Set environment variables in your Pages deployment
VITE_TALON_API_URL=wss://your-relay.workers.dev/ws
VITE_AUTH_TOKEN=your-auth-token

Tip

Deploy both the relay server and web frontend to keep everything on your own infrastructure.

Data Storage

All Talon data is stored locally in the app data directory:

• SQLite database (talon.db): Stores conversation history, messages, and memory
• Configuration (talon.json): Provider settings, API keys, channels, and custom tools
• Logs (talon.log): Operation logs for debugging

App Data Directories:

• Linux: ~/.config/talon/
• macOS: ~/Library/Application Support/talon/
• Windows: %APPDATA%\talon\

Caution

Backup your data: Regularly backup your app data directory to prevent loss of conversations and configuration.

Security Best Practices

1. Strong Authentication

Use a strong, random AUTH_TOKEN (at least 32 characters):

openssl rand -base64 32

Caution

Never use weak or predictable tokens. Treat your AUTH_TOKEN like a password.

2. Network Filtering

In your talon.json, use allow_from to restrict which networks can connect:

{
  "channels": [
    {
      "name": "desktop",
      "type": "tcp",
      "port": 5000,
      "allow_from": ["192.168.1.*", "10.0.0.*"]
    }
  ]
}

Only allow IP ranges you trust.

3. Permission Mode

Set appropriate permission levels for tool usage:

{
  "permission_mode": "ask"
}

Options:

• "ask" — Prompt user before running tools (safest)
• "allow" — Allow all tools automatically
• "deny" — Block all tools

Tip

Start with "ask" mode and transition to "allow" only for trusted integrations.

4. API Key Management

• Store API keys as environment variables, not in version control
• Rotate keys regularly
• Use read-only API keys where available
• Monitor API usage for unexpected activity

5. HTTPS/WSS Only

Always use encrypted connections:

• Use wss:// (WebSocket Secure) instead of ws://
• Use https:// instead of http:// for HTTP endpoints
• Enable TLS on self-hosted servers

Caution

Never transmit auth tokens or API keys over unencrypted connections.

Updating Your Deployment

Desktop App

Simply download the latest version and install it.

Headless Server

Rebuild and restart:

cd src-tauri
cargo build --release
# Stop the old process
./target/release/talon

Docker

Pull the latest image and redeploy:

docker pull talon:latest
docker-compose down
docker-compose up -d

Relay Server

Redeploy from the repository:

cd deploy/worker-relay
git pull
wrangler deploy

Web Frontend

Redeploy the pages:

cd deploy/pages-web
./deploy.sh