Gateway security

Moltbot’s Gateway security model is designed to expose services to LAN and tailnet while keeping credential and auth traffic confined to the local loopback network by default.

• Default bind: loopback (127.0.0.1) — the Gateway only accepts connections from localhost.
• Remote access: expose via Tailscale Serve/Funnel or SSH tunnel.
• Auth: always required (token or password) for non-loopback binds.
• Tailscale integration: optional identity header auth (gateway.auth.allowTailscale).

See /gateway/tailscale for Tailscale-specific guidance.

Auth modes

Token auth (default)

The wizard generates a Gateway token by default.

Config:

{
  gateway: {
    auth: { mode: "token", token: "your-secret-token" }
  }
}

Or set CLAWDBOT_GATEWAY_TOKEN.

Password auth

{
  gateway: {
    auth: { mode: "password", password: "your-password" }
  }
}

Or set CLAWDBOT_GATEWAY_PASSWORD.

Password auth is required for tailscale.mode: "funnel" (Funnel doesn’t support WS headers, so token auth isn’t viable).

Tailscale identity auth (no credentials)

When using Tailscale Serve, you can skip explicit credentials and rely on Tailscale identity headers:

{
  gateway: {
    auth: {
      mode: "password",
      allowTailscale: true  // allow Tailscale identity to satisfy auth
    }
  }
}

• With allowTailscale: true, clients on your tailnet are auto-authenticated via the Tailscale-User-Name header.
• Set allowTailscale: false to require explicit token/password even on Tailscale.
• allowTailscale has no effect when not using Tailscale Serve.

Bind modes

Non-loopback binds require a shared token/password (gateway.auth or env).

Tailscale integration

Serve (recommended)

Keep the Gateway on loopback and let Tailscale Serve proxy it:

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" }
  }
}

Then start the gateway:

moltbot gateway

Open: https://<magicdns>/ (or your configured gateway.controlUi.basePath).

With Serve, you can use gateway.auth.allowTailscale: true to skip explicit credentials.

Funnel (public internet)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" } // or MOLTBOT_GATEWAY_PASSWORD
  }
}

Funnel exposes the Gateway to the public internet via Tailscale. Password auth is required (Funnel doesn’t support WS headers for token auth).

Tailnet bind

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "your-token" }
  }
}

Then start the gateway (token required for non-loopback binds):

moltbot gateway

Open: http://<tailscale-ip>:18789/ (or your configured gateway.controlUi.basePath).

Security checklist

• Gateway is bound to loopback by default (check gateway.bind).
• Non-loopback binds have a shared token/password set.
• gateway.auth.allowTailscale is set to false if you want to require explicit credentials on Tailscale.
• For Funnel, password auth is configured (gateway.auth.mode: "password").
• Secrets are stored in ~/.moltbot/ with restrictive permissions (chmod 700).
• If using SSH tunnel, the tunnel is secured with keys, not password.

Webhooks security

When hooks.enabled=true, the Gateway exposes a webhook endpoint on the same HTTP server.

See Gateway configuration → hooks for webhook auth + payloads.

Security model (formal verification)

Moltbot’s formal security models (TLA+/TLC today; more as needed) live at /security/formal-verification.

These models prove:

• Confidentiality: secrets never leave the local loopback network.
• Integrity: only authenticated clients can mutate Gateway state.
• Availability: the Gateway remains responsive under DoS conditions.

Common security foot-guns

• Exposing Gateway to public internet without auth: use tailscale.mode: "funnel" only with password auth.
• Using weak passwords: generate a strong token/password via the wizard or openssl rand -hex 32.
• Storing secrets in plaintext: the CLI stores secrets in ~/.moltbot/ with restrictive permissions; avoid copying them to world-readable locations.
• Sharing credentials over insecure channels: use Tailscale Serve or SSH tunnel instead of sending tokens/passwords over plain HTTP.
• Running as root: the Gateway runs as your user; avoid sudo unless necessary (e.g., system service install).

Auditing

Run moltbot security audit to check for common security foot-guns:

moltbot security audit
moltbot security audit --deep  # includes live Gateway probe
moltbot security audit --fix   # apply safe fixes

See /cli/security for details.