OtterKit Tunnel

OtterKit Tunnel

Expose a local port to the internet instantly via a secure tunnel. Paid with prepaid OtterKit credits (1 credit = $0.01), metered by time: 1 credit per connected hour (first hour charged at provision), never more than 300 credits ($3) per endpoint per rolling 30 days - webhooks and tunnels alike. Billing pauses while disconnected, and tunnels auto-stop after a TTL (default 24h) so a forgotten tunnel stops billing. The user logs in once with otterkit login; after that the CLI (and any agent on the same machine) provisions automatically, debiting the user's credit balance.

Prerequisites

The user must be logged in. One-time:

npx otterkit login

This opens the browser, the user approves the device, and a token is saved to ~/.otterkit/credentials.json. Buy credits at https://console.otterkit.com. New accounts get a small free-credit grant to start.

For headless/CI agents, set OTTERKIT_TOKEN (create a token at console.otterkit.com → API Tokens) instead of running otterkit login.

Check the logged-in account and balance:

npx otterkit whoami
npx otterkit balance

OpenClaw: Wake Your Claw From Public Webhooks (zero gateway exposure)

The OpenClaw gateway binds to loopback (default port 18789), so external services can't reach /hooks/wake or /hooks/agent directly. The safest integration keeps it that way: a capture-only OtterKit endpoint takes the public traffic, and --deliver-exec relays each delivery to the gateway on loopback:

npx otterkit webhook --subdomain my-claw-hooks --standby --daemon \
  --deliver-exec 'curl -s -X POST http://127.0.0.1:18789/hooks/wake \
    -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
    -H "Content-Type: application/json" -d @-'

Point providers at https://my-claw-hooks.otterkit.app. Each capture's body arrives on the exec command's stdin (-d @- passes it through); metadata comes in OTTERKIT_* env vars. The gateway port is never public, providers always get a 200 (with --standby, even while the laptop is asleep - up to 200 requests are buffered and relayed on reconnect), and every delivery is in the capture log for inspect/replay. Use a dedicated hooks.token, not the gateway auth token.

An agent can also block on the next delivery instead of polling:

npx otterkit await my-claw-hooks --count 1 --timeout 120s --json

OpenClaw: Direct Tunnel to the Gateway

If a caller needs a real endpoint on the gateway itself (e.g. /hooks/agent responses, or remote Control UI access), tunnel the port with a stable URL:

npx otterkit tunnel 18789 --subdomain my-claw --daemon --ttl 7d

Then hand providers the public hook URL (keep hooks.token required in openclaw.json - the tunnel does not remove auth):

curl -X POST https://my-claw.otterkit.app/hooks/wake \
  -H 'Authorization: Bearer HOOKS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text":"CI build failed","mode":"now"}'

Notes for this setup:

• --subdomain gives the same URL across restarts, so provider configs don't go stale. Holding the name is free.
• Add --log to capture every delivery for inspect/replay debugging.
• The tunnel forwards the whole gateway port. Keep the gateway token and hooks token set; use a dedicated hooks token, not the gateway auth token. Stop the tunnel (otterkit stop my-claw) when public access isn't needed. Prefer the capture-and-relay setup above when providers only need to deliver events.

When to Use

• User wants external events (CI, Stripe, GitHub, forms, sensors) to wake their OpenClaw agent
• User asks to expose a local port or server to the internet
• User needs a public URL for a local development server or their OpenClaw gateway webhooks
• User wants to share their localhost with others
• User needs a webhook endpoint to capture incoming HTTP requests (no local server needed)
• User needs to receive webhook callbacks from third-party services (Stripe, GitHub, Slack, etc.)
• User needs to debug webhook integrations (capture + forward + replay)
• User fixed a webhook handler and wants to re-test it against a real captured payload
• User wants the public tunnel URL protected so only callers with credentials reach their server

Commands

Tunnel (1 credit/hour)

npx otterkit tunnel                      # foreground, Ctrl+C to stop
npx otterkit tunnel  --daemon --ttl 4h   # background, auto-stops after TTL (default 24h, max 7d)
npx otterkit tunnel  --subdomain myapp   # stable URL: https://myapp.otterkit.app every run
npx otterkit tunnel  --auth user:pass    # require HTTP Basic auth (enforced locally, free)
npx otterkit tunnel  --log               # also capture every request for inspect/replay

Default URLs are random (https://agent-.otterkit.app); --subdomain claims a persistent name to the user's account (free to hold; if taken, the command fails with no charge). --auth returns 401 before anything reaches the local server; credentials never touch OtterKit's servers.

Pricing: 1 credit/hour while connected, first hour at provision, max 10 credits/day per tunnel, free while disconnected.

Webhook Endpoint (capture-only, no local server)

npx otterkit webhook [--daemon] [--ttl 4h] [--subdomain name]
npx otterkit webhook --respond 204                              # custom auto-response status
npx otterkit webhook --respond 200 --respond-body '{"ok":true}' # custom body (challenge echoes)
npx otterkit webhook --standby                                  # server answers + buffers while disconnected

Every request is saved to ~/.otterkit/requests/.jsonl. Same pricing as tunnels. --standby keeps the endpoint live while the CLI is offline, buffering up to 200 captures (64 KB bodies) and replaying them into the local log on reconnect.

Local delivery and waiting:

npx otterkit webhook --deliver 3000                    # mirror every capture to a local server
npx otterkit webhook --deliver-exec './on-event.sh'    # run a command per capture (body on stdin, OTTERKIT_* env)
npx otterkit await  --count 1 --timeout 120s --json   # block until a matching request lands (exit 2 on timeout)

Inspect & Replay Captured Requests

npx otterkit inspect                         # last 20 captures
npx otterkit inspect  --json --last 50       # raw JSONL for piping
npx otterkit inspect  --follow               # live-tail
npx otterkit inspect  --method POST --status 5xx --path /hook
npx otterkit inspect  --har > session.har    # HAR 1.2 export

npx otterkit replay                          # re-send latest capture to the local server
npx otterkit replay  --index 3 --target 127.0.0.1:3000
npx otterkit replay  --method PUT -H "X-Debug: 1" --body '{"event":"retry"}' --json

replay re-sends straight to the local server - no tunnel round-trip, no credits spent. Ideal loop: capture the real payload once, fix the handler, replay until it returns 200. Exit code 0 whenever the local server responded (even 4xx/5xx), 1 if unreachable.

Project Config (otterkit up / down)

Define profiles in otterkit.toml, bring them all up as daemons with one idempotent command:

[tunnels.claw]
port = 18789
subdomain = "my-claw"
log = true
ttl = "7d"

[tunnels.hooks]
webhook = true
respond = 200

npx otterkit up --json
npx otterkit down

Status, Stop, Account

npx otterkit status              # running daemons: URL, target, TTL, PID
npx otterkit stop     # stop a daemon
npx otterkit subdomains          # list/reserve/release stable names
npx otterkit whoami              # account + balance

JSON Output (use when scripting)

Prefer --json on tunnel --daemon, webhook --daemon, up, down, status, inspect, replay, subdomains list, whoami, balance. Provision results include {subdomain, publicUrl, target, pid, ttl, expiresAt, logPath}. Errors are JSON too (e.g. {"error":"insufficient_credits","topUpUrl":"..."}) with exit code 1.

URL=$(npx otterkit tunnel 3000 --daemon --json | jq -r .publicUrl)

Troubleshooting

• "Not logged in" → npx otterkit login (one-time), or set OTTERKIT_TOKEN for headless machines.
• "Out of credits" / insufficient_credits → top up at https://console.otterkit.com/billing.
• Pricing check: curl https://otterkit.app/api/agent/pricing