Desktop endpoints

Desktop management#

Endpoints for creating, listing, updating, and controlling the lifecycle of desktops.

List desktops#

GET /api/desktops

Returns all desktops belonging to the authenticated user.

Response:

[
  {
    "id": "clx...",
    "name": "my-agent",
    "status": "running",
    "tier": "pro",
    "ipAddress": "10.0.3.42",
    "createdAt": "2026-03-15T10:00:00Z",
    "keepAlive": false
  }
]

Create desktop#

POST /api/desktops

Body:

Response: 201 with the created desktop object.

Note: The providerConfig.apiKey is your own AI provider key (BYOK). It is injected into the VM at boot and never stored in Le Bureau's database.

Get desktop#

GET /api/desktops/:id

Returns a single desktop with full details including IP address, resource metrics, and agent readiness status.

Update desktop#

PATCH /api/desktops/:id

Body:

Delete desktop#

DELETE /api/desktops/:id

Destroys the desktop and its VM. The data disk contents are lost. Returns 204 No Content.

Start desktop#

POST /api/desktops/:id/start

Boots a stopped desktop. The desktop transitions through booting to running. Returns 200 with the updated desktop.

Stop desktop#

POST /api/desktops/:id/stop

Shuts down the desktop VM gracefully. Returns 200 with the updated desktop.

Restart desktop#

POST /api/desktops/:id/restart

Stops and then starts the desktop. Equivalent to stop + start but atomic. Returns 200.

Desktop interaction#

Send chat message#

POST /api/desktops/:id/chat

Sends a message to the AI agent on the desktop. The agent processes the message and returns a response.

Body:

Response:

{
  "response": "I've installed PostgreSQL and created the database...",
  "messageId": "msg_abc123"
}

Note: The desktop must be in running state with agentReady: true. If the agent is not ready, you receive a 503 Service Unavailable.

Stream chat response#

POST /api/desktops/:id/chat/stream

Same as the chat endpoint, but returns an SSE stream with incremental response chunks. Use this for a real-time typing effect.

Body: same as /chat.

Get chat history#

GET /api/desktops/:id/chat/messages

Returns the full conversation history for the desktop.

Execute command#

POST /api/desktops/:id/exec

Runs a single command on the desktop.

Body:

Response:

{
  "stdout": "...",
  "stderr": "...",
  "exitCode": 0
}

Run bash script#

POST /api/desktops/:id/bash

Runs a multi-line bash script on the desktop. The script is written to a temp file and executed.

Body:

File operations#

GET /api/desktops/:id/files?path=/home/agent/project

Lists files at the given path.

POST /api/desktops/:id/files

Upload or write a file.

Body:

Screenshot#

GET /api/desktops/:id/screenshot

Returns a PNG screenshot of the desktop's current display. Useful for monitoring agent activity from scripts.

Metrics#

GET /api/desktops/:id/metrics

Returns current CPU, RAM, and disk usage for the desktop.

Response:

{
  "cpu": 23.5,
  "memory": { "used": 1024, "total": 4096, "percent": 25.0 },
  "disk": { "used": 5120, "total": 20480, "percent": 25.0 }
}

Desktop status stream#

GET /api/desktops/stream

An SSE endpoint that pushes real-time status updates for all your desktops. See Streaming endpoints for details on consuming SSE.

Error codes#