DocsGuides

Remote Machines

Connect to your dev boxes over SSH and run agents on them with full source control, terminals, and worktrees

Overview#

Add remote machines over SSH and run agents on your dev boxes — with full source control, terminals, and worktrees, just like a local workspace. Sessions are persistent: you can close your Mac or restart Agentastic and the agents keep running on the remote host in the background.

Adding a Remote#

Open the Add Remote Workspace sheet one of two ways:

  • File → Add Remote… (Cmd+Shift+E)
  • The Open Remote button on the Welcome window

Then:

  1. In the SSH Host field, type a host like user@host, or start typing to search your saved hosts
  2. Pick a host from the list (or finish typing a new user@host)
  3. Connect — Agentastic opens a remote workspace and drops you into the host's project

The Host Picker#

The picker is populated from your SSH config (~/.ssh/config), so machines you already use from the command line show up automatically. The search box filters by host alias and hostname as you type.

Include directives are expanded#

If your ~/.ssh/config pulls in other files with Include directives — a common setup when tools like Cursor, 1Password, or your company's tooling manage hosts in separate files — Agentastic expands those includes (recursively) and lists those hosts too. If a machine was missing from the picker before, this is usually why it now appears.

ssh-config
# ~/.ssh/config Include ~/.ssh/config.d/* Include ~/.orbstack/ssh/config Host dev-box HostName 10.0.0.5 User adel

Working on a Remote#

Once connected, a remote workspace behaves like a local one:

  • Terminals run on the remote host and are kept across app restarts
  • Source control (status, diffs, commit, push) operates on the remote checkout
  • Worktrees / agents are created and switched on the remote machine
  • Agent Home launches agents that run on the host, so they keep going after you disconnect

Port Forwarding#

Keep dev-server tunnels open right from the app — no more running ssh -L by hand. This is handy for previewing a web app or service running on the remote machine in your local browser.

  1. Open the remote sessions dialog and switch to the Tunnels tab.
  2. Add a forward by setting a local port, remote host (usually 127.0.0.1), and remote port — for example, local 3100 → remote 127.0.0.1:3100.
  3. Start the tunnel, then use Open URL to launch it or Copy URL to grab the address.

Tunnels can auto-start whenever the remote workspace reconnects, and they're saved with the workspace so they come back across reopen and reconnect. You can start, stop, or delete each one from the Tunnels tab.

Reconnecting & Offline Mode#

  • Remote workspaces restore on launch. If the host is unreachable, the workspace opens in offline mode instead of blocking.
  • Reconnect with a single click when the machine comes back.
  • Because sessions persist on the host, agents that were running are still there when you reconnect.

Tips#

  • Set up key-based auth in ~/.ssh/config (an IdentityFile per host) so connecting doesn't prompt for a password.
  • Group machine definitions into Include-d files — Agentastic will pick them up, and so will the ssh CLI.
  • For agents that should outlive your laptop entirely, see also Cloud Agents launched from Agent Home.