cftunnel（cftunnel 命令行）

cftunnel — Cloudflare Tunnel Manager for AI Agents

Expose local services to the internet via Cloudflare Tunnels. Use this skill when you need to make a locally running application accessible at a public HTTPS URL.

Flow: Start a local service (e.g. on port 3000) → cftunnel creates a tunnel + DNS route → the service is live at https://hostname.domain.com.

Authentication

Set these environment variables before running any command:

# Option A: API Key + Email (most common)
export CLOUDFLARE_API_KEY=<api-key>
export CLOUDFLARE_EMAIL=<account-email>

# Option B: API Token (scoped, if available)
export CLOUDFLARE_API_TOKEN=<api-token>

# Always required:
export CLOUDFLARE_ACCOUNT_ID=<account-id>

Quick Reference

Expose a local service (fastest path)

If a tunnel and cloudflared are already running (check with tunnel list), just add a route and DNS:

# 1. Add ingress route to existing tunnel
npx cftunnel route add <tunnel-id> --hostname <hostname> --service http://localhost:<port>

# 2. Create DNS CNAME
npx cftunnel dns create --zone-id <zone-id> --hostname <hostname> --tunnel-id <tunnel-id>

Create everything from scratch (one command)

npx cftunnel quickstart \
  --name <tunnel-name> \
  --hostname <hostname> \
  --service http://localhost:<port> \
  --zone-id <zone-id>

Then run the connector: npx cftunnel run <tunnel-id>

Programmatic usage (Node.js library)

import { createClient, quickstart } from 'cftunnel';

const client = createClient({ apiKey: '...', apiEmail: '...' });
const result = await quickstart(client, {
  accountId: '...',
  name: 'my-app',
  hostname: 'app.example.com',
  service: 'http://localhost:3000',
  zoneId: '...',
});
console.log(result.run_cmd);

All Commands

Tunnel lifecycle

Ingress routes (hostname → local service mapping)

DNS records

Running the connector

Decision Guide

"I need to expose port N on a domain" → Check tunnel list for a healthy tunnel. If one exists, use route add + dns create. If not, use quickstart.

"I need to add another service to an existing tunnel" → route add + dns create. One tunnel can serve many hostnames.

"I need to change where a hostname points" → route remove --hostname X then route add --hostname X --service <new-url>. DNS stays the same.

"I need to take a service offline" → route remove --hostname X and optionally dns delete <record-id>.

"The tunnel exists but cloudflared isn't running" → npx cftunnel run <tunnel-id> or use tunnel token to get the token for manual cloudflared invocation.

Service URL Formats

The --service flag accepts these protocols:

Output Format

All commands output JSON to stdout. Progress/errors go to stderr.

Parse with jq:

TUNNEL_ID=$(npx cftunnel tunnel create my-app | jq -r '.id')
TOKEN=$(npx cftunnel tunnel token $TUNNEL_ID | jq -r '.token')

Common Patterns

Pattern 1: Deploy a new web app

cd /path/to/app && npm start &

npx cftunnel quickstart \
  --name my-web-app \
  --hostname app.example.com \
  --service http://localhost:8080 \
  --zone-id <zone-id>

npx cftunnel run <tunnel-id-from-output>

Pattern 2: Add subdomain to existing tunnel

npx cftunnel tunnel list | jq '.[] | select(.status == "healthy")'

npx cftunnel route add <tunnel-id> --hostname api.example.com --service http://localhost:4000
npx cftunnel dns create --zone-id <zone-id> --hostname api.example.com --tunnel-id <tunnel-id>

Pattern 3: Swap service behind a hostname

npx cftunnel route remove <tunnel-id> --hostname app.example.com
npx cftunnel route add <tunnel-id> --hostname app.example.com --service http://localhost:9000

Pattern 4: Clean teardown

npx cftunnel route remove <tunnel-id> --hostname app.example.com
npx cftunnel dns list --zone-id <zone-id>
npx cftunnel dns delete <record-id> --zone-id <zone-id>
npx cftunnel tunnel delete <tunnel-id>

Pattern 5: Programmatic usage in agent code

import { createClient, createTunnel, addRoute, createDNS } from 'cftunnel';

const client = createClient(); // reads from env vars
const tunnel = await createTunnel(client, { accountId: '...', name: 'my-app' });
await addRoute(client, {
  accountId: '...',
  tunnelId: tunnel.id,
  hostname: 'app.example.com',
  service: 'http://localhost:3000',
});
await createDNS(client, {
  zoneId: '...',
  hostname: 'app.example.com',
  tunnelId: tunnel.id,
});

Important Notes

• A tunnel must have cloudflared running to serve traffic. Creating a tunnel and routes alone is not enough.
• The catch-all http_status:404 rule is always appended automatically. Do not add it manually.
• DNS CNAME records must be proxied through Cloudflare (orange cloud). This is set automatically.
• One tunnel can serve multiple hostnames. Prefer reusing existing healthy tunnels over creating new ones.
• route set replaces ALL routes. Use route add/route remove for incremental changes.
• If cloudflared is already running as a service, route changes take effect immediately (no restart needed).

Global Flags