Fly.io

Goal: OpenClaw Gateway running on a Fly.io machine with persistent storage, automatic HTTPS, and Discord/channel access.

What you need

• flyctl CLI installed
• Fly.io account (free tier works)
• Model auth: API key for your chosen model provider
• Channel credentials: Discord bot token, Telegram token, etc.

Beginner quick path

1. Clone repo, customize fly.toml
2. Create app + volume, set secrets
3. Deploy with fly deploy
4. SSH in to create config, or use the Control UI

git clone https://github.com/openclaw/openclaw.gitcd openclaw # pick your own namefly apps create my-openclaw # 1GB is usually enoughfly volumes create openclaw_data --size 1 --region iad

app = "my-openclaw"  # your app nameprimary_region = "iad" [build]  dockerfile = "Dockerfile" [env]  NODE_ENV = "production"  OPENCLAW_PREFER_PNPM = "1"  OPENCLAW_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 = "openclaw_data"  destination = "/data"

# required: gateway auth token for non-loopback bindingfly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32) # model provider API keysfly secrets set ANTHROPIC_API_KEY=example-anthropic-key-not-real # optional: other providersfly secrets set OPENAI_API_KEY=example-openai-key-not-realfly secrets set GOOGLE_API_KEY=... # channel tokensfly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

fly deploy

fly statusfly logs

fly ssh console

mkdir -p /datacat > /data/openclaw.json << 'EOF'{  "agents": {    "defaults": {      "model": {        "primary": "anthropic/claude-opus-4-6",        "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"]      },      "maxConcurrent": 4    },    "list": [      {        "id": "main",        "default": true      }    ]  },  "auth": {    "profiles": {      "anthropic:default": { "mode": "token", "provider": "anthropic" },      "openai:default": { "mode": "token", "provider": "openai" }    }  },  "bindings": [    {      "agentId": "main",      "match": { "channel": "discord" }    }  ],  "channels": {    "discord": {      "enabled": true,      "groupPolicy": "allowlist",      "guilds": {        "YOUR_GUILD_ID": {          "channels": { "general": { "allow": true } },          "requireMention": false        }      }    }  },  "gateway": {    "mode": "local",    "bind": "auto",    "controlUi": {      "allowedOrigins": [        "https://my-openclaw.fly.dev",        "http://localhost:3000",        "http://127.0.0.1:3000"      ]    }  },  "meta": {}}EOF

exitfly machine restart <machine-id>

fly open

fly logs              # live logsfly logs --no-tail    # recent logs

fly ssh console

Troubleshooting

"App is not listening on expected address"

The gateway is binding to 127.0.0.1 instead of 0.0.0.0.

Fix: add --bind lan to your process command in fly.toml.

Health checks failing / connection refused

Fly cannot reach the gateway on the configured port.

Fix: ensure internal_port matches the gateway port (--port 3000 or OPENCLAW_GATEWAY_PORT=3000).

OOM / memory issues

Container keeps restarting or getting killed. Signs: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration, or silent restarts.

Fix: increase memory in fly.toml:

[[vm]]  memory = "2048mb"

Or update an existing machine:

fly machine update <machine-id> --vm-memory 2048 -y

512MB is too small. 1GB may work but can OOM under load or with verbose logging. 2GB is recommended.

Gateway lock issues

Gateway refuses to start with "already running" errors after a container restart.

The runtime lock files live at <tmpdir>/openclaw-<uid>/gateway.<hash>.lock and gateway.state.<hash>.lock (Linux: /tmp/openclaw-<uid>/gateway.*.lock), not on the persistent /data volume, so a full container restart normally clears them along with the rest of the container filesystem. If a lock survives (for example a fly machine restart that preserves the container filesystem) and blocks startup, remove it manually:

fly ssh console --command "rm -f /tmp/openclaw-*/gateway.*.lock"fly machine restart <machine-id>

Config not being read

--allow-unconfigured only bypasses the startup guard. It does not create or repair /data/openclaw.json, so make sure your real config exists and includes "gateway": { "mode": "local" } for a normal local gateway start.

Verify the config exists:

fly ssh console --command "cat /data/openclaw.json"

Writing config via SSH

fly ssh console -C does not support shell redirection. To write a config file:

# echo + tee (pipe from local to remote)echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json" # or sftpfly sftp shell> put /local/path/config.json /data/openclaw.json

fly sftp may fail if the file already exists; delete first:

fly ssh console --command "rm /data/openclaw.json"

State not persisting

If you lose auth profiles, channel/provider state, or sessions after a restart, the state dir is writing to the container filesystem instead of the volume.

Fix: ensure OPENCLAW_STATE_DIR=/data is set in fly.toml and redeploy.

Updating

git pullfly deployfly statusfly logs

git pull + fly deploy is the supervised path here: it rebuilds the image from the Dockerfile, so the CLI/gateway version, the base OS image, and any Dockerfile changes all update together. openclaw update inside the running container is not the same operation, since the image ships as a Docker-built dist/ tree with no .git checkout and no npm-managed global install for it to detect; see Updating for that flow on VM-style installs.

Updating the machine command

To change the startup command without a full redeploy:

fly machines listfly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y # or with a memory increasefly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y

A later fly deploy resets the machine command back to whatever is in fly.toml; re-apply manual changes after redeploying.

Private deployment (hardened)

By default, Fly allocates public IPs, so your gateway is reachable at https://your-app.fly.dev and discoverable by internet scanners (Shodan, Censys, etc.).

Use deploy/fly.private.toml for a hardened deployment with no public IP: it omits [http_service], so no public ingress is allocated.

When to use private deployment

• Only outbound calls/messages (no inbound webhooks)
• ngrok or Tailscale tunnels handle any webhook callbacks
• Gateway access is via SSH, proxy, or WireGuard instead of a browser
• The deployment should be hidden from internet scanners

Setup

fly deploy -c deploy/fly.private.toml

Or convert an existing deployment:

# list current IPsfly ips list -a my-openclaw # release public IPsfly ips release <public-ipv4> -a my-openclawfly ips release <public-ipv6> -a my-openclaw # switch to the private config so future deploys do not re-allocate public IPsfly deploy -c deploy/fly.private.toml # allocate private-only IPv6fly ips allocate-v6 --private -a my-openclaw

After this, fly ips list should show only a private type IP:

VERSION  IP                   TYPE             REGIONv6       fdaa:x:x:x:x::x      private          global

Accessing a private deployment

Option 1: local proxy (simplest)

fly proxy 3000:3000 -a my-openclaw# open http://localhost:3000 in a browser

Option 2: WireGuard VPN

fly wireguard create# import to a WireGuard client, then access via internal IPv6# example: http://[fdaa:x:x:x:x::x]:3000

Option 3: SSH only

fly ssh console -a my-openclaw

Webhooks with private deployment

For webhook callbacks (Twilio, Telnyx, etc.) without public exposure:

1. ngrok tunnel: run ngrok inside the container, or as a sidecar
2. Tailscale Funnel: expose specific paths via Tailscale
3. Outbound-only: some providers (Twilio) work for outbound calls without webhooks

Example voice-call config with ngrok, under plugins.entries.voice-call.config:

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          provider: "twilio",          tunnel: { provider: "ngrok" },          webhookSecurity: {            allowedHosts: ["example.ngrok.app"],          },        },      },    },  },}

The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself. Set webhookSecurity.allowedHosts to the tunnel hostname so forwarded host headers are accepted.

Security tradeoffs

Notes

• Fly.io uses x86 architecture; the Dockerfile is compatible with both x86 and ARM.
• For WhatsApp/Telegram onboarding, use fly ssh console.
• Persistent data lives on the volume at /data.
• Signal requires signal-cli (a Java-based CLI) on the image; use a custom image and keep memory at 2GB+.

Cost

With the recommended config (shared-cpu-2x, 2GB RAM), expect roughly $10-15/month depending on usage; the free tier covers some baseline allowance. See Fly.io pricing for current rates.

Next steps

• Set up messaging channels: Channels
• Configure the Gateway: Gateway configuration
• Keep OpenClaw up to date: Updating

Related

• Install overview
• Hetzner
• Docker
• VPS hosting