Getting started

Sox is a native remote development terminal for macOS. It owns the SSH connection, the remote shells, and the workspace context, then renders those shells as GPU-accelerated terminal surfaces — so working on a remote host does not mean living in a second terminal app.

Requirements

• macOS 13.0 or newer
• Apple silicon
• For remote work: a host you can already reach with ssh. Sox reads your existing SSH config; it does not manage keys or ask for credentials.

Install

Download Sox (stable), open the disk image, and drag Sox.app into Applications. Builds are signed and notarized, so the first launch opens normally — there is no Gatekeeper override to click through.

Terminals you open inside Sox.app already have sox on PATH — that is the session CLI (up, down, ls, …), not the app binary. soxterm is the Ghostty-engine CLI for power users (soxterm +list-fonts, +list-themes, +show-config).

To use sox from Terminal.app or another emulator, link the same binary:

ln -sf /Applications/Sox.app/Contents/Resources/bin/sox /usr/local/bin/sox

Start sessions with the CLI; Sox.app presents and reconnects their shells. See the CLI reference.

Install on a Linux host

To run sox pair on a Linux host, install the host command on PATH first. Download that release’s soxd-vX.Y.Z-linux-x86_64.tar.gz or soxd-vX.Y.Z-linux-aarch64.tar.gz archive from GitHub Releases, matching the host’s architecture. On the host, replace X.Y.Z with the downloaded version:

mkdir -p "$HOME/.local/bin"
tar -xzf soxd-vX.Y.Z-linux-x86_64.tar.gz -C "$HOME/.local/bin" sox soxd
export PATH="$HOME/.local/bin:$PATH"
sox pair

Use the aarch64 archive in that command on an ARM64 host. Add the PATH line to the shell’s startup file to keep it available in later terminals. The archive includes sox and a soxd compatibility link for one release. The installed sox must be outside {sox_home}/bin (normally ~/.sox/bin): every Sox.app deploy removes {sox_home}/bin/sox. Deploying the backend alone does not install the command on PATH.

Your first session

From a terminal (including one inside Sox), run:

sox up my-host

Starting a remote session establishes the SSH connection, deploys the remote sox binary, opens an RPC tunnel, and opens terminal windows bound to that host. With no host argument it targets your local machine and skips SSH entirely, which is a good way to try the interface before pointing it at a server.

If Sox already manages that host, sox up reconnects rather than failing. To reattach kept shells from the app, choose Reopen under that session in Sessions. Tearing down is sox down, or Stop Session in the menu.

The first start against a new host deploys the daemon. Existing sox.toml files are ignored. Later starts against the same host reconnect and are much faster.

Your shells outlive the app

Remote shells run on the remote host, not inside the app. Quitting Sox, closing a window, or losing the network detaches from a shell — it does not kill it. Reopening reattaches and restores what was on screen, including scrollback.

This is the single most important thing to internalise, because it changes what closing a window means: nothing is lost, and a long build keeps running while your laptop sleeps. Sessions and persistence covers the details, including what to do when a pane fails to reconnect.

Running more than one agent

Press ⌘I to open the Command Center: one roster of every shell Sox knows about, across every host, sorted by which one needs you. Shells appear there with no setup.

Agent state — blocked on a permission prompt, finished, erroring — is reported by a plugin that runs inside the agent, so it is one install per harness and per host. Claude Code, Codex, Grok, and pi are supported; Agent sessions is the procedure.

Updates

Sox updates itself. Use Check for Updates… in the Sox menu; a build knows which channel it came from and polls that feed on its own.

Switching channels is a download, not a setting: install Sox (tip) to move onto tip, or Sox (stable) to move back. An installed build never crosses channels on its own.