Usage and limits

This page tells you where to look when you suspect you're about to hit a plan limit, and what each limit error looks like when you trip it.

For the actual numbers per tier, see Plans and limits — that page is generated against the server's enforcer and is canonical.

Where to see what you're using

From the CLI

justtunnel status is the single command that reports your current account state:

justtunnel status

It prints your active plan, your active context, and (when authenticated) high-level account info. It's the fastest way to confirm "what plan am I on right now?" — including any gifted plan that overrides your Stripe plan. See justtunnel status.

From the dashboard

The dashboard shows your plan, current tunnels, and reserved subdomains. The Stripe billing portal (linked from the dashboard) is canonical for invoices, payment methods, and subscription state.

Programmatically

GET /api/plans returns the limits matrix for every tier with no auth required. The landing page renders against this endpoint so the published numbers always match what the server enforces.

What you see when you hit a limit

The server emits three structured limit errors. Each carries a stable code field, a human-readable message, and an upgrade URL. The CLI surfaces the message verbatim.

TUNNEL_LIMIT_REACHED

You tried to open a tunnel beyond your plan's concurrent-tunnel cap. Source: internal/plan/enforcer.go:69.

Free plan limited to 1 tunnel. Upgrade to Starter for 2 or Pro for 5.

The wording adapts to your plan — Starter sees "Upgrade to Pro for 5"; Pro sees "Pro plan limited to 5 tunnels."

Fix: close one of your existing tunnels, or upgrade. justtunnel (with no subcommand) lists your active tunnels; closing the CLI process for a tunnel ends that session.

PLAN_LIMIT_REACHED

You tried to set a password on a tunnel and you're already at your plan's password-protected-tunnel cap. Source: internal/plan/enforcer.go:87.

Your free plan allows 1 password-protected tunnel(s). Upgrade for more.

Fix: drop the --password flag, close one of your existing password-protected tunnels, or upgrade. See Password protection.

RESERVED_SUBDOMAIN_NOT_ALLOWED

You passed --subdomain <name> on a non-Pro plan. Source: internal/plan/enforcer.go:106.

Reserved subdomains require a Pro plan. Upgrade to Pro for reserved subdomains.

Fix: drop --subdomain (you'll get a random name) or upgrade to Pro. Random names are fine for webhooks and demos; reserved names are for staging URLs that need to stay the same. See Subdomains.

Edge-level limits

Two limits are enforced at the edge proxy rather than at tunnel-create:

• Per-tunnel rate limit. Requests beyond your plan's per-minute budget receive HTTP 429. The limit is applied per-tunnel, not per-account, so two tunnels each get their own bucket.
• Inactivity reaper (Free only). A tunnel with no traffic for 2h is closed by the edge. Your CLI will reconnect if it's still running. Paid plans have no reaper.

These limits are not surfaced as JustTunnel error codes — they look like a normal 429 or a normal WebSocket close to the client.

When a downgrade hits your limits

If your plan downgrades — voluntary cancellation, payment failure past grace, or a manual admin action — the server enforces the new caps automatically:

• Excess tunnels are closed oldest-first (internal/billing/downgrade.go:39).
• Reserved subdomains are released if you're dropping away from Pro (internal/billing/downgrade.go:60).
• Workers above the new cap are quarantined.

You receive a "plan downgraded" email when this happens. See Upgrade and downgrade → What happens on downgrade.

Related

• Plans and limits — the per-tier numeric matrix (canonical)
• Plans — what each tier unlocks
• Upgrade and downgrade — moving between tiers
• justtunnel status — confirm your active plan from the CLI