justtunnel [port]

Open a tunnel from localhost:<port> to a public HTTPS URL. This is the default action when you run justtunnel with no subcommand.

If no auth token is configured and you're running in an interactive terminal, the CLI starts the GitHub device flow before opening the tunnel — same path as justtunnel auth. In non-interactive shells (CI, supervisors) the command exits with an auth error and points you at JUSTTUNNEL_AUTH_TOKEN.

Synopsis

justtunnel [port] [flags]

The port argument is required unless you pass --config-file (multi-tunnel mode). Valid ports are 1-65535.

Examples

Expose a Next.js dev server

justtunnel 3000

The CLI prints a banner like:

✔ Connected to api.justtunnel.dev
  Forwarding  https://wandering-otter-42.justtunnel.dev → http://localhost:3000

  Status      Online
  Plan        Free  ·  1/1 tunnels
  Local       http://localhost:3000

  Press Ctrl+C to stop.

Pin a specific subdomain

justtunnel 3000 --subdomain api-staging

Reserved subdomains require a paid plan. See Reserve a subdomain.

Password-protect a tunnel

justtunnel 8080 --password 'staging-only'

The password must be 4-128 characters. Visitors get a basic-auth prompt before requests reach your local server.

Run multiple tunnels from a YAML file

justtunnel --config-file tunnels.yaml

Each entry in tunnels.yaml becomes its own tunnel. The TUI supports adding and removing entries while the file is being watched. See Use a tunnels.yaml config file.

Tighten the local-target timeout

justtunnel 3000 --local-timeout 5s

Useful when you want fast failure on a slow local backend instead of the default 30s wait per request.

Run under a different context for one invocation

justtunnel 3000 --context team:acme

--context is a persistent flag — it works on every subcommand. See justtunnel context.

Flags

Flag	Type	Default	Description
--config-file <string>	string	—	YAML config file with tunnel definitions
--local-timeout <duration>	duration	30s	per-request timeout when proxying to the local target (e.g. 30s, 1m)
--log-level <string>	string	info	log level (debug, info, warn, error)
--max-reconnect-attempts <int>	int	50	maximum number of reconnection attempts (0 = unlimited)
--password <string>	string	—	password-protect the tunnel (4-128 chars)
-s, --subdomain <string>	string	—	request a specific subdomain
--config <string>	string	—	config file (default ~/.config/justtunnel/config.yaml)
--context <string>	string	—	context override for this invocation (e.g. personal, team:<slug>)

The --config and --context flags are persistent and apply to every subcommand. The remaining flags are specific to the root command.

Exit codes

Code	Meaning
0	Tunnel closed cleanly (Ctrl-C, SIGTERM, or non-error server close).
1	Failure — invalid port, auth error, network error, plan limit reached, subdomain unavailable, reconnection attempts exhausted, or any other runtime error.

Environment variables

Variable	Purpose
`JUSTTUNNEL_AUTH_TOKEN`	Used as the API token when no token is saved in the config file. Required for non-interactive use.