Built for agents.

Mint a key with a cap

curl -X POST "$API/tokens" \
    -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "claude-agent-prod",
      "ttlHours": 720,
      "bandwidthLimitMbps": 100,
      "tunnelQuota": 10,
      "monthlyBudgetUsdCents": 5000
    }'

The response is the only place the full key value appears:

{
  "apiKey": "mtk_AAAB...full_value_here",
  "nonce": "9f2c4a7e1b3d5f60...",
  "issuedAt": 1786636800,
  "expiresAt": 1789228800,
  "tunnelQuota": 10,
  "bandwidthLimitMbps": 100,
  "allowedSubdomains": ["*"],
  "wireBytes": "AAABZm9vYmFy...",
  "wireBytesLen": 312,
  "version": 1, "subject": "...", "signature": "..."
}

Other body fields: allowedSubdomains (default ["*"]). ttlHours defaults to 24 and is capped at 2160 (90 days) — a longer request is cut to the maximum, not rejected, so read expiresAt. The budget isn't echoed back. Hand apiKey to the agent as MYTUNNEL_API_KEY.

Adjust the cap (owner only)

# Raise / lower
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": 1000 }'

# Uncap
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": null }'

# Freeze all spend (incident response)
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": 0 }'

$NONCE is the first 16 hex chars of the token's nonce, visible in the GET /tokens list. The budget is charged on the agent transport at tunnel-registration time — an over-budget agent's mytunnel register is rejected with a BUDGET_EXCEEDED protocol reason, and the agent should surface that to its operator rather than retry.

Declare the tunnels

# mytunnel.toml — one [tunnels.<name>] table per tunnel
[tunnels.tool]
type = "http"            # http | tcp | ssh | udp
port = 8080
subdomain = "tool"       # optional, http only

[tunnels.db]
type = "tcp"
port = 5432
# public_port = 30432    # optional, tcp/udp only

mytunnel start runs every tunnel in the file. It looks for --tunnels-config FILE, then ./mytunnel.toml, then ~/.config/mytunnel/tunnels.toml. Top-level server and token_file are optional. An unknown type or key is rejected up front, so a typo fails at startup instead of being skipped.

Install it as a service (Linux)

export MYTUNNEL_API_KEY="mtk_..."      # a project key
sudo -E mytunnel service install --tunnels-config ./mytunnel.toml

This copies the tunnels file to /etc/21tunnel/<name>.toml, writes the current key (from MYTUNNEL_API_KEY, --token-file, --token-env or mytunnel login) to /etc/21tunnel/<name>.key, readable by root only, and enables and starts 21tunnel-<name>.service. --name defaults to agent. The unit restarts forever (Restart=always, no start limit) and runs sandboxed: no capabilities, read-only filesystem.

journalctl -u 21tunnel-agent -f                # logs
sudo mytunnel service uninstall --name agent    # stop; remove unit, tunnels file, key

Install mytunnel system-wide first — the install one-liner run as root puts it in /usr/local/bin (curl -fsSL https://login.21tunnel.com/install.sh | sudo sh). The service refuses a binary in a home directory. It warns if the key expires within 14 days.

Reconnects by itself

Every tunnel command — http, tcp, udp, ssh, grpc, start, wg up — reconnects forever after a drop (server restart, server IP change, network blip), with exponential backoff and jitter from about 1 s up to 30 s. It re-resolves agent.21tunnel.com on every attempt and asks for the same subdomain or public port again, so the URL stays the same. A dead server is noticed through unanswered heartbeats (sent at most every 30 s).

It gives up, exiting non-zero, only on things a person has to fix: a key rejected on the first connect, an invalid subdomain, or a client too old for the server. A key rejected after it was already connected (revoked, expired, rotated) is retried every 30 s, re-reading a key file each time. Ctrl+C and SIGTERM stop it cleanly. To stop on the first drop instead, set auto_reconnect = false in a CLI config file passed with --config FILE (the file must also set server = "agent.21tunnel.com:7443" and region = "us-east"). The old reconnect_interval_secs setting is ignored; the backoff replaces it.

Rotate the key without a restart

mytunnel projects keys rotate <project> --key-file /etc/21tunnel/agent.key --grace 24

This mints an equivalent key — same project, quota, bandwidth, subdomains, budget and lifetime — and keeps the old one working for --grace hours (default 1; 0 revokes it at once). The new key is written back to the file atomically (mode 0600). The agent reading that file switches to it on its next reconnect, at the latest when the grace window ends (the server ends sessions on the old key within about 30 s of its expiry). That costs one reconnect of about a second, and no restart.

--if-expires-within HOURS makes it a no-op until the key has that many hours or fewer left, so a daily timer can call it unconditionally. Rotating needs a master key — the agent key can't rotate itself — so the agent host needs one. Keep it in its own root-only env file, separate from the agent key: /etc/21tunnel/rotate.env, mode 0600, containing MYTUNNEL_API_KEY=mtk_master_….

# /etc/systemd/system/21tunnel-agent-rotate.service
[Unit]
Description=Rotate the 21tunnel agent key before it expires
[Service]
Type=oneshot
# rotate.env holds MYTUNNEL_API_KEY=mtk_master_...
EnvironmentFile=/etc/21tunnel/rotate.env
ExecStart=/usr/local/bin/mytunnel projects keys rotate <project> --key-file /etc/21tunnel/agent.key --if-expires-within 720 --grace 24

# /etc/systemd/system/21tunnel-agent-rotate.timer
[Unit]
Description=Daily 21tunnel agent key rotation check
[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true
[Install]
WantedBy=timers.target

sudo systemctl enable --now 21tunnel-agent-rotate.timer

The master key expires too (default 90 days, at most 1 year): replace it in rotate.env before it does. Over REST the same call is POST /api/projects/<project>/tokens/<nonce>/rotate with {"graceHours": 24} (0–720). An expired but unrevoked key can still be rotated; master keys can't be rotated this way.

Stable names

Use a reserved subdomain (subdomain = "tool"). With a key from a project other than default, the server serves it as tool-<project>.21tunnel.com. For a name of your own, bind a custom domain to the tunnel in the dashboard. For an internal tool, a Google sign-in gate limited to your email domain keeps it to your team, on the *.21tunnel.com name and on any custom domain bound to the tunnel alike.

IDEM=$(uuidgen)

# First call
curl -X POST "$API/tunnels" \
    -H "Authorization: Bearer $JWT" \
    -H "Idempotency-Key: $IDEM" \
    -d '{"subdomain":"my-app","protocol":"http","localPort":3000}'

# Network blip → safe to repeat with the SAME key
curl -X POST "$API/tunnels" \
    -H "Authorization: Bearer $JWT" \
    -H "Idempotency-Key: $IDEM" \
    -d '{"subdomain":"my-app","protocol":"http","localPort":3000}'
# → identical response + header X-Idempotent-Replay: true

The cache key is a composite hash of api_key_id · method · path · body · header, so a leaked key from one tenant can't replay another tenant's request. Reusing the same key with a different body is a conflict (your retry logic has a bug).