Skip to main content
A remote machine lets you drive a repository that lives somewhere else — a Linux dev box, a beefy build server, a cloud VM — without copying the code to your laptop. ADE connects over SSH and runs the agents, builds, and tests on that box. Your desktop app stays local and stays in charge: it is the control plane, the remote is the workspace.

​
When to use it

Code that lives elsewhere

The repository and its dev stack are on another machine and you would rather not clone or sync it locally.

Heavier compute

Builds, tests, and agents run on a box with more cores, more RAM, or the right GPU.

The right environment

Services, databases, and toolchains are already set up on the remote and you want agents to run against them.

​
How it connects

ADE adds the remote over SSH using the same connection details you already use from a shell. The desktop spawns a lightweight ADE bridge on the far side and tunnels its control protocol back over the SSH channel — so lanes, chats, diffs, and PRs all behave exactly as they do locally, just backed by the remote’s filesystem and runtime.
1

Add the machine

Give ADE the SSH target for the remote box. ADE bootstraps its runtime there on first connect.
2

Pick a project

Choose the repository on the remote you want to work in. It becomes a normal ADE project, backed by the remote filesystem.
3

Work as usual

Create lanes, run agents, review diffs, and open PRs from the desktop. Everything executes on the remote.

​
The desktop still drives everything

Connecting a remote does not move ADE off your own machine. The desktop app remains the control plane: you compose prompts, approve diffs, and merge PRs locally, while the agent processes, builds, and tests live on the remote. The remote’s own GitHub, Linear, and provider credentials are used for work that happens there.
Remote machines run macOS, Linux, or Windows. A Windows desktop can drive them when it is running an installed release build — a locally packaged Windows build ships no macOS or Linux runtime payloads and will refuse. Windows targets must be Windows 10 22H2 or Windows 11 x64 with OpenSSH Server and PowerShell 5.1 or newer; WSL, ARM64, and Windows Server are not supported. See ADE on Windows.

​
Use another machine from the chat you are in

A chat can run a command or a simulator on another of your machines without a second chat or a new lane. Run the Windows tests, a build on a bigger Mac, or that Mac’s simulator, and the output comes back to the chat you are in.
The other machine keeps a hidden work copy for the chat: a git checkout at the chat’s commit, with the chat’s uncommitted changes applied. It is not a lane and never shows in Lanes.
  • Git moves the code. The chat’s commit must be pushed. Work done in the copy reaches the chat only by commit and push. A sync refuses while the copy holds work that is not pushed and names the files; --discard throws that work away.
  • The chat shows where it works. While a chat works on another machine, its header and card show that machine’s logo, with its commands and Stop. The terminal tool lists those commands.
  • Copies clean up after themselves: after a week unused, when the chat is deleted or archived, when the disk is low, with ade shell clean --machine, or from Settings › Machines, where each machine lists its Work from other machines with size and Delete.
Agents are told to ask you before they use another machine. The @machine mention in the composer offers three choices: run a command there, start a chat there, or move this chat there.

​
Pick where new work goes

Settings › Machines shows each machine’s live load and what it can run: CPU, free memory, disk, running builds, signed-in CLIs, Xcode and simulators, battery, and work copies. Each machine also has a New work preference: Prefer, Normal, Less often, or Manual only. The preference is saved to your account, so every machine and the phone read it. Least loaded in the new-lane and new-chat pickers uses both the load and the preference, and never picks a Manual only machine.

​
ADE Relay: the internet fallback

ADE Relay is how your phone, another Mac, or the web client reach a machine when they cannot connect directly. Relay uses ADE-hosted infrastructure, so both devices must be signed in to the same ADE account. ADE chooses the route for you:
  1. It first tries a direct connection, such as your local network or tailnet.
  2. If those routes are unavailable and both devices are signed in, it tries ADE Relay.
  3. If you are signed out, ADE tells you when Relay is the missing connection option.
You do not need Relay to use ADE on one Mac, and direct pairing works without an account when your devices can reach each other.
1

Sign in on your machine

Open ADE and sign in to your account.
2

Sign in on your other device

Use the same ADE account on your phone, another Mac, or the web client.
3

Choose your machine

Your account’s machines appear automatically. ADE tries the best available connection, including Relay when needed.
Relay is a transport, not cloud storage, and it does not store your ADE project state. Relay traffic is not end-to-end encrypted, so the Relay operator can read traffic while it passes through ADE-hosted infrastructure. Direct LAN and Tailscale connections do not pass through Relay.
If Relay is unavailable: confirm both devices are signed in to the same account, keep ADE running on the machine you want to reach, then open Connections and try again. ADE shows the route that failed and the next action to take. To avoid Relay entirely, connect over the same local network, Tailscale, or an SSH setup you configured yourself. Settings › Account › Connections shows the order clients try routes in (local network, then Tailscale, then ADE Relay) and a Tailscale setup checklist read from this computer. With Tailscale HTTPS set up, the web client reaches the computer over your tailnet. Each computer under Your computers has its own ADE Relay switch; turning it off keeps that computer off the relay, and ADE warns you first about what stops working.

​
Or install the brain on the box instead

SSH remotes are driven by your desktop: it bootstraps the runtime on the far side and tunnels the connection. The alternative is to install ADE’s brain on that machine directly and connect it to your account:
The machine then publishes itself to your account directory and is reachable from ADE desktop, the web client, and iOS — with no SSH session and no desktop app doing the bootstrapping. This is the better fit for a long-lived server you want available from everywhere, rather than a box you occasionally attach to.

Connect a machine

Install the brain on a server and put it on your account.

Architecture

How the control plane, runtime, and clients fit together.