Run AI coding agents on a remote machine over SSH

How it works

Baton keeps the workspace list, terminal rendering, and settings on your computer. The remote machine holds the repository and runs everything that touches the code: agents, shells, builds, tests, and Git. Baton connects with your system's ssh, so the hosts, keys, and jump hosts in ~/.ssh/config work as they do in your terminal.

Requirements

Baton itself can run on macOS, Windows, or Linux. On Windows it uses the built-in OpenSSH client or WSL, and Local copies aren't available.

Connect a machine

1. Make sure SSH works.

   From a terminal on your computer, run ssh you@host. Load your key into ssh-agent if it has a passphrase.

2. Add the machine.

   Open Settings → SSH Hosts → Connect machine and enter a name, host or IP address, user, and port. Advanced SSH options holds the identity file, extra ssh arguments, saved port forwards, and the remote Baton path (~/.baton by default, fixed once connected).

3. Check the machine.

   Check machine tests SSH access, Git and your Git identity, tmux, the required utilities, and rsync. Password, passphrase, and host key prompts appear in Baton.

4. Set it up.

   Set up machine creates Baton's folders under the remote Baton path and installs small helper scripts. If the remote machine has no Git name and email, Baton copies yours.

5. Enable agent integrations.

   On Remote machine ready, click Enable next to Notifications and MCP Server for each agent you use, then Finish setup. For Codex, run /hooks once on the remote machine to approve Baton's hooks.

6. Create a workspace.

   The new machine becomes the default environment in the New Workspace dialog. Pick a project and branch. The first workspace clones the repository on the remote machine, and later ones reuse that clone.

Working in an SSH workspace

Agents keep running

Every terminal runs in a tmux session on the remote machine. If your connection drops, your laptop sleeps, or you quit Baton, the agents carry on. Select the workspace to reattach. To reattach a single pane without stopping it, use More → Reconnect SSH Session in the pane's context menu.

Join from your own terminal

Hover the host pill in a pane header and choose Copy tmux attach command. It joins the same session from any terminal without detaching Baton.

Files and Git

Browse, edit, and save remote files in the file tree and editor, and review diffs as usual. Commit, pull, push, merge, rebase, and switch branches from the toolbar. Git runs on the remote machine, and the sidebar's change counts update as files change.

Setup steps and links

Workspace setup steps run on the remote machine. The Upload .env to SSH recipe copies a local .env into each new workspace. Linked workspaces work between workspaces on the same machine.

Baton CLI and port forwards

The baton command is on the PATH in SSH terminals, so agents can open tabs, start workspaces, and open previews. For services you always want forwarded, add port forwards in either direction under the host's Advanced SSH options. They bind to 127.0.0.1 only.

Notifications, MCP, and previews

While a workspace is connected, Baton keeps a data tunnel open to the remote machine. It's an SSH reverse forward from a port on the remote loopback interface (in the 62000–63999 range) back to Baton.

• Notifications: agent hooks run baton notify on the remote machine. Finished turns, input requests, and errors come back through the tunnel, and every computer connected to that host shows them.
• MCP: agents start Baton's MCP server through the remote baton mcp helper. They can set workspace titles and start new workspaces on the same machine.
• Git status: the Remote Companion watches the worktree for changes and pushes status to Baton, so the sidebar stays current without polling over SSH.
• Browser previews: when you open the preview panel, Baton looks for localhost URLs in the workspace's terminal output and forwards that port over SSH to 127.0.0.1 on your computer, keeping the same port number when it's free. If it finds more than one, use Pick URL from terminals or Forward Remote Port.

Integrations are per machine. Change them in Settings → Integrations & MCP on the tab named after the host. Baton shows Update available there when a newer hook is ready.

Use it from several computers

Start an agent on your desktop, then check on it from your laptop. Each SSH workspace keeps a small manifest on the host, and every computer with Sync with other devices turned on (the default) picks up the others' workspaces.

• What syncs: new workspaces, agent tabs, renames, and archiving or stashing. Tab layouts stay per computer.
• Attaching: opening a synced workspace attaches to the agents still running in tmux instead of starting new ones. The computer that attaches takes over the session from the other one.
• Alerts everywhere: when an agent finishes, needs input, or fails, every computer connected to the host shows it.
• While you're away: agents can start new workspaces even when no computer is connected. The next one to connect adds them.
• Deleting: deleting a workspace removes it from the other computers too. If its files disappear from the host some other way, it shows as Missing from host.

To choose by hand instead, open the host's Workspaces panel in Settings → SSH Hosts, turn off Sync with other devices, and use Add here on the workspaces you want.

Local copy

Some work needs the files on your own disk: building a desktop or mobile app, running a simulator, or a tool that only works locally. For that, Baton can keep a Local copy of an SSH workspace.

• One way, remote to local. Baton syncs changes from the remote machine with rsync. Edits you make in the Local copy aren't sent back and can be overwritten.
• Your local files stay. Gitignored files such as node_modules, .env, caches, and build output stay on your computer and aren't touched by syncs.
• Created when needed. A Local copy appears the first time something uses it, such as a New Local copy terminal, a setup step, or a Terminal Command. Archiving the workspace deletes it.
• Terminal Commands. The first time you run one in a project, Baton asks where Terminal Commands should run: on the remote machine or on this computer. Change it later under Settings → Projects → SSH terminal commands.

Security

Only SSH crosses the network

Baton opens no ports on either machine. The data tunnel's remote end listens on 127.0.0.1 on the remote machine and leads to a gateway on your computer's loopback interface. The gateway labels each request with the host it came from before passing it to Baton.

Use a machine you trust

Anything on the remote machine that can reach its loopback port can send requests to Baton for that host, including notifications and MCP calls. Anyone who can act as your remote user can also read the code and Baton's helper files. Use a machine and account you control, and avoid hosts shared with people you don't trust.

SSH agent forwarding

Forward SSH agent is on by default. Your private keys stay on your computer, but while you're connected, any process running as your remote user can ask your ssh-agent to sign with them. Turn it off in the host's settings for machines you don't fully trust, and give the remote machine its own, narrowly scoped Git credentials instead.

Forwarded keys go away when the connection drops. Agents keep running in tmux, but they can't push until you reconnect, unless the remote machine has its own credentials.

Removing a machine

When you delete a host, Delete all Baton data from this host is on by default. It's off when other computers may still be using workspaces there.

Troubleshooting

Need an SSH setup Baton doesn't support yet? Get in touch.