Install the agent on a server

The agent runs on each server where your coding agents work. It connects out to Onetty, so you don't open any port, set up a VPN or give anyone SSH. No root needed.

1. 1 Get your install command

   Open the Onetty app → Team → Servers → Add server. You'll get one line like this:

   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   It works once and expires in 1 hour. No team yet? Create one first, it takes a minute.

2. 2 Run it on your server

   Log in to the server as the user that runs your coding agents (not root) and pick your system:

   Ubuntu · Debian Fedora · RHEL · Rocky · Alma Arch Amazon Linux openSUSE macOS

   Make sure curl is there, then paste your command:

   # once, if curl is missing
   sudo apt update && sudo apt install -y curl
   
   # your line from step 1
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   # once, if curl or tar are missing
   sudo dnf install -y curl tar
   
   # your line from step 1
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   RHEL / Rocky / Alma 8 or newer.

   # once, if curl or tar are missing
   sudo pacman -S --needed curl tar
   
   # your line from step 1
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   # once (Amazon Linux 2023 comes with curl)
   sudo dnf install -y tar
   
   # your line from step 1
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   Amazon Linux 2023. Amazon Linux 2 is too old for the bundled Node.

   # once, if curl or tar are missing
   sudo zypper install -y curl tar
   
   # your line from step 1
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   For agents you leave working on a Mac with Apple Silicon (M1 or newer). The installer needs Homebrew for tmux:

   # once, if you don't have Homebrew (see brew.sh)
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
   # your line from step 1 (it installs tmux with Homebrew if it's missing)
   curl -fsSL https://onetty.app/install.sh | sh -s -- --token … --owner …

   Run it in Terminal on the Mac, logged in as your user (not over SSH with nobody logged in: launchd needs your session). Open a new Terminal window afterwards to use the onetty command.

   It runs as a launchd agent of your user: it starts when you log in and updates itself. Keep that user logged in (the screen can be locked) and stop the Mac from sleeping while agents work: System Settings → Energy → Prevent automatic sleeping.

   Intel Macs aren't supported. Step 3 (linger) is Linux only: skip it.

   The installer puts everything in your home folder (~/.local/share/onetty): its own Node.js and tmux, checked against published hashes. It sets up a user service that starts on boot and updates itself.

3. 3 Keep it running after you log out

   So the agent keeps working when nobody is logged in to the server:

   sudo loginctl enable-linger $USER

   The installer tries this for you; if it couldn't, it tells you to run it.

4. 4 Add the server to your team

   Back in the app, Team → Servers: the new server shows up. Tap Add. That's it: your sessions on that server appear in the app.

   The installer doesn't install coding agents. Install and log in to the ones you use on the server as usual (for example claude, codex, grok, qwen): Onetty finds their sessions on its own.

onetty agent status          # connected to the hub?
onetty setup --check         # service, hooks, updates
systemctl --user status onetty                    # Linux
launchctl print gui/$(id -u)/app.onetty.serve     # macOS

onetty hooks uninstall
onetty wrap uninstall
systemctl --user disable --now onetty onetty-update.timer   # Linux
launchctl bootout gui/$(id -u)/app.onetty.serve; launchctl bootout gui/$(id -u)/app.onetty.update   # macOS
rm -f ~/Library/LaunchAgents/app.onetty.*.plist                                        # macOS
rm -rf ~/.local/share/onetty ~/.local/bin/onetty ~/.config/onetty