Contexts

A context is the identity the CLI uses for the current invocation. Every context is either personal (your individual account) or team:<slug> (a team you belong to). Tunnels you open and workers you create are scoped to whichever context is active.

Contexts exist because most developers have at least two relationships with JustTunnel: their own side projects, and one or more teams they collaborate with. Without contexts you'd have to log out and back in every time you switched accounts. The context model lets you switch with a single command — and override per-invocation when one-off cases need a different identity.

How it works

On every CLI invocation, the active context is resolved in this order:

1. --context flag — if present, wins for this invocation only. Local config is not modified.
2. Local config (~/.justtunnel/config.yaml) — set by justtunnel context use.
3. Default personal — if no override and no stored context.

The active context is then sent to the server with every authenticated request. The server uses it to scope tunnel ownership, billing, worker visibility, and reserved-subdomain lookups. personal always resolves to your individual account; team:<slug> requires that you're an active member of that team — the server rejects the request otherwise.

What contexts affect

Operation	Personal	Team
Opening a tunnel	Counts against your personal limits	Counts against the team's limits
Reserving a subdomain	Held by your user	Held by the team
Creating a worker tunnel	Rejected — workers are team-only	Allowed if signed in as a member
Listing teams	Always lists every team you belong to	Same
Billing	Personal Stripe customer	Team's Stripe subscription

The asymmetry on workers is intentional: workers are long-lived team infrastructure. Trying to run any justtunnel worker ... command on personal exits with worker commands require a team context. See Worker tunnels.

Switching contexts

Set the active context globally:

justtunnel context use team:acme

The CLI verifies your membership against the server before writing the local config. A bogus team slug fails fast with a clear error rather than silently succeeding. If the server is unreachable, the CLI prints a stderr warning and still updates the local config so you can keep working offline; membership is re-verified on the next online invocation.

Inspect the active context:

justtunnel context show
# team:acme

Override for one invocation only:

justtunnel 3000 --context team:beta-co

Full CLI reference at justtunnel context. Task-oriented walkthrough at Switch between accounts (contexts).

Limits and guarantees

What's enforced today:

• Personal is always available. Even when you're not signed in, justtunnel context list shows personal along with a hint to run justtunnel auth.
• Team membership is verified server-side. context use team:<slug> checks the server before writing the config. Bogus slugs fail with you are not a member of team:<slug>.
• Worker commands require a team context. Server-side check; the CLI also enforces locally to fail fast.
• Anyone signed in can create a team. There is no plan gate on team creation itself — free users can create teams (verified in internal/teams/service_test.go:111). Team-plan limits and per-seat pricing only kick in when a team chooses to upgrade. See Plans and limits.

Best-effort, not guaranteed:

• Offline context switching. If the server is unreachable when you run context use, the CLI accepts the change and re-verifies on the next online call. A team you've been removed from will eventually fail server-side checks even if your local config still references it.

Related

• justtunnel context — full CLI reference (list, use, show).
• Switch between accounts (contexts) — task-oriented walkthrough.
• Worker tunnels — workers require a team context.
• Plans and limits — what team plans include vs personal plans.