---
url: https://docs.mochiexec.io/guides/remote-machines.md
description: >-
  Watch runs and logs from a dev box or VM where your coding agents work, from
  the desktop app, over SSH.
---

# Remote Machines

If your coding agents work on another machine, such as a cloud VM or a dev box under your
desk, the desktop app can watch what they run there: each run, the agent that started it,
how it ended, and its output.

Watching is read-only. The app never starts, stops or changes anything on a remote machine.

## What you need

* Mochi installed on the remote machine. The [installer](/getting-started/installation)
  puts it in `~/.mochi/bin`, which the app finds even when it isn't on your `PATH`.
* `ssh` access from your computer that doesn't prompt. Run `ssh <host>` once in a terminal
  to accept the host key, and use a key held by your SSH agent, or one without a passphrase.

The remote machine doesn't need its own license to be watched. Nothing on it listens on a
port: the app opens an SSH session and Mochi answers over it for as long as the session
lasts.

## Add a machine

Open **Settings → Remote machines** and choose **Add machine**. Enter the host as you would
type it after `ssh`: an alias from `~/.ssh/config`, or `user@host`. A name is optional.

The app connects right away. Each machine shows whether it's connected, the Mochi version
there, and when it last synced. If it can't connect, it says why and keeps retrying.

## Watch runs

Runs from every machine appear together on the **Runs** page. A **Machine** column says
where each ran, and the **Machine** filter narrows to one. Open a remote run to read its
output. A run that's still going keeps updating.

**Notify on failure** is on for a new machine: a run that fails there raises a notification,
in the app and from your system when Mochi is in the background. Turn it off per machine in
Settings.

If a machine goes offline, its runs stay visible as of the last sync, and it catches up when
it's back.

## Agents in a container or sandbox

The same works for an agent sandboxed in a container or VM, as long as you can `ssh` into
it. The agent runs Mochi inside the sandbox as usual, and the app watches from outside.

The sandbox needs Mochi installed and a way in over ssh. Some common setups:

* **A VM** (Lima, OrbStack machines, a cloud VM): these usually come with ssh. Add the host
  or alias you already use.
* **A dev container**: add an ssh server to the container (for example the `sshd` dev
  container feature) and an entry for it in `~/.ssh/config`.
* **GitHub Codespaces**: `gh codespace ssh --config >> ~/.ssh/config` writes an alias for
  each codespace, which you can add as the host.

A plain container with no ssh server can't be watched yet.

## Pro commands on the remote

To use Mochi's paid commands on the remote machine itself (AI, discovery, Mochi's MCP
tools), activate your license there. Choose **Activate license there…** from the machine's
menu in Settings, or run this on the machine:

```sh
mochi license set
```
