Install & manage

Stand up a long-lived worker tunnel — create, install, start, monitor, and tear it down.

This guide walks through the full lifecycle of a worker tunnel: install it as a managed service, confirm it's running, tail its logs, run it in the foreground for debugging, and cleanly tear it down.

You'll need:

An authenticated CLI (justtunnel auth).
A team you belong to. Worker tunnels are team-only — switch contexts before any worker ... command.
macOS or Linux for the managed-service path. Windows supports worker start in the foreground but not worker install — see Platform support.

Steps

1. Switch into the team context

justtunnel context use team:acme

Every worker command resolves the team from the active context. If you skip this step, worker ... exits with worker commands require a team context.

2. Create and install the worker

justtunnel worker install staging-api

Installed worker "staging-api" (id=wrk_abc123) in team:acme
  url: https://staging-api--acme.justtunnel.dev

worker install does three things in order:

Registers the worker server-side (idempotent — re-running on an existing worker is fine).
Writes the per-worker config to ~/.justtunnel/.
Installs the platform-native service definition (launchd user agent on macOS, systemd --user unit on Linux).

The public URL is <name>--<team-slug>.justtunnel.dev. The CLI validates that this fits within the 63-character DNS label before contacting the server.

Linux: user-linger prompt

On Linux, the installer may ask whether to enable systemd user-linger so the service keeps running after you log out. Your options:

Approve — the service stays up across logout and reboot.
--no-linger — the service runs only while you're logged in; it stops on logout.
--non-interactive — equivalent to --no-linger for scripted installs (CI, provisioning scripts).

On macOS, launchd-user agents survive logout natively, so --no-linger and --non-interactive are no-ops. The CLI emits a stderr warning if you pass them on macOS.

3. Confirm it's running

justtunnel worker status

Workers in team:acme:
NAME          SERVER  LOCAL              LAST SEEN
staging-api   active  launchd:running    2026-05-06 12:34:56Z

The LOCAL column reports what the platform supervisor sees. launchd:running (macOS) or systemd:running (Linux) means the service is up. none means the worker isn't supervised — typically because it was created with worker create and never installed.

For a verbose detail view of a single worker:

justtunnel worker status staging-api

Worker:    staging-api
Context:   team:acme
Server:    active
Local:     launchd:running
Last Seen: 2026-05-06 12:34:56Z

4. Tail the logs

justtunnel worker logs staging-api -f

-f follows the active log file in real time, just like tail -f. Press Ctrl-C to exit. Other modes:

justtunnel worker logs staging-api — last 1000 lines (default).
justtunnel worker logs staging-api -n 100 — last 100 lines. The --lines value is capped at 100,000 to protect against typos.
justtunnel worker logs staging-api --all — every retained day, oldest first.

The supervisor writes to ~/.justtunnel/logs/worker-<name>.log. Daily rotation and 7-day / 100 MB retention are enforced automatically.

5. Run in the foreground (for debugging)

If you suspect the supervisor is masking an error, run the same code path directly:

justtunnel worker start staging-api

This blocks until SIGINT/SIGTERM or until the server closes the session. Logs stream to stderr (not the rotated log file) — useful when you want to watch live without -f.

6. Tear it down

justtunnel worker uninstall staging-api

Uninstalled worker "staging-api"

uninstall stops the service, removes the local service definition, and deletes the local config. The server-side worker record is preserved by default so you can re-install with the same name later. To also delete the server-side record:

justtunnel worker uninstall staging-api --delete-on-server

Uninstalled worker "staging-api" (server-side row quarantined; permanent removal in 30 days)

The server soft-deletes for 30 days; a background reaper removes the row after that. Run worker list --all to see quarantined workers.

If the install is wedged and the normal teardown fails, use --force:

justtunnel worker uninstall staging-api --force

--force continues past per-step failures, prints warnings to stderr, and exits 0. Use it when local config is corrupt or the supervisor is stuck.

Verify

After step 2, hit the worker URL from any machine:

curl -I https://staging-api--acme.justtunnel.dev

You should see whatever your local service returns (HTTP/2 200, etc.). After step 6 the URL should fail to resolve or return a 404.

To verify the service is managed by the platform supervisor, check it directly:

# macOS
launchctl list | grep justtunnel
 
# Linux
systemctl --user status justtunnel-worker-staging-api

worker status already wraps this in a portable form, but the native commands are useful when something is misbehaving.

Worker tunnels overview — concept overview and limits by plan tier.
Platform support — macOS, Linux, and Windows details.
Troubleshooting — common errors and fixes.
justtunnel worker — full CLI reference for every subcommand.
justtunnel context — switch into a team context before running worker commands.