Run AI coding agents on remote machines over SSH

Keep Baton's interface on your computer while agents, terminals, Git operations, and worktrees run on a remote development machine.

SSH workspaces are useful when your code or compute belongs somewhere else: a powerful Linux workstation, a cloud VM, a machine inside your company network, or a Mac build host. Baton connects with standard SSH. You do not install or run a second copy of Baton remotely.

The repository stays remote. Baton creates and manages a bare repository plus one worktree per workspace under the remote Baton path. Only an optional one-way local mirror copies working files back.

How it works

Baton owns the workspace list and terminal interface locally. The remote host owns the checkout and runs the agent process. A small set of SSH connections joins the two sides.

Baton SSH workspace architecture Terminals travel to the remote host over SSH. Notifications, MCP calls, and Git status return through a host-scoped reverse tunnel. Previews and mirrors use separate paths. Your computer Remote POSIX host Baton desktop app Workspace UI · terminal PTYs · metadata Authenticated local gateway Approved HTTP → Baton loopback Optional local mirror One-way working-file copy via rsync Agent inside managed tmux Claude · Codex · Gemini · OpenCode Remote loopback port 127.0.0.1:62xxx Remote Baton data repos/<project>.git worktrees/<project>/<branch> helpers/baton Source, Git, builds, and tools live here SSH terminal input + output reverse tunnel token required local forward web previews rsync optional copy All cross-machine paths use SSH No Baton server is exposed to the LAN or public internet
The reverse tunnel carries small HTTP requests for notifications, MCP calls, and workspace status. Terminal output uses the interactive SSH session; source files remain remote.
Your computer Remote host
Baton app, workspace metadata, layouts, and settings Bare Git repositories and per-branch worktrees
Terminal rendering, notifications, and MCP server Agent CLIs, shells, builds, tests, and Git commands
Optional working-file mirror Small Baton-managed hooks, token, and tmux configuration

Requirements

Remote operating systemLinux is recommended. macOS is supported. Native Windows is not supported.
Remote toolsA POSIX shell, Git, and standard Unix tools. Install tmux for resilient sessions.
SSH accessA host, user, and authentication method that already work with your SSH client.
Optional toolscurl or wget for hooks; rsync on both machines for local mirror mode.

Baton supports SSH ports, a local identity file, agent forwarding, and extra SSH arguments for setups such as jump hosts. The remote user must be able to write to the configured Baton path, which defaults to ~/.baton.

tmux is strongly recommended. Without it, terminals work, but a dropped SSH connection ends the remote process. With tmux installed, Baton can reconnect to the same managed terminal session.

Set up a remote host

  1. Open Settings → SSH → Hosts → Add Host.

    Enter a name, hostname or IP address, user, and SSH port.

  2. Choose how SSH authenticates.

    Use your SSH configuration, select an identity file, or add advanced SSH arguments. Baton shows password, passphrase, and host-key prompts when needed.

  3. Configure the host.

    Baton verifies the connection, Git, tmux, writable folders, and its notification helper before saving.

  4. Enable agent integrations.

    In Agent integrations, enable Notifications and MCP for each agent you plan to run.

  5. Create a workspace on the SSH host.

    Choose the project and branch in New Workspace, then select the SSH host as the environment.

You can set an SSH host as an agent preset's default under Settings → SSH → Defaults & rules. Per-project settings can override the default remote runtime mode.

Notifications, MCP, status, and previews

Agent notifications

Baton installs small hooks for Claude Code, Codex CLI, Gemini CLI, and OpenCode when you enable the integration. Turn completion, prompt submission, and input-required events cross the host-scoped reverse tunnel to update tabs and trigger local notifications and sounds.

MCP tools

The same tunnel exposes Baton's MCP endpoint to enabled remote agents. Agents can set the workspace title or spawn another agent workspace without exposing Baton's local HTTP service to the network. The gateway attaches the configured SSH host identity before forwarding requests.

Git status

The lightweight Remote Companion sends branch and working-tree status through the data tunnel. Git operations still execute remotely; the tunnel returns status data, not the repository.

Browser previews

When an agent starts a web server on remote localhost, Baton creates a separate local SSH forward for its preview panel. The local address binds to 127.0.0.1 on a newly allocated port instead of exposing the remote server publicly.

Remote only vs local mirror

Mode Behavior Best for
Remote only Agents, Terminal Commands, files, and Git stay remote. The simplest setup and a clear remote source of truth.
Remote agents + local mirror Agents and Git stay remote. Baton maintains a one-way rsync copy for Terminal Commands configured to run locally and for local terminals. Tools that require a local path while compute remains remote.

The mirror is not bidirectional. Treat it as disposable. Local edits are not pushed back and may be replaced by the next sync. This mode requires rsync on both machines and is not supported on native Windows.

Security and troubleshooting

What the tunnel exposes

The remote end binds to 127.0.0.1 on the SSH host. The local gateway also binds to loopback and checks a randomly generated, host-specific bearer token before forwarding a request to Baton. Neither endpoint is intentionally reachable from other machines.

Anyone who can act as your remote user can still inspect that user's processes and files, including Baton's remote helper data. Treat the remote account as trusted.

SSH agent forwarding

Forwarding is convenient for private Git repositories. Keys remain local, but a process running as your remote user can ask the forwarded agent to sign with loaded keys while the connection is active. Enable it only for hosts you trust.

Forwarded keys become unavailable when the SSH connection ends. Agents kept running by tmux can continue working, but cannot use those keys for Git until Baton reconnects. If unattended Git operations must always remain available to agents, configure persistent, appropriately scoped Git credentials for the remote user. This is optional if agents do not need to perform Git operations while disconnected.

Common problems

Need help with an SSH setup Baton should support? Get in touch.