Run a real Linux desktop for AI agents.
portabledesktop is a standalone Go binary that embeds a compressed Linux
runtime, unpacks it on first run, and manages desktop sessions directly. Give
your agent a controllable desktop with real GUI apps, mouse/keyboard input,
screenshots, and recordings — no containers or display servers to configure.
Download a prebuilt binary from GitHub Releases.
# Start a desktop session.
portabledesktop up --json
# Launch an app inside the session.
portabledesktop open -- google-chrome-stable --new-window
# Take a screenshot.
portabledesktop screenshot shot.png
# Record the session to MP4 (Ctrl+C to stop).
portabledesktop record run.mp4
# Tear down the session.
portabledesktop downup --json prints session metadata (display number, VNC port, environment
variables) so agent tooling can connect programmatically.
portabledesktop viewer starts a local HTTP server that serves a noVNC
client, letting a human watch and interact with the desktop in a browser:
portabledesktop viewer
# Opens http://localhost:6080 by default.This is useful for debugging agent runs or intervening when the agent gets stuck.
The VNC endpoint is unauthenticated by default
(SecurityTypes None). Expose it only on trusted boundaries — localhost,
a private network, VPN, or SSH tunnel.
| Architecture | Supported |
|---|---|
| Linux x64 | ✓ |
| Linux arm64 | ✓ |
| Variable | Description |
|---|---|
PORTABLEDESKTOP_RUNTIME_DIR |
Skip unpack, use this runtime dir |
PORTABLEDESKTOP_STATE_FILE |
Override default state file path |
See pd/README.md for build instructions, Makefile targets,
and development workflow.
examples/demo/— Docker container that runs an AI agent loop (Anthropic Claude + computer-use tool) on the virtual desktop.examples/agent/— Bun/TypeScript agent that drives the desktop via the CLI binary, with support for both Anthropic and OpenAI providers.