> ## Documentation Index > Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Remote machines > Reach a repository or dev stack on another box over SSH, or through ADE Relay when a direct connection is unavailable. 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 > [card] Code that lives elsewhere > > The repository and its dev stack are on another machine and you would rather not clone or sync it locally. > [card] Heavier compute > > Builds, tests, and agents run on a box with more cores, more RAM, or the right GPU. > [card] 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. > [!NOTE] > > 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](https://ade-app.dev/docs/getting-started/windows.md). ## 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. ```bash theme={null} ade shell start --machine windows --wait -- npm test # stream the output, exit with its code ade shell start --machine windows --no-sync -- git status # use the copy as it is ade shell clean --machine windows # delete this chat's copy there ``` 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. > [!NOTE] > > 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: ```bash theme={null} curl -fsSL https://ade-app.dev/install.sh | sh ade connect --headless ``` The machine then publishes itself to your account directory and is reachable from ADE desktop, [the web client](https://app.ade-app.dev), 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. > [card] [Connect a machine](https://ade-app.dev/docs/getting-started/connect-machine.md) > > Install the brain on a server and put it on your account. > [card] [Architecture](https://ade-app.dev/docs/architecture.md) > > How the control plane, runtime, and clients fit together. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.