Tunneling & CLI

Tunneling streams incoming webhooks directly to your local machine over a WebSocket connection so you can debug against localhost without deploying.

Permanent endpoints require a paid account. Temporary endpoints can tunnel without login.

How it works

1. The CatchHook CLI opens a WebSocket connection to CatchHook.
2. Incoming webhooks are streamed to the CLI in real time.
3. The CLI forwards each request to your local URL.
4. The CLI reports local delivery results back to CatchHook for metrics and alerts.

Permanent endpoint flow

Use start directly. If no valid token is stored, the CLI opens browser auth automatically.

npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000

Headless alternatives:

# One-off
npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000 --token chk_dev_xxx

# Environment
CATCHHOOK_TOKEN=chk_dev_xxx npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000

Temporary endpoint flow

Temporary endpoints include a tunnel_key:

npx @catchhook/tunnel ep_abc123 --key tkey_abc123 --port 3000

No account login required.

Authentication model

• CLI auth creates a token scoped for tunneling and reads.
• CLI tokens expire after 30 days.
• Re-authenticating revokes older CLI tokens for that user/account.
• Browser callback uses a one-time auth code exchanged for the token by the CLI.

Connection limits

Troubleshooting