Skip to main content

Your computer as a sandbox

The machine provider runs the agent's bash tool on your own computer. The agent stays in the cloud. Commands run as you, with your PATH, environment and installed tools. It can also give the agent your screen, mouse and keyboard, and run local MCP servers.

Your computer opens no port. broods machine <sandbox> holds one WebSocket to the gateway, and each command comes down it. When the daemon is not running, the tool call fails with the command that starts it.

Keep permissionMode on ask. With bypass the agent runs any command on your computer without asking.

Configure​

broods/index.ts
import { defineAgent, defineSandbox } from "broods";

export const myMac = defineSandbox({
name: "my-mac",
provider: "machine",
permissionMode: "ask",
network: { mode: "allow-all" },
options: { cwd: "/Users/me/Projects/app" }, // optional, default is where the daemon started
envVars: { FOO: "bar" }, // merged over your environment
});

export const helper = defineAgent({
name: "helper",
sandboxes: [myMac],
});

persistent, size and snapshot are rejected, and network.mode must be allow-all.

The daemon strips every BROODS_* variable from the environment of agent commands and MCP servers, so an agent shell cannot read BROODS_API_KEY or BROODS_TOKEN.

Run the daemon​

broods machine my-mac
broods machine my-mac --cwd ~/Projects/app

It needs a broods login and a deployed stage, like broods logs. The daemon trades your login for a fifteen-minute stage ticket and hands core a fresh one on the open socket before it expires, so a long command is never cut off by the ticket; each reconnect mints a fresh one too. The machine socket also accepts an account key or a role session, which needs sandboxes:write on the sandbox. It never accepts the runtime key, which is meant for frontends.

The daemon prints each command with its exit code and reconnects after a network drop. While it holds the record, any other daemon on any computer is refused, and the refusal names the host that holds it:

broods machine my-mac --force # take the record over from another daemon

The record is released when the daemon exits, so a normal restart never needs --force. You need it only after a daemon was killed while its network was down, before the platform notices the dead socket. The daemon exits with the reason when the credential is invalid, the name has no machine record, the takeover is refused, or another daemon takes the record.

Computer use​

Start the daemon with --computer and agents on this sandbox also get a computer tool for screenshots of the main display, mouse and keyboard. It takes the action names of Anthropic's computer-use tool, such as screenshot, left_click, type, key, scroll and zoom, as a plain tool, so any model provider can call it.

broods machine --doctor --request # once: grant Screen Recording and Accessibility to this terminal
broods machine my-mac --computer
  • macOS only for now. The first start compiles a small helper with swiftc from the Xcode Command Line Tools into ~/.broods/desktop/. Both permissions belong to the terminal that runs the daemon.
  • Coordinates are pixels in the screenshot, which is the display scaled to 1280 on its long edge. Retina displays need no setup. Every result names the frontmost app.
  • screenshot, zoom, cursor_position and wait never ask for approval on their own. Every other action asks unless permissionMode is bypass.
  • Actions run in the order the model gave them. One that comes after an action waiting for approval in the same step never runs ahead of it: it is asked for in the same round, even a screenshot, and runs after that action, so it sees its result.
  • The tool tells the model that text on screen is data, not instructions, and to ask before CAPTCHAs, payments or security settings.
  • Ctrl+C on the daemon stops everything.

More than one computer​

An agent drives every machine sandbox in its sandboxes, wherever it sits in the list.

defineAgent({
name: "support",
sandboxes: [laptopMac, officeMac],
});

With one computer reachable, computer takes just the action. With several, it also takes a sandbox naming the computer, and every result says which screen it came from. Coordinates do not carry across screens, so the model should take a screenshot after switching. Approval follows the computer the call names, so a bypass machine clicks without asking while an ask machine still asks. Whether an agent can reach a computer at all is up to its owner starting the daemon with --computer.

Local MCP servers​

Start the daemon with --mcp <file> and the stdio MCP servers in that file run on your computer for your agents. The file uses the .mcp.json shape that Claude Code, Cursor and Codex read. Each server must speak MCP 2026-07-28: a server built on a 2025-era SDK is refused when the daemon first starts it, with an error naming the version. Starting a server also runs its command once more, briefly, to ask which version it speaks.

.mcp.json
{
"mcpServers": {
"blender": { "command": "uvx", "args": ["blender-mcp"] },
"files": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Work"]
}
}
}
broods machine my-mac --mcp ./.mcp.json

Register the server by naming the sandbox instead of a URL. The name is the mcpServers key:

export const blender = defineMcp({
name: "blender",
sandbox: myMac,
allowedTools: ["get_scene_info", "execute_blender_code"],
});

export const designer = defineAgent({
name: "designer",
sandboxes: [myMac],
mcp: { [blender.name]: { enabled: true, needsApproval: true } },
});

The daemon starts a server on its first call and keeps it running. The platform sees server names, tool listings and results, never the file or its commands. See Tools for MCP servers in general.

Limits​

  • No workspaces. The file tools need the workspace mount, which a computer does not have. A run is refused when a workspace would inherit a machine, so give that workspace its own sandbox or sandbox: null. Use bash for files.
  • No background jobs, snapshots, suspend or resume.
  • The dashboard lists a connected computer under Sandboxes, Instances with its connection state, size, connect time, last seen time and the command that starts it. The size is the CPU count, memory and home disk the daemon reports when it connects; a daemon from an older CLI reports none, and the size shows ? until you update and restart it. It has no image, trace or lifecycle controls.