Devices, Peers and Remote Control

Robota sessions can reach each other. Sessions of yours running on the same machine find each other automatically; with the device mesh turned on, sessions on your other computers join them. From a session you can then message another one, send it a file, or hand the whole conversation over to it. Separately, remote control pairs a browser page with one session so you can co-drive it from another device, such as a phone.

The device mesh links only your own devices: one identity, created once, certifies each computer you enrol. It is not a way to share a session with another person.

Prerequisites

• The robota CLI installed on every computer involved — see Getting Started.
• An interactive terminal. /devices, /peers, /handoff and /remote-control are commands for the person at the host terminal: the model cannot run them, and every secret (recovery phrase, enrollment code) is typed and shown only on that terminal.
• For enrolling devices and for remote control: a signaling relay you run yourself (apps/remote-signaling in this repository), set as transports.webrtc.options.relayUrl in ~/.robota/settings.json.
• For remote control only: the browser client page hosted somewhere you control (the /remote route of apps/agent-web), set as transports.webrtc.options.clientUrl.

All transports.* settings in this guide are read from ~/.robota/settings.json only. A project's settings cannot turn on the mesh or remote control.

Talk to another session on this machine

Start two robota sessions. In either one:

/peers

/peers lists the other live sessions with their id, name, status (working, needs input, idle) and how their workspace relates to yours (same worktree, same repo, different repo, or unknown), followed by any linked devices. Then:

/peers send <session-id> Can you run the integration tests on your branch?
/peers send-file <session-id> ./report.md

The receiving session treats the message as a turn from an untrusted third party (see Security model). Its model answers only through the peer_reply tool, which asks its operator by default, showing the full text and the destination. A file you send is offered to the receiving operator, who must accept it; it is kept aside and never run.

Link your computers into a device mesh

1. On your first computer only, create your device identity:

   /devices init laptop

   Copy

   The terminal shows a 24-word recovery phrase once and asks you to retype three of its words, then offers an optional passphrase. Write the phrase down and keep it offline: with the passphrase, it is the only way to recover the identity. Do not run init on your other computers — there it creates a separate identity that can never link to the first.

2. On each computer, turn the mesh on and point at your relay in ~/.robota/settings.json:

   {
     "transports": {
       "mesh": { "enabled": true },
       "webrtc": { "options": { "relayUrl": "wss://relay.example.com" } }
     }
   }

   Copy

   Restart robota. The mesh opens when an interactive session starts; print and serve runs never open it.

3. Enrol the second computer. On the first one:

   /devices add

   Copy

   It shows a one-time code, valid once for five minutes. On the new computer:

   /devices join desktop

   Copy

   and type the code at the prompt — never as an argument, where shell history would keep it. Both terminals then show the same six digits; compare them and confirm on both. Only then is the new device certified.

4. Check the result on either computer:

   /devices

   Copy

   It lists your devices, which one holds the signing key, certificate expiry, and the mesh status: whether it is on, how this device finds the others, and which are linked now.

Linked devices then appear in /peers and /handoff, and /peers send and /peers send-file take a device id in place of a session id.

Hand a conversation to another session or machine

/handoff
/handoff <session-or-device-id>

With no argument, /handoff lists where the conversation can go. With a target, it first shows what does not travel — uncommitted changes in the working tree and running processes stay on this machine, and the destination uses its own provider credential — and asks you to confirm. The receiving operator must also accept. The conversation arrives saved, not started; resume it there with robota --resume <id>. This session ends once the destination confirms it saved the session; until then the session stays here. If the confirmation is lost, running /handoff to the same target again resends the same transfer, which is not saved twice.

Co-drive a session from a browser

Set both settings in ~/.robota/settings.json:

{
  "transports": {
    "webrtc": {
      "options": {
        "relayUrl": "wss://relay.example.com",
        "clientUrl": "https://robota.example.com/remote"
      }
    }
  }
}

Then, in the session:

/remote-control

It prints a scannable QR code and a pairing link. Open the link on the other device. The browser waits until you approve the connection on the host terminal; every connection is put to you there, including one from a device that paired before, and without an interactive terminal it is refused. Once approved, the browser sends prompts and answers the session's questions alongside the host terminal.

A paired browser is remembered in ~/.robota/remote-trusted-devices.json so it can reconnect without a new pairing link (still with your approval each time). List and remove them with /remote-control devices and /remote-control revoke <device-id>. /remote-control stop ends remote control.

Reference

Slash commands

A connected browser may run /remote-control status and stop; enable and revoke are refused from it, and its status never shows the pairing link. /devices refuses anything but the host terminal.

The model has two related tools: peer_reply, offered only in a turn a peer's message started, and peer_send_file, which asks you on every call (no permission mode, rule or remembered answer approves it), reaches only files inside the workspace that do not look like secrets, and is not offered in a peer's turn.

Settings

All keys live in ~/.robota/settings.json.

A malformed mesh setting stops the mesh with an error naming the setting; nothing is partly applied. The mesh options are checked only while enabled is true. With the defaults, finding your devices beyond the local network uses public infrastructure (the DHT and public Nostr relays); set dht to false and pkarrRelays and nostrRelays to [] to rely only on the local network and your own relay.

Files and locations

The keychain is used through the optional @napi-rs/keyring package (macOS Keychain, Windows Credential Manager, Linux Secret Service); where no keychain works, keys go to an owner-only file under ~/.robota/credentials.

Security model

• A peer message carries no authority. It becomes a turn under this session's own permission rules and mode, exactly like the session's own work — so it can still lead to tool calls those rules allow. The model is told, from the message's verified origin and never from its text, that the message comes from a peer and not from you. A message expands no @path references. Each sender is limited to 6 messages a minute and 30 an hour.
• Files are data. A received file is written without execute permission, never opened on arrival, and reaches the model only if something later reads it through the session's ordinary tools. The conversation is told only its name, size and SHA-256. Transfers are capped at 32 MiB and kept only when the whole content matches the offered hash.
• The receiving operator decides. Each incoming file and each incoming hand-off needs a yes on that machine's terminal every time, even when the capability is allowed; with no terminal the answer is no. observe and drive ask once per connection; delegate asks per request.
• Credentials never travel. A hand-off does not carry provider credentials; the destination uses its own.
• Enrollment cannot be hijacked by the relay. The new device proves the one-time code over the connection's DTLS fingerprints before anything else crosses, and the six digits both operators compare cannot be chosen by someone who only saw the code. The relay only forwards connection setup and never sees session content.
• The recovery phrase is shown once and never stored. Lose it (and its passphrase) and the identity cannot be recovered; revoke the lost device from one that holds the signing key instead.
• Remote control is approved per connection at the host terminal, a returning trusted browser included.

Limitations

• The mesh links one user's devices only.
• Only one session per computer opens the mesh at a time; /devices in another session says so and it links nothing.
• The mesh opens only in interactive sessions, not in print mode, --serve or the daemon.
• Enrollment and anything touching the recovery phrase need an interactive terminal.
• An enrollment code works once, for five minutes, and stops working after too many failed attempts.
• /remote-control has no built-in relay or browser page: without relayUrl and clientUrl it refuses to start.
• An interrupted file transfer is discarded; there is no resume.

Troubleshooting

Related

• Sessions, background sessions and the daemon
• MCP and external events
• CLI reference
• Permissions and hooks — the rules a peer's turn runs under
• @robota-sdk/agent-interface-session-mobility SPEC — how peer messages and hand-offs carry (no) authority
• @robota-sdk/agent-remote-pairing — device identity, enrollment and pairing
• @robota-sdk/agent-transport-webrtc — the WebRTC transport and device mesh
• Signaling relay and browser client deployment