Desktops and MCP

A desktop is an agent whose machine has a real screen: a dark Linux desktop at 1280 by 800, Google Chrome, LibreOffice and a file manager. Like any agent it keeps everything, sleeps when idle and comes back exactly as it was, open windows and signed-in websites included. It is ready in under a second, and wakes in 0.2 seconds.

Desktops come with paid plans. A desktop uses two running slots, and always sleeps when idle.

Two ways to use one

An agent with a screen. Deploy with --desktop (or "desktop": true). The harness inside the machine learns that it has a screen and how to use it, so you can just ask: "open this site and tell me what you see".
A computer for your own agent. Your agent runs wherever you want, and drives a Waken desktop over MCP. One persistent desktop per end user of your product.

Driving a desktop over HTTP

Route	What it does
GET /agents/{id}/desktop/screenshot	A PNG of the screen, in about 0.1 second
POST /agents/{id}/desktop/actions	Up to 50 actions in order, stops at the first failure
POST /agents/{id}/desktop/viewer	A link to watch and control the desktop live in a browser, valid one hour

POST /agents/{id}/desktop/actions

{ "actions": [
  { "type": "open_url", "url": "https://example.com" },
  { "type": "wait", "ms": 2000 },
  { "type": "click", "x": 640, "y": 400 },
  { "type": "type", "text": "hello" },
  { "type": "key", "keys": "Enter" }
] }

Actions: open_url, click (with button and double), move, type, key (for example ctrl+l), scroll (dx, dy), drag (x, y, to_x, to_y), wait. Coordinates are pixels on the 1280 by 800 screen. These routes need the computers scope.

Recording the screen

A desktop can film its own screen as an MP4 video (H.264), for a demo, a bug report or a trace of what the agent did. Pick a resolution, a frame rate and a quality, start, then stop. One recording at a time, one hour at most. The agent stays awake while it records.

Route	What it does
GET /agents/{id}/desktop/recordings	The recording in progress, the finished ones, and the settings this machine accepts
POST /agents/{id}/desktop/recordings	Start recording
POST /agents/{id}/desktop/recordings/stop	Stop, returns the video with its length and size
GET /agents/{id}/desktop/recordings/file?id=	The MP4 file
DELETE /agents/{id}/desktop/recordings?id=	Delete a video

POST /agents/{id}/desktop/recordings

{ "resolution": 1080, "fps": 30, "quality": "medium" }

Setting	Values
resolution	720 or 1080: the height of the video
fps	15, 30 or 60 frames per second
quality	low, medium or high. Higher means a sharper image and a bigger file

Filming takes processing power from the agent, so the heaviest settings need a bigger machine. The list route tells you what this one accepts, and a setting it cannot hold is refused with a clear message.

Machine	720	1080
2 vCPU (default)	15 or 30 fps	15 or 30 fps
4 vCPU	15, 30 or 60 fps	15, 30 or 60 fps

The screen is 1280 by 800: 720 is the closest to what is really on screen, 1080 enlarges the image for players and editors that expect that size. At medium quality, count about 45 MB per minute at 720 and 30 fps when the whole screen moves, and much less on a calm screen.

Videos are kept on the agent's disk, in /root/recordings. The 20 most recent are kept. The agent can also film itself from the inside with desktop-record start 1080 30 medium and desktop-record stop.

The MCP server

Endpoint: https://api.waken.sh/mcp (streamable HTTP). Authenticate with an API key that has the computers scope.

Claude Code

claude mcp add --transport http waken https://api.waken.sh/mcp \
  --header "Authorization: Bearer $WAKEN_KEY"

Tool	What it does
get_computer	The persistent desktop of one end user (user_id is your own id for them), or their Android phone with os set to android. Created on the first call, woken on the next ones
computer	One action, then a screenshot of the result
computer_batch	Up to 50 actions, then one screenshot
run_shell	A shell command on the computer, 30 seconds at most
read_file, write_file	Text files, 8 MiB at most
start_recording, stop_recording	Record the screen as an MP4 video, one hour at most
request_takeover	Ask a person to take the mouse and keyboard. Returns a link to give them
takeover_status	none, pending, done or expired
close_computer	End the session: the computer sleeps now

When a human is needed

Logins, CAPTCHAs and payments should be done by a person. Your agent calls request_takeover with a reason. You send the returned link to your user. They see the live screen with the reason, do what is needed, and press "I'm done". Your agent polls takeover_status and continues. You also receive a computer.takeover_requested webhook with the link.

Because the desktop persists, your user signs in to a site once. The session is still there next week.

Next: phones