screens

Alpha: interfaces may change before 1.0.

Isolated desktops for agents. screens runs a per-user daemon that starts disposable Linux X screens, each inside its own sandbox: its own X server, network namespace, /tmp, home and session bus. An agent sees and drives a screen through a CLI or an MCP server; the screen never touches your own display, input, focus, clipboard, session bus or files.

Linux first. Each screen is a sandbox-runtime wrap holding Xvnc (Unix socket only), the apps and a small helper. Network access is closed except for the domains you allow.

Requirements

• Linux with unprivileged user namespaces

• Node.js 22 or later

• bwrap (bubblewrap), rg (ripgrep), socat, Xvnc (TigerVNC), xdotool, dbus-run-session

• A browser to run inside screens, such as google-chrome-stable

• For container screens (--backend oci, the only backend on macOS): rootless Podman or Docker (Docker Desktop, OrbStack, Colima), or Apple container on Apple silicon

Related MCP server: glovebox-mcp

Install

pnpm add -g @aurigax-ai/screens

CLI in brief

screens create --allow example.com     # prints a screen id, an agent token and a viewer token
export SCREENS_TOKEN=<agent token>
screens launch <id> -- google-chrome-stable https://example.com
screens screenshot <id> --out shot.png
screens click <id> 640 400
screens type <id> 'hello'
screens key <id> ctrl+l
screens windows <id>
screens list                           # ids, size, owner and state; never a token
screens stop <id>

Exit codes: 0 ok, 2 usage, 3 not found, 4 refused (token, input owner, limit), 5 backend failure. --json prints one JSON object. The full contract (verbs, flags, JSON shapes, the daemon socket protocol) is in CONTRACT.md.

The daemon starts on the first command and listens on $XDG_RUNTIME_DIR/screens/daemon.sock. At most maxScreens screens run at once (default 4, 1 to 16, set in ~/.config/screens/config.json).

MCP

screens mcp --screen <id> is an MCP stdio server for one screen, with the token in SCREENS_TOKEN. It offers computer (the actions and arguments of Anthropic's computer_toolset_20260801, screenshots scaled so the longest side is at most 1280 pixels and coordinates in that space), screen_launch and screen_windows.

{
  "mcpServers": {
    "screen": {
      "command": "screens",
      "args": ["mcp", "--screen", "<id>"],
      "env": { "SCREENS_TOKEN": "<agent token>" }
    }
  }
}

Development

pnpm install
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:integration

See AGENTS.md for the rules every change follows.

License

MIT