Grants & Consent
Pairing establishes trust between two instances (see Pairing machines). It does not, by itself, let a peer see or touch any terminal. Two separate mechanisms control what a paired machine can actually do, and it's worth being precise about the difference between them.
Per-terminal View / Control grants
For each of your terminals, you can grant a specific peer one of two levels of access:
| Grant | What it allows |
|---|---|
| View | Read the terminal's screen and output. The peer can watch, but not type. |
| Control | Everything View allows, plus sending input, running commands, and closing the terminal. |
Grants are per-terminal, not blanket — pairing a machine doesn't expose every terminal to it. You choose which terminals a given peer can see or drive, and at which level, from the Grants control next to that peer in Settings → Peers.
Per-peer "Allow fleet commands" consent
Separately, each peer has one toggle: "Allow fleet commands (create & run terminals)."
- Default: OFF. A newly paired machine cannot spawn anything on you until you turn this on for it.
- Revocable at any time, and the check is live on every request — turning it off blocks the next fleet command immediately; it does not wait for anything currently running to finish, and it does not retroactively cancel one already in flight.
- This toggle governs one thing specifically: whether a machine-targeted or OS-targeted Fleet request from that peer is allowed to spawn a brand-new terminal on your machine.
The distinction that matters
It's easy to conflate "the peer can control a terminal" with "the peer can run commands on me." They're not the same permission:
| Mechanism | Governs | Scope | Default |
|---|---|---|---|
| Control grant | Running a command in an existing terminal, by terminalId | One specific terminal | Off until explicitly granted |
| Allow fleet commands | Spawning a new terminal via a machineId- or targetOS-targeted request | The whole machine | OFF |
In other words:
- A request that names an exact
terminalIdnever spawns anything — it runs in a terminal you already granted Control on. The fleet-exec toggle is irrelevant to it. - A request that only names a
machineIdortargetOShas no existing terminal to run in, so it needs a new one — that's gated by Allow fleet commands, independent of any per-terminal grant.
This split lets you, for example, let a trusted peer drive one long-lived build terminal you've explicitly granted Control on, without also giving it the standing ability to spin up arbitrary new terminals on your machine whenever it feels like it.
Neither grant nor consent triggers an interactive "Allow this?" prompt at request time — that would stall an unattended agent. The controls above are the entire gate: set them in advance, in Settings → Peers, for what you're comfortable allowing. See Fleet commands for the other compensating controls (audit logging, the visible labeled terminal, auto-revoke on close).
Next steps
- Fleet commands — how these grants and this consent are actually checked when a command routes across machines.
- Fleet API & MCP — the error you get back when a grant or consent is missing.