Quickstart

Get a production AI agent running in under 15 minutes — on your laptop for development, or on an Android phone for always-on deployment.

Prerequisites

Python 3.11+
uv — fast Python package manager
At least one API key: ANTHROPIC_API_KEY or GOOGLE_API_KEY
At least one channel configured (Telegram, Discord, Slack, IRC, etc.)

Tip: You can run with just a cloud API key and no local model. The local model (llama.cpp) is optional — it saves money on simple messages but isn't required.

macOS / Linux

1 Clone and bootstrap

git clone https://github.com/jbxter/palmtop.git
cd palmtop
bash bootstrap_macos.sh

The bootstrap script installs uv and project dependencies. On macOS it uses Homebrew; on Linux it installs uv directly.

2 Configure

cp config.example.toml config.toml

Edit config.toml — set your [persona] section and API keys. See the Configuration guide for all options.

3 Set secrets

export ANTHROPIC_API_KEY="sk-ant-..."
export TELEGRAM_BOT_TOKEN="123456:ABC..."  # or your channel's token

4 Run

uv run python -m palmtop

Multi-channel: Run multiple channels simultaneously by setting channels = ["telegram", "slack", "irc"] in config.toml. All channels share the same agent. See the Channels reference for setup details.

Android (Termux)

Important: Install Termux from F-Droid, not the Play Store. The Play Store version is outdated and won't work.

1 Clone and bootstrap

pkg update && pkg install git
git clone https://github.com/jbxter/palmtop.git
cd palmtop
bash bootstrap_termux.sh

The bootstrap script installs Python, uv, llama.cpp with Vulkan GPU acceleration, and all dependencies. Takes about 10 minutes on a fresh Termux install. The local llama.cpp model runs in-process with direct GPU access — no extra daemons, minimal footprint.

2 Configure and run

cp config.example.toml config.toml
# Edit config.toml with your settings
export ANTHROPIC_API_KEY="sk-ant-..."
export TELEGRAM_BOT_TOKEN="123456:ABC..."
uv run python -m palmtop

Configure your persona

The [persona] section in config.toml drives everything — system prompts, web presence, email branding:

[persona]
name = "My Agent"
tagline = "AI-powered executive assistant"
owner_name = "Your Name"
domain = "yourdomain.com"
location = "San Francisco"

personality = """\
Sharp analytical thinking with genuine warmth. \
Casual but competent."""

capabilities = [
    "Scheduling and time management",
    "Business decisions and tradeoff analysis",
    "Research and recommendations",
]

services = [
    "Full-stack web development",
    "AI/ML integrations",
    "Technical consulting",
]

See the full Configuration reference for all options.

Verify it's working

Once the agent starts, you should see output like:

08:00:01 Cloud heavy: anthropic / claude-sonnet-4-5
08:00:01 Telegram bot started
08:00:01 Web channel started on 0.0.0.0:8000
08:00:01 Ready.

Send a message via your configured channel. If the agent replies, you're live.

Channel extras

Some channels need optional dependencies. Install only what you use:

uv sync --extra telegram   # python-telegram-bot
uv sync --extra discord    # discord.py
uv sync --extra slack      # slack-bolt + slack-sdk
uv sync --extra matrix     # matrix-nio
uv sync --extra xmpp       # slixmpp
uv sync --extra all        # everything

IRC, SMS, ScuttleBot, email, and WhatsApp have zero extra dependencies.

Expose with Cloudflare Tunnel

Cloudflare Tunnel gives your agent a public URL without port forwarding, static IPs, or exposing your network. Required for the web channel, WhatsApp webhooks, and any service that needs inbound HTTP.

Automated setup (recommended)

The setup script handles installation, authentication, DNS routing, config generation, and auto-start — on Termux, macOS, or Linux:

# Basic setup
bash scripts/setup-tunnel.sh --domain yourdomain.com

# With a separate webhook subdomain (for WhatsApp/Slack)
bash scripts/setup-tunnel.sh --domain yourdomain.com --webhook-port 8080

# Custom tunnel name and port
bash scripts/setup-tunnel.sh --domain yourdomain.com --name my-agent --port 8000

The script will:

Install cloudflared (pkg/brew/apt as appropriate)
Open a browser for Cloudflare authentication
Create a named tunnel and configure DNS routing
Generate ~/.cloudflared/config.yml
Set up auto-start (Termux:Boot / launchd / systemd)

Manual setup

If you prefer to do it step by step:

# Install cloudflared
# macOS: brew install cloudflared
# Termux: pkg install cloudflared
# Linux: sudo apt install cloudflared

# Authenticate (opens browser)
cloudflared tunnel login

# Create a named tunnel
cloudflared tunnel create palmtop

# Route your domain to the tunnel
cloudflared tunnel route dns palmtop yourdomain.com

# Run the tunnel
cloudflared tunnel run palmtop

Webhook routing

Channels like WhatsApp need a public webhook URL. If your WhatsApp webhook runs on port 8080, add a subdomain route:

# Route webhook subdomain
cloudflared tunnel route dns palmtop webhook.yourdomain.com

Then configure ~/.cloudflared/config.yml with multiple services:

tunnel: <tunnel-id>
credentials-file: ~/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: webhook.yourdomain.com
    service: http://localhost:8080
  - hostname: yourdomain.com
    service: http://localhost:8000
  - service: http_status:404

Set your WhatsApp webhook URL to https://webhook.yourdomain.com/webhook/whatsapp in the Meta Developer Console.

Troubleshooting

Common issues:

DNS not resolving: Allow 1-2 minutes for DNS propagation. Verify with dig yourdomain.com.
502 Bad Gateway: The agent isn't running or is on a different port. Check that [admin] port in config.toml matches the tunnel config.
Tunnel disconnects on phone: Ensure Termux has battery optimization disabled (Android Settings → Apps → Termux → Battery → Unrestricted).
Auth expired: Re-run cloudflared tunnel login to refresh credentials.

Git-push deploy

Once the agent is running on your phone, set it up as a git remote for zero-downtime deploys from your laptop:

# On the phone (Termux)
bash scripts/setup-git-server.sh

# On your laptop
git remote add phone ssh://phone-ip:8022/path/to/palmtop.git
git push phone main
# Auto-pulls, restarts agent, reconnects tunnel

The post-receive hook handles everything. See scripts/git-post-receive.sh for details.

Auto-start on boot

With Termux:Boot, the agent starts automatically when your phone reboots:

bash scripts/setup-boot.sh

This creates a boot script that starts the agent and Cloudflare Tunnel on device startup.