Skip to content

Computer use for the Pi coding agent — Windows apps, browsers and desktops through native UI trees, screenshots and real input.

docs: describe separate desktop limits

alexshpunt-clanker[bot]5dcc883264dc
diff --git a/README.md b/README.md
index a587f51..38c072b 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ If you have [Pi Agent IDE](https://github.com/alexshpunt/pi-agent-ide), looking
Computer use is built for an agent you trust with your desktop. In YOLO mode, the default, the agent can read and operate any window you point it at, read whole displays, attach to browsers that are already running and start programs by path. You get the most out of it this way.
-YOLO also means the agent can click and type anywhere you could. If a misclick would fuck up something you care about, switch to Safe mode with `/computer-mode safe`, or give the agent a sandbox. In Safe mode the agent only sees and touches windows it opened itself, and it can't read displays or start arbitrary programs. Neither mode isolates anything at the OS level; sandboxes and isolated sessions do that (see below).
+YOLO also means the agent can click and type anywhere you could. If a misclick would fuck up something you care about, switch to Safe mode with `/computer-mode safe`, or give the agent a sandbox. In Safe mode the agent only sees and touches windows it opened itself, and it can't read displays or start arbitrary programs. Safe mode is an ownership policy for this extension, not an OS security boundary. It does not restrict shell tools, files, networking, the clipboard, shared application state or what an authorized app can do.
### UI structure and screenshots
@@ -80,7 +80,7 @@ Input goes to a window by its address and targets an element by a ref from the l
- run a timeline of timed key, button, mouse and pen events, with raw relative mouse motion for pointer-locked apps and pen pressure and tilt;
- invoke, select or set values through UI Automation, and open menu items by their labels.
-What the agent sees as an element it presses through UI Automation in the background, so your pointer and focus stay put. What it sees only as pixels it clicks with the real mouse, and keys are real key presses: that input takes the front window, and it pauses whenever you touch the keyboard or mouse. Nothing is posted to windows as messages that an app could silently drop. To keep your desktop untouched, give the agent a sandbox or an isolated session.
+What the agent sees as an element it presses through UI Automation in the background, so your pointer and focus stay put. What it sees only as pixels it clicks with the real mouse, and keys are real key presses: that input takes the front window, and it pauses whenever you touch the keyboard or mouse. Nothing is posted to windows as messages that an app could silently drop. To keep foreground UI work off the human desktop, use a sandbox or an isolated session.
### Results and checks
@@ -99,10 +99,12 @@ The browser's toolbar, tabs and system dialogs are still ordinary windows, so th
### Sandboxes, sessions and other machines
-- Windows Sandbox gives the agent a throwaway Windows with its own driver. You choose which folders it can see.
-- An isolated agent session is a separate Windows session on the same machine with its own desktop, clipboard and input. Several agents can work at once, each with foreground input, and none of them touches your desktop.
+- Windows Sandbox gives the agent a disposable Windows desktop with networking enabled. The extension maps its runtime and control files read-only and a private output folder writable. Requested imports are read-only unless `writable` is set; `export` is writable.
+- Sandbox setup turns Smart App Control off only inside the disposable guest. The driver requires a bearer token, and the identity service requires mutual proof. Their traffic crosses temporary guest ports and host-loopback relays.
+- An isolated agent session is a temporary Windows user session on the same machine with its own desktop, clipboard and input. Several can run at once. Its network policy allows ingress and egress. Runtime and control files go into the temporary user's private workspace; user folders are not shared automatically.
+- In verified Windows checks, their foreground UI stayed off the human desktop. This is desktop separation, not hostile-code containment or protection from a local administrator.
- Browsers the agent opens use throwaway profiles that get deleted when the session closes.
-- Another Windows machine with WSL can be controlled over SSH with the same addresses. No ports are opened on either side.
+- Another Windows machine with WSL can be controlled over its existing SSH connection. Temporary loopback listeners and SSH forwards carry control traffic; the extension does not configure a new externally reachable host listener.
### Files, clipboard and recordings
diff --git a/docs/computer-resources.md b/docs/computer-resources.md
index fbdc675..b6fe954 100644
--- a/docs/computer-resources.md
+++ b/docs/computer-resources.md
@@ -63,10 +63,11 @@ Native locators run over the UI Automation tree:
## Work apart from the human's desktop
-- Windows Sandbox — its own focus, pointer, windows and clipboard; starts in 15–20 s; one at a time per machine, and the human's Windows session must be active. The guest has no Notepad.
-- Isolated session — invisible to the human; starts in 15–25 s; several can run at once. Its desktop is 640×480, some apps are missing by name (start them by `path`) and no files are shared.
-- Neither is a security boundary. Their addresses work like a machine's.
-- Another machine acts only there: a `url` such as `127.0.0.1` means that machine. Its Windows session must be active, or screenshots come back white.
+- Windows Sandbox — its own focus, pointer, windows and clipboard; starts in 15–20 s; one at a time per machine, and the human's Windows session must be active. Networking is enabled. The guest has no Notepad.
+- Sandbox runtime and control mappings are automatic and read-only; its private output mapping is writable. `sandbox.import` is read-only unless `writable` is true, and `sandbox.export` is writable.
+- Isolated session — invisible to the human; starts in 15–25 s; several can run at once. Its desktop is 640×480, some apps are missing by name (start them by `path`), and no user folders are shared automatically. Its network policy allows ingress and egress.
+- Both use temporary control channels. Sandbox requires a driver bearer token and mutual identity proof; MXC reverse channels mutually prove their roles before forwarding application bytes. Their foreground UI stayed off the human desktop in verified Windows checks. Neither is qualified as hostile-code containment or protection from a local administrator.
+- Another machine acts only there: a `url` such as `127.0.0.1` means that machine. Its Windows session must be active, or screenshots come back white. Remote control uses the existing SSH connection and temporary loopback forwards.
## Files and recording
diff --git a/docs/setup.md b/docs/setup.md
index 45c3244..4b95be0 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -26,6 +26,16 @@ Safe hides outside-session windows from discovery and denies their old reference
Switching cannot undo input already dispatched under YOLO. Pending work checks the current policy before dispatch; if the mode changes during a read or input, foreign returned UI state is withheld. Previously received YOLO observations remain in conversation history. Safe does not constrain shell tools, files, network, clipboard, shared app state, or what an authorized app can do.
+## Separate desktops and their limits
+
+Windows Sandbox and MXC isolated sessions keep foreground UI on a desktop separate from the human's desktop. Verified Windows checks established that separation for ordinary read and input. They did not qualify either environment to contain hostile code, resist a local administrator or withstand sustained connection flooding.
+
+Windows Sandbox runs with networking enabled. The extension automatically maps its runtime and control configuration read-only and a private output folder writable. A `sandbox.import` folder is read-only unless its `writable` field is true; `sandbox.export` is writable. Guest setup disables Smart App Control only inside the disposable guest, leaving the host policy unchanged. It opens guest TCP ports for the bearer-protected driver and the mutually authenticated identity service. Temporary host relays listen only on OS-chosen loopback ports.
+
+An isolated session is a temporary Windows user session with its own desktop, clipboard and input. Its MXC network policy allows ingress, egress and host-loopback access. Runtime and control files are copied into that user's private ephemeral workspace; no user folder is mapped automatically. Four temporary loopback relay roles connect driver and identity traffic. Each MXC reverse channel completes mutual proof before it forwards application bytes.
+
+A configured remote machine uses its existing SSH connection and temporary loopback forwarding. The extension does not configure a new externally reachable host listener. These authentication checks do not claim that every local guest transport is encrypted.
+
## Windows and input
Computer use works through `computer:` addresses: the ordinary Pi Agent IDE Read, Search and Delete tools, or `computer_read`, `computer_search` and `computer_delete` without IDE, plus a `computer_*` tool for each action. The `computer_*` tools are deferred, and `tool_search` is turned on.