# Run agents on a remote machine

Run agents on another computer while working from your local editor.

## 1. Connect to your project over SSH

Install **Remote - SSH** in VS Code and confirm that you can log in to the host from a terminal:

```shell
ssh user@hostname
```

Run **Remote-SSH: Connect to Host…** from the Command Palette. Connect to the host, then open the project folder on that machine. Check the editor’s status bar to confirm the host.

[Remote SSH setup and host requirements ↗](https://code.visualstudio.com/docs/remote/ssh)

## 2. Prepare the remote environment

In the SSH-connected window, open the Extensions view, find Facade Code, and install it on the SSH host. The Window Component stays on your computer and connects the remote project to your other Facade projects.

In the remote integrated terminal, install the CLI you want to use and complete its login or provider setup. Confirm that it can answer a request there.

| Your computer | Remote machine |
| --- | --- |
| Editor interface and SSH connection | Facade’s project extension, agent CLI, project files, builds, and tests |

The remote agent uses that machine’s tools and credentials. A CLI installed only on your computer will not be available to a remote agent.

## 3. Start the remote agent

Open Facade in the connected project, choose **New Agent**, and select the CLI. Check that the selected location is the remote project folder.

```text
Tell me which operating system and project directory you are working in, and how to run this project’s checks.
```

Confirm that the reply describes the expected environment and path. The agent runs commands and changes files on that machine.

## Edit settings where the agent runs

With the remote folder open, choose **Open Settings → Facade: Home → Edit in facade.json**. If your remote window opens Settings as JSON, **Open Settings** goes straight to facade.json. See [Agent settings](https://facadecode.com/docs/settings/) for the fields.

Prepare API keys, executable paths, and other environment variables on the remote machine; your local environment does not carry over.

## Connect local and remote work

Keep the local project and SSH connection open. Agents can discover and message one another through Facade when their access settings allow it.

```text
Use Facade to ask the remote agent which project it is working in and what checks are available there.
```

See [Approvals and agent access](https://facadecode.com/docs/permissions/) if an agent cannot find another. To follow several feature agents, local or remote, from one conversation, use the [Facade pattern](https://facadecode.com/docs/collaboration/phone-led-team/).

Each machine has its own project files. Check out the same commit on each machine before comparing test results across operating systems.