Docs
From an empty cluster to tether ssh box1.
1. Run the hub
The hub is one container with a SQLite file. Install it with the Helm chart from the download page (it pulls gocarlos/tether-hub from Docker Hub), or run the image standalone with Docker. Three things must be right:
- Public URL (
publicUrl/TETHER_PUBLIC_URL): the https address agents and browsers use. It is baked into the install script and the session cookie. - WebSockets through your ingress: agents keep one connection open for days, SSH sessions for hours. The chart sets 3600 s read/send timeouts for ingress-nginx; other ingress controllers need the equivalent.
- Secrets: a JWT secret of at least 32 characters, the first admin's email and password, and optionally a registration token to seed.
helm upgrade --install tether ./tether-hub-chart.tgz -n tether --create-namespace \
--set publicUrl=https://tether.example.com --set ingress.host=tether.example.com \
--set secrets.jwtSecret="$(openssl rand -hex 32)" \
--set secrets.adminEmail=you@example.com --set secrets.adminPassword='change-me-now'Check https://tether.example.com/api/v1/health returns {"status":"ok"}.
Security settings
The defaults are safe; these chart values (environment variables in brackets) adapt them to your setup:
- Client IP (
security.trustedProxyHops/TETHER_TRUSTED_PROXY_HOPS): how many reverse proxies in front of the hub append toX-Forwarded-For. The hub takes the client address that many entries from the right, so a client cannot fake its IP in the audit log or dodge the login limits. The chart picks 1 behind ingress-nginx and 2 on GKE; the Docker image alone uses 0 (the TCP peer). - Login limits (
security.loginRatePerMin/TETHER_LOGIN_RATE_PER_MIN, default 10;security.loginLockoutMinutes/TETHER_LOGIN_LOCKOUT_MIN, default 30): failed logins, 2FA codes and registration tokens per client IP and minute, and the longest account lockout. After 5 wrong passwords or codes in a row an account is locked for 1, 2, 4 … minutes; the hub answers429withRetry-Afterand records it in the audit log. - Other web origins (
security.corsOrigins/TETHER_CORS_ORIGINS): browsers may only call the API and open the terminal from the hub's own address. List extra origins here, for example a development server. - Sandbox for proxied pages (
security.proxySandbox/TETHER_PROXY_SANDBOX, off by default): pages opened through HTTP ports run on the hub's address. Turned on, they are served in a sandbox and cannot reach your hub session, even if the box or its app is compromised. Apps that rely on their own login cookies or browser storage stop working, so turn it on when your boxes run simple status pages, or when you do not fully trust them.
The hub sends the usual browser protections (Content-Security-Policy, X-Frame-Options, nosniff, no referrer, HSTS behind https) and never accepts a login token in a URL.
2. First login
Open the public URL and sign in with the admin email and password you set. The admin user is created only when the database is empty; later changes to those values have no effect (use the Users page or the account page instead).
3. Add a box
- Add box → Create token. Give it a label (where it will be used). The secret is shown once; the list afterwards only shows a prefix and how often it was used.
- Run the one-liner on the box as root. It downloads the static agent for the CPU architecture from your hub, registers the box, writes
/etc/tether/config.toml(0600) and enables a systemd service that starts at boot and restarts on failure.
curl -fsSL https://<your-hub>/install.sh | sudo bash -s -- --token <registration-token> --name box1 --ports 22,80,8080 --tags lab
systemctl status tether # active (running)
journalctl -u tether -f # "connected to wss://… registered as agent …"Useful flags: --ports lists what to advertise in the UI; --restrict-ports additionally forbids the hub from opening any other port; --insecure accepts a self-signed hub certificate in a lab. If a name is taken the box gets a numbered suffix, like a GitLab runner. sudo tether uninstall --purge removes service, config and binary.
Which account the agent runs as
By default the service runs as the user who ran sudo to install it, so the browser terminal is a shell as that account, with its home writable and the rest of the system read-only. Choose differently at install time:
--system-usercreates a dedicated, unprivilegedtethersystem user (no home, no login shell). Use it when hub admins should not see a person's files.--user NAMEruns as any existing account;--user rootruns as root.- Logged in as root without
sudothere is no installing user, so the agent falls back to thetethersystem user and says so.
The choice is saved as service_user in /etc/tether/config.toml and kept when you reinstall. Boxes installed by a 0.3.x agent keep running as tether; to switch one, run sudo tether install --url … --token … --user NAME again.
Add a Mac
Macs (macOS 11 or newer, Apple silicon or Intel) join the same way: the one-liner above detects macOS, fetches tether-macos-<arch> from your hub and installs a launchd daemon instead of a systemd unit. Or install with Homebrew first (see the download page):
brew tap smtech/tether https://tether-pro.web.app/brew/tether.git
brew install smtech/tether/tether
sudo tether install --url https://<your-hub> --token <registration-token> --name mac1 --ports 22
sudo launchctl print system/ch.smtech.tether # state = running
tail -f /var/log/tether.log # "connected to wss://… registered as agent …"- The daemon
ch.smtech.tether(/Library/LaunchDaemons) starts at boot, without anyone logged in, and restarts on failure. It runs/usr/local/bin/tetheras the user who ransudo, or--user NAME;--system-useris Linux-only. - SSH needs Remote Login: System Settings → General → Sharing, or
sudo systemsetup -setremotelogin on. Thentether ssh you@mac1works like for any box;tether installwarns while port 22 is closed. - Web terminal: macOS has no equivalent of the systemd hardening, so the terminal is a normal shell as that account. If it is an admin account,
sudoworks there for anyone who knows its password. Install as a standard account (--user) or with--no-shellif hub admins should get less. - Same config (
/etc/tether/config.toml), samesudo tether upgrade,--auto-upgradeandsudo tether uninstall --purgeas on Linux.brew upgrade tetheronly updates the command on your PATH, not the daemon's copy.
The box appears in Boxes within seconds, with hostname, IPs, OS release, kernel, agent version, CPU count, load, memory, disk usage, uptime and the ports it is listening on. Metrics refresh every 15 seconds, system facts (OS, kernel, IPs, agent version) every 5 minutes, so an upgrade shows up without a reconnect.
4. Open HTTP ports
Every advertised or listening port is a link: https://tether.example.com/p/<box-id>/<port>/. The hub opens a tunnel stream per request, speaks HTTP/1.1 to 127.0.0.1:<port> on the box and streams the answer back. Only logged-in users can open these links (the session cookie is checked and never forwarded to the box).
The hub sets X-Forwarded-Prefix, X-Forwarded-Host and X-Forwarded-Proto, and rewrites absolute Location redirects. Apps that generate absolute links without honouring the prefix (some SPAs) may not render correctly through the path-based proxy; per-box subdomains are on the roadmap.
5. SSH into a box
Install the tether binary on your laptop (download; on a Mac brew install smtech/tether/tether) and log in once; the token is stored in ~/.config/tether/client.toml and lasts 90 days.
tether login --url https://<your-hub> --email you@example.com
tether ssh admin@box1 # wraps: ssh -o ProxyCommand="tether proxy %h" admin@box1
tether ssh admin@box1 -- -L 5432:localhost:5432 # extra ssh args after --Or integrate with plain OpenSSH so every tool (scp, rsync, VS Code Remote) works:
# ~/.ssh/config
Host *.tether
ProxyCommand tether proxy %h
User admin
ssh box1.tether
scp file.txt box1.tether:/tmp/The hub only forwards encrypted bytes; authentication is still your SSH key against the box's sshd. Nothing on the box listens for inbound connections.
Terminal in the browser
Admins also get Open terminal on the box page: a login shell on the box, started by the agent in a pseudo-terminal and shown in the browser — no ssh client, no key, handy from a phone. It runs as the agent's account — by default the user who installed it, or the tether system user with --system-user (see which account) — without sudo, every session is written to the audit log, and a box can opt out with tether install --no-shell or shell_enabled = false in /etc/tether/config.toml. Needs agent 0.3 or newer — see Upgrading.
6. Users and roles
Admins manage boxes, registration tokens and users. Operators see boxes, open ports and connect over SSH. Passwords need at least 10 characters. Deleting a box in the UI disconnects its agent immediately and the agent cannot reconnect until re-registered.
Two-factor authentication
Each user can turn on a TOTP second factor under Account: scan the QR code with Microsoft Authenticator, Google Authenticator or any TOTP app and confirm with the first code. From then on the web login and tether login ask for the 6-digit code after the password. Turning it off needs the password and a current code. Each code works once: a code that was accepted is refused for the rest of its 30-second window. After 3 wrong codes the login starts over at the password. Admins see 2FA changes in the audit log.
Audit log
Admins find Audit log in the navigation: logins and failed attempts, locked accounts and rate-limited addresses, password and 2FA changes, users, registration tokens, box registrations, connects and disconnects, renames and removals, every SSH/TCP session and (once per 10 minutes per user, box and port) HTTP access through the proxy — each with actor, target, detail and client IP. Entries are kept for 180 days and pruned nightly; filter by event type or search by user, box or detail.
7. Operations
- Backups: the SQLite file on the persistent volume (
/data/tether.db). Copy it while the pod runs (WAL mode) or snapshot the volume. - Upgrades: see Upgrading; the Deployment uses
Recreateand agents reconnect within seconds. Protocol changes are versioned; the hub logs a mismatch. - One replica: the live agent registry is in memory. Horizontal scaling is on the roadmap.
- Logs: structured text logs on stdout;
RUST_LOG=debug(chart valuelogLevel) shows every tunnel open.
8. Upgrading
Upgrade the hub first, then the boxes. New agent features (like the browser terminal) only appear once both sides are current; the box page shows agent outdated next to a box whose agent is older than the one the hub ships, and the sidebar shows the hub version.
Hub on Kubernetes
helm upgrade tether ./tether-hub-chart.tgz -n tether --reuse-values --set image.tag=2026.11.16-095bdc6
kubectl -n tether rollout status deploy/tether-hub
curl -s https://tether.example.com/api/v1/info # "version":"2026.11.16-095bdc6"With the chart from the download page the new appVersion is the default tag, so helm upgrade with the new .tgz and your existing values is enough. Agents reconnect by themselves (backoff 1–60 s); open tunnels are cut and re-established on the next request.
Hub with Docker
docker pull gocarlos/tether-hub:2026.11.16-095bdc6
docker stop tether-hub && docker rm tether-hub
docker run -d --name tether-hub -p 8080:8080 -v tether-data:/data --env-file hub.env gocarlos/tether-hub:2026.11.16-095bdc6The SQLite file in the /data volume is migrated automatically on start; keep a copy before major upgrades.
Agent on a box
The hub ships the agent binaries it was built with under /dl/, so a box can upgrade itself from the hub it is registered at — no registration token, the box keeps its identity, name and tags:
sudo tether upgrade # compares versions, downloads, swaps the binary, restarts the service
sudo tether upgrade --force # reinstall even if the version matches
tether --versionEquivalent without the CLI (for example from a config-management tool): re-run the install one-liner from Add box without --token; on an already registered box it only replaces the binary and restarts the service.
curl -fsSL https://tether.example.com/install.sh | sudo bashUnattended agent upgrades (opt-in)
A box can keep itself current: with auto_upgrade = true in /etc/tether/config.toml (or --auto-upgrade on the install one-liner), the tether-upgrade.timer systemd timer (on a Mac the ch.smtech.tether-upgrade launchd daemon, log in /var/log/tether-upgrade.log) runs tether upgrade --auto every 30 minutes, which swaps the binary and restarts the service whenever the hub ships a different agent version. It is off by default — turning it on means whoever controls your hub decides what binary runs on the box, so use it for hubs you operate yourself.
curl -fsSL https://tether.example.com/install.sh | sudo bash -s -- --token tether_reg_… --auto-upgrade
# or on an already installed box:
sudo sed -i 's/^auto_upgrade = .*/auto_upgrade = true/' /etc/tether/config.toml || echo 'auto_upgrade = true' | sudo tee -a /etc/tether/config.toml
systemctl list-timers tether-upgrade.timer # next check
journalctl -u tether-upgrade.service # what the last check didThe timer is installed by tether install and by the first manual tether upgrade on older boxes, so flipping the config key is all it takes; set it back to false to stop (the timer keeps firing but does nothing). sudo tether uninstall removes the timer too.
Agents older than 0.3.1 do not have tether upgrade yet: once the hub is upgraded, run that one-liner on the box once (no token needed, the existing config is reused); from then on sudo tether upgrade works. Downgrades work the same way against a hub that ships the older agent.
9. API keys and automation
Scripts and coding agents such as Claude cannot type a password or a 2FA code. Give them an API key instead: Account → API keys → Create key, with a name and an expiry (30, 90 or 365 days, or never). The key (tether_key_…) is shown once; the hub stores only its hash. It acts as you — the same boxes and the same admin rights — for the API, tether boxes, tether ssh and tether exec, but it cannot create keys or change your password or 2FA. The list shows when each key was last used; revoking one locks it out at once. Everything done with a key is in the audit log as you@example.com (API key claude).
# where the script or Claude runs: environment variables …
export TETHER_URL=https://tether.example.com TETHER_API_KEY=tether_key_…
# … or store the key in ~/.config/tether/client.toml (0600; the key is prompted for)
tether login --url https://tether.example.com --api-key
tether boxes # name, online, OS, agent version, IPs (--json for everything)
tether exec box1 -- uname -a # run a command, print its output, exit with its exit code
curl -H "Authorization: Bearer $TETHER_API_KEY" "$TETHER_URL/api/v1/agents"Running commands with tether exec
tether exec <box> -- <command> runs one command on a box through the hub — no ssh key, no open port — and streams its output (stdout and stderr) back. It exits with the command's exit code (255 when there is none), so scripts and agents can check the result; Ctrl+C stops the command and everything it started. Like the browser terminal it is admin only, runs as the agent's account with its login shell (no terminal, no input: DEBIAN_FRONTEND=noninteractive is set), is switched off together with the terminal by --no-shell / shell_enabled = false, and needs an agent of this release (sudo tether upgrade). Every command is written to the audit log (the first 500 characters), so do not put secrets on the command line.
Installing software needs root, which the agent's account normally does not have (on Linux the service even forbids sudo). Use tether ssh with your SSH key for that — it works with an API key too — or, on a box you dedicate to automation, run the agent as root (--user root), which makes tether exec and the terminal root shells for every hub admin:
tether ssh admin@box1 -- sudo apt-get install -y jq # your key, your sudo
tether exec box1 -- 'jq --version' # check as the agent's accountTo let Claude work on your boxes, put the two variables into the environment Claude runs in and tell it to use tether boxes, tether exec and tether ssh. Create one key per tool so you can revoke it on its own.
FAQ
Does the box need a public IP or open port?
No. The agent only makes an outbound HTTPS/WebSocket connection to the hub.
What does the hub see?
The box's metadata and metrics, and the bytes of the tunnels it opens on behalf of a logged-in user. SSH traffic is end-to-end encrypted between your ssh client and the box's sshd.
Can an agent reach other agents or the hub's cluster?
No. Agents receive three kinds of instruction: "connect stream N to 127.0.0.1:port", and, for admins, "start a shell for stream N" (browser terminal) and "run this command on stream N" (tether exec) — as the agent's own account, without sudo on Linux, audited, and only if the box has not opted out. They never open connections elsewhere.
macOS or Windows boxes?
Macs, yes: macOS 11 or newer, Apple silicon and Intel, as a launchd daemon (see Add a Mac); the same binary is the operator CLI. Windows: not for now.
Is it really free?
Yes. Tether is freeware from SM Tech GmbH Swiss: free for personal and commercial use, no registration, no phone-home. See the licence on the download page.