# Making Every Machine Feel as One

An agent should use every machine it can reach as if it were one computer. A nanocode brain keeps the model loop, the journal, and subagents in one process, and hands run its code on a laptop, a build server, or a browser tab.

**A sandbox per session rents one machine for the whole turn, and a turn mostly waits on the model.** A hand is busy only while a call runs on it. So one turn can use zero machines, or five, and pay only for the calls.

## TL;DR

* **One cell, every machine:** a Code Mode cell runs tool calls on several hands at once and returns one result to the model.
* **4 ms across machines:** a laptop ran nc as the brain, and a command from it ran in a browser tab hand in 4 ms.
* **3 s to attach:** the tab joined as a hand 3 s after the page loaded.
* **One command:** a single installer line puts nc on any machine and dials it into a demo session.
* **No open ports:** either side dials the other through a relay, or over an SSH reverse forward.
* **No keys on the machine:** provider and API keys stay with the brain.

Measured on 2026-11-09.

## Brains and Hands

* **Brain:** calls the model, keeps the session journal, and runs subagents. It can be a Durable Object, a Function, a browser tab, or nc.
* **Hand:** a process on another machine that runs cells and tools for a brain, with that machine's files, shell, and network.

```mermaid
flowchart LR
  brain[Brain: model, journal, subagents] <-->|WebSocket| relay[Relay]
  relay <--> laptop[Hand: laptop]
  relay <--> tab[Hand: browser tab]
  brain <-->|WebSocket| server[Hand: build server]
```

The protocol is the same in both directions. A brain that cannot accept sockets, such as a Function or a tab, reaches its hands through a relay on nanocode.xyz.

## One Computer

A hand appears to the model as a name, and the `hands` tool lists what is attached. A call whose arguments include that name runs there. **One cell can check git status on a laptop and run a test suite on a build server, in parallel.**

* **Replace:** the hand runs the session's cells, so the agent works on that machine as if it ran there.
* **Alongside:** cells stay with the brain, and only the calls that name the hand run on it.

## Cells Across Hands

**Code Mode is what makes many machines feel like one.** A cell runs on one machine, and any tool call in it runs on another hand when its arguments include `hand`. So one cell fans work out to every machine with Promise.all and returns only the answer:

```js
// 1. List the attached machines
const { hands } = await tools.hands();

// 2. Check the laptop and run the tests on the build server, in parallel
const [status, tests] = await Promise.all([
  tools.Bash({ command: "git status --short", hand: "laptop" }),
  tools.Bash({ command: "cargo test --workspace 2>&1 | tail -3", hand: "build-box" }),
]);

// 3. Ask every machine for its load, in one line each
const load = await Promise.all(hands.map((hand) => tools.Bash({ command: "uptime", hand })));

// 4. Only this summary enters the model's context
text(JSON.stringify({ hands, dirty: status.stdout, tests: tests.stdout, load: load.map((l) => l.stdout.trim()) }));
```

```mermaid
sequenceDiagram
  participant M as Model
  participant B as Brain, the cell
  participant L as Hand: laptop
  participant S as Hand: build-box
  M->>B: one exec call
  par
    B->>L: Bash git status
    B->>S: Bash cargo test
  end
  L-->>B: stdout
  S-->>B: stdout
  B-->>M: one line of JSON
```

* **One model call, many machines:** the model sees one exec call and one result, not a round trip per machine.
* **Calls without hand:** run where the cell runs.
* **A hand that is not attached:** the call fails without running anything, and nothing falls back to another machine.
* **Tools-only hands:** a browser tab or a phone runs no cells. A cell elsewhere calls its tools, such as location or clipboard, with `hand`.

## What It Costs

|                   | Sandbox per Session    | Hands                                          |
| ----------------- | ---------------------- | ---------------------------------------------- |
| Machine time      | The length of the turn | The length of the calls that name it           |
| Machines per turn | One                    | Zero or more                                   |
| Credentials on it | Provider and API keys  | None                                           |
| When it dies      | The turn is lost       | One call reports unknown, and the turn goes on |

## When Things Break

The journal rules from [Durable Nanocode](/experiments/durable-nanocode) hold across the network.

* **A dropped call:** a call that was running when its connection dropped reaches the model as an unknown outcome. Nothing runs it again.
* **A restarted brain:** it resumes the session and waits for its hands to dial back.
* **An absent hand:** on Cloudflare a turn that waits for one backs off its alarm, so waiting costs almost nothing.

## Tabs as Hands

[nc hand in a tab](/hand) makes a browser tab a hand. With "Run scripts here", cells run in the tab on the simulated shell over files in memory. With "Tools only", cells stay with the brain and call the tab's location, notifications, and clipboard behind the browser's own prompts.

We want to be clear about the limit: a tab's files live in its memory and disappear with it.

## Behind SSH

A hand on a private server needs no public port. The brain listens on a loopback port, and an SSH reverse forward maps the same port on the server to it. The hand dials its own loopback, SSH encrypts the link, and the hand redials if the forward drops.

## Try It Today

Open the [Cloudflare](https://nanocode.xyz/cloudflare/) or [Vercel](https://nanocode.xyz/vercel) demo, copy the command under Connect, and run it on your laptop. The agent in the page now works on your machine. Tell us what you attach on [GitHub](https://github.com/nanocodexyz).

- [Remote Hands](/docs/guides/remote-hands): Brains, hands, tokens, and the SSH recipe.

- [hand](/docs/api/rust/hand): Reference for hands in Rust.

- [nc hand in a tab](/hand): Make this browser tab a hand.