Deploy Moltbot To Fly

Deploy Moltbot to Fly.io with persistent storage, secure token authentication, environment secrets, and approved device pairing for web UI access.

Security Scan

The runtime instructions coherently describe deploying Moltbot to Fly.io, but the skill metadata omits required secrets (Anthropic/OpenAI API keys and a gateway token) and the instructions recommend executing remote install scripts and server-side commands that modify device pairing files — these mismatches and privileged operations merit caution.

Purpose & Capability

The SKILL.md describes exactly how to deploy Moltbot (Clawdbot) to Fly.io — creating app, volume, secrets, config, and approving device pairing — which matches the apparent purpose. However the published metadata lists no required environment variables or credentials even though the instructions explicitly require CLAWDBOT_GATEWAY_TOKEN, ANTHROPIC_API_KEY (and optionally OPENAI_API_KEY). The missing metadata declarations are an inconsistency.

Instruction Scope

The instructions are specific and scoped to deployment: git clone, set Fly secrets, create a config file under /data, deploy, and run a Node one-liner over fly ssh to approve device pairing (reading/writing /data/*.json). These actions require full control of the Fly machine and the app's persistent volume (expected for this task). The instruction to embed the token in a public URL (https://your-app.fly.dev/?token=...) is a potential security concern but is part of the product's pairing flow.

Install Mechanism

There is no install spec in the skill (instruction-only), which is low risk. The SKILL.md recommends installing flyctl via Homebrew or via the official fly install script (curl -L https://fly.io/install.sh | sh). The latter executes a remote script; it's common for CLI installs but carries the usual risk of running remote code — verify the URL and checksum before running if you are cautious.

Credentials

The instructions require several secrets (CLAWDBOT_GATEWAY_TOKEN, ANTHROPIC_API_KEY, optionally OPENAI_API_KEY) and persistent storage, but the skill registry metadata claims no required env vars or primary credential. That mismatch is problematic: the skill will not function without those secrets, and they are not declared upfront. Requesting LLM provider keys and a gateway token is reasonable for a bot that proxies models and pairs devices, but the omission from metadata reduces transparency and prevents automated vetting of credential scope.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide agent settings. The operations described write to the app's /data volume and set Fly app secrets — these are scoped to the deployed app and are expected for this deployment. Approving device pairing grants access to the bot's device registry, which is necessary for the product flow but is a privileged action the operator should understand.

What to consider before installing

This skill's instructions are plausible for deploying a bot to Fly.io, but pay attention to these issues before installing or following them: - Metadata mismatch: The registry says no env vars are required, but the guide requires CLAWDBOT_GATEWAY_TOKEN, ANTHROPIC_API_KEY (and optionally OPENAI_API_KEY). Treat that as a transparency gap — expect to supply those secrets. - Repository trust: The steps clone and run code from github.com/clawdbot/clawdbot. Inspect the repository (Dockerfile, entrypoint, and any scripts) before deploying so you know what code will run in your account. - Remote install script: The guide suggests curl | sh to install flyctl. Prefer Homebrew or review the install script before executing remote code. - Token exposure: The pairing flow uses a token in a URL query parameter (https://.../?token=...). That can leak via browser history, logs, or referers. Keep the token secret and rotate it if accidentally exposed. - Device pairing one-liner: The provided Node command approves pending devices by editing /data JSON files. That operation effectively authorizes devices to access your Moltbot instance — only run it when you understand which pending request will be approved. - Least privilege: Only store the required LLM provider keys and gateway token as Fly secrets; avoid placing credentials in config files checked into git. Consider using short-lived or scoped API keys where possible. If you want to proceed: verify the GitHub repo contents, confirm the Fly app and volume names, create and securely store the gateway token, and add only the secrets needed. If anything in the repo looks unexpected or the metadata remains inconsistent, treat the skill as untrusted until clarified.

Deploy Moltbot to Fly.io

Deploy Moltbot (Clawdbot) to Fly.io with proper configuration, persistent storage, and device pairing.

Overview

Deploying Moltbot to Fly.io requires:

1. Setting up the Fly app with a persistent volume
2. Configuring environment secrets (API keys, gateway token)
3. Creating a proper config file with token authentication
4. Approving device pairing for web UI access

Prerequisites

Before starting:

• Fly.io CLI installed (brew install flyctl or curl -L https://fly.io/install.sh | sh)
• Fly.io account and logged in (fly auth login)
• Anthropic API key (and optionally OpenAI API key)
• Git installed

Phase 1: Clone and Setup

1.1 Clone the Moltbot Repository

git clone https://github.com/clawdbot/clawdbot.git moltbot-deploy
cd moltbot-deploy

1.2 Generate Gateway Token

Generate a secure token for authentication:

openssl rand -hex 32

IMPORTANT: Save this token - you'll need it for:

• Fly secrets
• Config file
• Web UI access URL

Phase 2: Fly.io Configuration

2.1 Create fly.toml

Create fly.toml with the correct configuration:

app = 'your-app-name'
primary_region = 'iad'

[build]
  dockerfile = 'Dockerfile'

[env]
  NODE_ENV = 'production'
  CLAWDBOT_PREFER_PNPM = '1'
  CLAWDBOT_STATE_DIR = '/data'
  NODE_OPTIONS = '--max-old-space-size=1536'

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[[vm]]
  size = 'shared-cpu-2x'
  memory = '2048mb'

[mounts]
  source = 'moltbot_data'
  destination = '/data'

CRITICAL Settings:

• CLAWDBOT_STATE_DIR = '/data' - Required for proper config persistence
• --bind lan - Allows Fly's proxy to reach the gateway
• http_service - Newer Fly format (not [[services]])
• memory = '2048mb' - 512MB is too small; 2GB recommended

2.2 Create App and Volume

fly apps create your-app-name
fly volumes create moltbot_data --region iad --size 1 -a your-app-name -y

Choose a region close to you:

• iad - Virginia (US East)
• lhr - London
• sjc - San Jose (US West)

2.3 Set Fly Secrets

# Set your generated token
fly secrets set CLAWDBOT_GATEWAY_TOKEN="YOUR-TOKEN-HERE" -a your-app-name

# Set API keys
fly secrets set ANTHROPIC_API_KEY="sk-ant-xxxxx" -a your-app-name
fly secrets set OPENAI_API_KEY="sk-xxxxx" -a your-app-name  # Optional

Note: Secrets are deployed on first fly deploy, not immediately.

Phase 3: Deploy

Deploy the application:

fly deploy -a your-app-name

First deployment takes ~3-5 minutes (building Docker image).

Wait for gateway to start:

fly logs -a your-app-name --no-tail | grep "listening on"

You should see:

[gateway] listening on ws://0.0.0.0:3000 (PID xxx)

Phase 4: Create Config File

CRITICAL: The config file must include the same token as the env var for authentication to work.

4.1 SSH into the machine

fly ssh console -a your-app-name

4.2 Create the config file

cat > /data/moltbot.json << 'EOF'
{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "YOUR-TOKEN-HERE"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5"
      }
    }
  },
  "auth": {
    "profiles": {
      "anthropic:default": { "mode": "token", "provider": "anthropic" }
    }
  }
}
EOF

Replace YOUR-TOKEN-HERE with your actual token!

4.3 Exit and restart

exit
fly machine restart <machine-id> -a your-app-name

Get machine ID with: fly machines list -a your-app-name

Phase 5: Access and Device Pairing

5.1 Wait for DNS propagation

DNS may take 2-5 minutes to propagate. Check status:

nslookup your-app-name.fly.dev 8.8.8.8

If DNS isn't resolving on your machine, flush your DNS cache:

macOS:

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Linux:

sudo systemd-resolve --flush-caches

5.2 Access Web UI

Open in browser with the tokenized URL:

https://your-app-name.fly.dev/?token=YOUR-TOKEN-HERE

You'll see "disconnected (1008): pairing required" - this is normal!

5.3 Approve Device Pairing

While the browser is open and attempting to connect, approve the pairing:

fly ssh console -a your-app-name

Then run:

node -e "
const fs = require('fs');
const pending = JSON.parse(fs.readFileSync('/data/devices/pending.json'));
const paired = JSON.parse(fs.readFileSync('/data/devices/paired.json') || '{}');
const requestId = Object.keys(pending)[0];
if (requestId) {
  const device = pending[requestId];
  paired[device.deviceId] = {
    deviceId: device.deviceId,
    publicKey: device.publicKey,
    platform: device.platform,
    clientId: device.clientId,
    role: device.role,
    roles: device.roles,
    scopes: device.scopes,
    approvedAt: Date.now(),
    approvedBy: 'cli'
  };
  delete pending[requestId];
  fs.writeFileSync('/data/devices/pending.json', JSON.stringify(pending, null, 2));
  fs.writeFileSync('/data/devices/paired.json', JSON.stringify(paired, null, 2));
  console.log('Approved device:', device.deviceId);
} else {
  console.log('No pending devices');
}
"

5.4 Refresh Browser

After approval, refresh your browser. You should now be connected! 🎉

Troubleshooting

Gateway Token Mismatch

Symptoms: unauthorized: gateway token mismatch

Fix: Token in config file must match the env var:

# Check env var token
fly ssh console -a your-app-name -C "printenv CLAWDBOT_GATEWAY_TOKEN"

# Update config file to match
fly ssh console -a your-app-name
# Edit /data/moltbot.json and update gateway.auth.token

App Not Listening / Connection Refused

Symptoms: instance refused connection or not listening on expected address

Fix: Ensure --bind lan in fly.toml and gateway is fully started:

fly logs -a your-app-name --no-tail | tail -50

Wait 30-60 seconds after deploy for gateway to initialize.

DNS Not Resolving

Symptoms: Could not resolve host

Fix:

1. Wait 2-5 minutes for DNS propagation
2. Use Google DNS: 8.8.8.8 or 1.1.1.1
3. Flush local DNS cache (see Phase 5.1)

Config Validation Errors

Symptoms: Gateway exits with "Invalid input" or validation errors

Fix: Check config syntax:

fly ssh console -a your-app-name -C "cat /data/moltbot.json"

Common issues:

• Invalid auth.mode: Only "token" is valid (not "off")
• Missing commas in JSON
• Mismatched quotes

State Not Persisting

Symptoms: Config/devices reset after restart

Fix: Ensure CLAWDBOT_STATE_DIR=/data is set in fly.toml [env] section.

Stuck Deployment

Symptoms: Machine keeps restarting or won't stabilize

Nuclear option (fastest):

fly apps destroy your-app-name -y
# Then re-run Phase 2 onwards with fresh setup

Advanced: Trusted Proxies (Optional)

If you see proxy warnings in logs, add trusted proxies:

fly ssh console -a your-app-name

node -e "
const fs = require('fs');
const config = JSON.parse(fs.readFileSync('/data/moltbot.json'));
config.gateway.trustedProxies = [
  '172.16.0.0/12',
  '10.0.0.0/8'
];
fs.writeFileSync('/data/moltbot.json', JSON.stringify(config, null, 2));
console.log('Trusted proxies configured');
"

Restart machine after changes.

Quick Reference

# Check status
fly status -a APP

# View logs
fly logs -a APP --no-tail | tail -50

# SSH into machine
fly ssh console -a APP

# Restart machine
fly machines list -a APP  # Get machine ID
fly machine restart <machine-id> -a APP

# Check secrets
fly secrets list -a APP

# Get gateway token
fly ssh console -a APP -C "printenv CLAWDBOT_GATEWAY_TOKEN"

# Redeploy
fly deploy -a APP

Updates

To update Moltbot:

cd moltbot-deploy
git pull
fly deploy -a your-app-name

Config and paired devices persist on the volume across updates.

Key Lessons

1. CLAWDBOT_STATE_DIR=/data is critical - without it, config location is wrong
2. Token must be in BOTH env var AND config file
3. Use http_service not [[services]] (newer Fly format)
4. Device pairing is required even with token auth
5. DNS takes time - wait 2-5 minutes, flush cache if needed
6. Fresh deploy is often faster than debugging corrupted state
7. 2GB RAM minimum - 512MB will OOM, 1GB may work but 2GB is recommended

Resources

• Fly.io Documentation
• Moltbot Official Docs
• Clawdbot GitHub