https://github.com/coder/portabledesktop
Run a real Linux desktop for AI agents.
https://github.com/coder/portabledesktop
agent ai llm typescript
Last synced: 20 days ago
JSON representation
Run a real Linux desktop for AI agents.
- Host: GitHub
- URL: https://github.com/coder/portabledesktop
- Owner: coder
- License: mit
- Created: 2026-02-19T15:41:15.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T17:41:23.000Z (about 1 month ago)
- Last Synced: 2026-03-21T08:02:58.457Z (about 1 month ago)
- Topics: agent, ai, llm, typescript
- Language: Go
- Homepage:
- Size: 297 KB
- Stars: 10
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# portabledesktop
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.
## Install
Download a prebuilt binary from
[GitHub Releases](https://github.com/coder/portabledesktop/releases).
## Quick Start
```bash
# 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 down
```
`up --json` prints session metadata (display number, VNC port, environment
variables) so agent tooling can connect programmatically.
## Human-in-the-Loop Viewer
`portabledesktop viewer` starts a local HTTP server that serves a noVNC
client, letting a human watch and interact with the desktop in a browser:
```bash
portabledesktop viewer
# Opens http://localhost:6080 by default.
```
This is useful for debugging agent runs or intervening when the agent gets
stuck.
## Security
The VNC endpoint is **unauthenticated by default**
(`SecurityTypes None`). Expose it only on trusted boundaries — localhost,
a private network, VPN, or SSH tunnel.
## Platform
| Architecture | Supported |
|--------------|-----------|
| Linux x64 | ✓ |
| Linux arm64 | ✓ |
## Environment Variables
| Variable | Description |
|-----------------------------|-----------------------------------|
| `PORTABLEDESKTOP_RUNTIME_DIR` | Skip unpack, use this runtime dir |
| `PORTABLEDESKTOP_STATE_FILE` | Override default state file path |
## Development
See [`pd/README.md`](pd/README.md) for build instructions, Makefile targets,
and development workflow.
## Examples
- [`examples/demo/`](examples/demo/) — Docker container that runs an AI agent
loop (Anthropic Claude + computer-use tool) on the virtual desktop.
- [`examples/agent/`](examples/agent/) — Bun/TypeScript agent that drives the
desktop via the CLI binary, with support for both Anthropic and OpenAI
providers.