Screenshots, mouse & keyboard

Open the desktop

Open your desktop, sign in with your ComputerUse account, select the assigned computer and choose Take control. Click inside the screen to use the mouse and keyboard. The text box supports longer text and paste. Return control to agent enables agents to claim a new lease.

The owner desktops run inside both ThinkCentres. The physical 16 GiB host provides 12 GiB guest RAM and 6 vCPUs; the physical 8 GiB host provides 6 GiB guest RAM and 4 vCPUs. New 8 GiB Standard desktops receive an 80 GiB virtual disk; Creator desktops receive 150 GiB. The existing owner pilots retain their already-provisioned 150 GiB disks, and the portal shows their actual capacity. Proxmox keeps the remaining physical memory. These are system RAM allocations, not dedicated GPU/video memory. This pilot is assigned to the operator account; it is not public rental inventory. New customer checkout remains disabled until automated fresh-rental provisioning, cleanup and billing pass launch checks.

Human handoff and privacy

Only a signed-in human session can take or return control. Takeover waits for any already-dispatched input request to finish, invalidates the old agent lease and pauses agent screenshots and mouse/keyboard calls. A disconnected or expired human session leaves agents paused. Sign in again and explicitly return control when ready.

This pauses the ComputerUse API, not programs already running inside the guest. A program or agent previously installed inside the desktop could still observe its environment. Use a fresh, trusted desktop for sensitive work. After handback, the agent can use signed-in browser sessions; prefer accounts with limited permissions. Screenshots already delivered to an agent cannot be recalled. This service has no terminal/file API, recording or audio endpoint yet.

Authentication and ownership

Create an API key in the account portal with desktop:read and, when authorized, desktop:write. These scopes cover the key owner's assigned desktops. They do not grant another customer's computer, host SSH, Proxmox administration or billing access. Keep the key in your agent's secret configuration.

Every HTTPS control request checks credentials, account status, desktop ownership, the active rental when applicable, current host heartbeat and the current control mode. A direct connection requires the current controlling human session on an owner pilot. Its authorization is renewed through HTTPS about every three seconds and expires no later than ten seconds after the last authorization, assuming synchronized clocks. Revocation, suspension or an unavailable management service prevents renewal. Explicit handoff fences the direct connection before acknowledgment; closing the viewer never automatically returns control to an agent. Expired/revoked credentials, suspended rentals and unavailable hosts stop access. The owner pilot has a separate operator allocation and no paid rental.

REST contract

All paths below are under https://api.computeruse.space/api/v1. Send Authorization: Bearer <your-key>. POST requests use JSON; normal request body limit is 16 KiB.

Every POST needs desktop_id. Lease renewal and release also need the current lease. Renewal rotates the lease token: retain the newly returned value. Agent input requires lease, operation_id (a UUID) and action. The human viewer uses its current controlling session. Direct connection setup additionally sends sdp (maximum 12,000 characters); renewal and closure send the returned stream_id. The browser never receives the private guest service token. Direct input uses the same bounded action protocol and operation IDs; a lost input response is never automatically replayed through HTTPS. Direct operation deduplication is held in guest memory, so an interrupted/restarted guest makes unacknowledged input uncertain. This local pilot does not provide a public TURN relay or direct agent API; distant customers and agents still use the HTTPS path.

Input actions

Coordinates are integer pixels within a 1280 × 800 desktop: x 0–1279, y 0–799.

Buttons: 1 left, 2 middle, 3 right. Scroll directions: up/down/left/right; amount 1–10. Text limit: 4096 characters. Key combinations accept ctrl/alt/shift/super and supported named keys such as Return, Tab, Escape, BackSpace and arrow keys. No shell string is accepted by this API. Desktop write permission can still operate a terminal application inside the guest, so treat it as powerful access to that computer.

Python example

This example navigates the selected desktop browser. Use a computer you own and are authorized to control. The key and desktop ID come from your environment, not source code.

import json, os, uuid
from urllib.request import Request, urlopen

origin = "https://api.computeruse.space/api/v1"
key = os.environ["COMPUTERUSE_API_TOKEN"]
desktop_id = os.environ["COMPUTERUSE_DESKTOP_ID"]

def call(path, data):
    request = Request(origin + path, data=json.dumps(data).encode(),
        headers={"Authorization": "Bearer " + key,
                 "Content-Type": "application/json"})
    with urlopen(request, timeout=30) as response:
        return json.load(response)

lease = call("/desktops/lease", {"desktop_id": desktop_id})["lease"]
# Keep each operation ID if recovering from an interrupted response.
for action in [{"type": "key", "key": "ctrl+l"},
               {"type": "type", "text": "https://example.com"},
               {"type": "key", "key": "Return"}]:
    operation_id = str(uuid.uuid4())
    call("/desktops/action", {"desktop_id": desktop_id, "lease": lease,
         "operation_id": operation_id, "action": action})
call("/desktops/release", {"desktop_id": desktop_id, "lease": lease})

Ordered input batches

For rapid typing or a short sequence, send {"type":"batch","actions":[{"type":"type","text":"hello"},{"type":"key","key":"Return"}]} as the action. A batch accepts 1–16 actions and at most 4096 total text characters; nested batches are rejected. The guest has a five-second execution budget with bounded button release. The whole batch shares one operation ID. A failure can leave a partially completed batch, so an uncertain batch must not be replayed automatically.

Safe retries

Completed input is deduplicated by desktop and operation ID. Reusing an ID with different input returns 409. If dispatch times out or the broker restarts after dispatch, the result may be uncertain: the broker records that state and will not replay it. Inspect the screen before deciding on a new operation. Never automatically issue a second click with a fresh ID after a timeout.

401 means the credential is unavailable; 403 means insufficient permission or inactive ownership; 409 covers human control, lease conflicts and uncertain/reused operations; 429 is the account rate limit; 503 means unavailable host or controller. Human takeover is not an error to work around.

Screenshots and persistence

Screenshots are returned over authenticated HTTPS with Cache-Control: no-store. The service does not save screenshots or keystroke text in its database or routine logs. A client may retain images it receives. The browser viewer attempts a direct encrypted WebRTC data connection after the owner takes control. The current LAN pilot permits the configured owner workstation addresses only. The connection indicator says Direct local connection when it succeeds, or Via Hetzner · higher latency on fallback. Local JPEG updates target up to 12.5 frames per second; fallback HTTPS polling targets up to four, with actual rates limited by capture and network time. Screen transfer does not hold the input lock, and authorization and the control epoch are checked again before a frame is delivered. Rapid input is grouped into ordered batches to avoid a separate round trip for every queued keystroke. This is not a video stream and has no audio.

Files, browser profiles and installed software persist inside the owner pilot until explicitly reset. Stopping an agent or returning control does not erase RAM or disk. Verified fresh-rental cleanup is still a separate launch requirement. See memory and state and fresh virtual computers.