Skip to main content
tunnelbyte [region] [-- <cmd>...] [flags]
The primary command. With no subcommand and an optional region argument, brings up a tunnel and either:
  • Exposes a localhost SOCKS5/HTTP proxy (default - per-app routing), or
  • Replaces your system default route (--all - sudo prompt on first run), or
  • Spawns a wrapped child process routed through the tunnel (-- <cmd>).
Ctrl-C tears the tunnel down.

​
Arguments

ArgumentRequiredDefault
regionnoGeolocate-and-pick. Persisted to your config dir (see overview).

​
Examples

Quickest start - auto-pick region, per-app proxy, live status line: 
$ tunnelbyte
✓ tunnel up via 116.203.42.7 (fsn) - anonymous tier
  proxy:           http://127.0.0.1:57412
  export HTTPS_PROXY=http://127.0.0.1:57412
  ↑ 12.4 MiB  ↓ 187.3 MiB  ·  4m 12s  ·  daily: 199 MiB / 1.0 GiB · 4m 12s / 30m 00s
  (Ctrl-C to tear down)
The bottom line refreshes once per second. On the paid tier it also shows the running cost at €0.01/min + €0.02/GiB (e.g. · €0.04). On --all and per-app modes, you see this line; when wrapping a child process, the child’s stdout owns the screen and the line is suppressed (the server-terminate poll still runs). Explicit region, persisted: 
$ tunnelbyte ash
Wrap a CLI command - auto-injects HTTPS_PROXY / HTTP_PROXY / ALL_PROXY into the child env: 
$ tunnelbyte sin -- curl https://api.ipify.org
Wrap a Chromium browser - the CLI knows how to launch it with a --proxy-server flag and a dedicated --user-data-dir, so the browser routes through the tunnel without touching your normal profile: 
$ tunnelbyte fsn -- brave         # also: chrome, edge, chromium, arc
✓ launching brave via 167.233.22.69 (fsn) - anonymous tier (persistent profile per region)
Profiles are persistent per (browser, region) pair under your config dir’s browser-profiles/ folder, so re-launching tunnelbyte fsn -- brave keeps your logins and bookmarks across sessions. Different regions get different profiles so cookies don’t leak across exit IPs. System-wide - your default route changes for the duration: 
$ tunnelbyte ash --all
✓ tunnel up via 51.34.65.83 (ash) - all traffic - free tier
  (Ctrl-C to tear down and restore default route)

​
Flags

FlagDefaultPurpose
--alloffRoute the system default through the tunnel. Requires elevated privileges on first run.
--region(positional arg)Override the region without writing to the persisted file.
-v, --verboseoffShow handshake / route diagnostics.

​
What happens under the hood

  1. Resolve region: positional arg → --region flag → persisted file → geo auto-pick.
  2. POST /v1/sessions to create a session and receive a wg_config.
  3. Bring up a userspace WireGuard interface in-process. No wg-quick, no kernel module, no sudo for the interface itself. On Linux with --all, switches to kernel WireGuard for the higher throughput.
  4. Either:
    • Default: start a localhost SOCKS5/HTTP proxy bound to a random port.
    • --all: prompt for sudo, install a 0.0.0.0/0 route via the tunnel.
    • -- <cmd>: launch the child with proxy env vars set (CLI commands) or with --proxy-server + a fresh --user-data-dir (known Chromium browsers).
  5. Poll /v1/sessions/{id} every 10 seconds. Renders bytes/elapsed/cost/quota live in TTY mode; appends once per minute on non-TTY (logs, pipes).
  6. Sleep until Ctrl-C, server-side expiration, or quota exhaustion.
  7. On exit: tear down the WireGuard interface; restore routing if --all.

​
Failure modes

  • Quota exhausted (exit 2): tier daily cap hit. The error body lists bytes_used, session_seconds, and resets_at. Wait, or signup / upgrade.
  • Server-terminate (exit 3): the server ended the running session - quota hit mid-session, idle (>5 min without handshake), or tier max-session time. The reason prints to stderr.
  • No active node: that region has no healthy nodes right now (503 + available: [...] in the body). Try one of the listed regions.

​
See also