Computers
A Computer is a durable cloud desktop. It gives each user, agent, or workflow a real Linux GUI with browser state, files, shell access, desktop streaming, and programmatic control.
Use it when the work depends on pixels, sessions, browser logins, desktop apps, accessibility trees, or a human taking over the same machine an agent was using. For pure code execution, builds, and preview servers, Sandboxes are cheaper and faster. For a 24/7 production web app, use App Engine.
What Computers are for
Run a browser session that stays logged in, exposes pixels to agents, and can be resumed by a human.
Let an operator open the same live desktop, inspect the state, and continue from where automation stopped.
Drive desktop apps with mouse, keyboard, clipboard, windows, accessibility, and shell commands.
Keep files, browser profiles, installed tools, and local state across stop/start cycles.
When to use Computer vs Sandbox
| Workload | Pick | Why |
|---|---|---|
| Run tests, install packages, build code, expose a dev server | Sandbox | Faster and cheaper shell-first compute |
| Computer-use agent that must click through a website | Computer | Needs pixels, browser state, and input events |
| Logged-in browser session that must survive across tasks | Computer | Browser profile persists with the VM |
| Headless Playwright, API tests, CLI workflows | Sandbox | No visible desktop needed |
| Screenshot-based QA or visual inspection | Computer | Uses the rendered screen as truth |
| Desktop apps, extensions, file pickers, or manual takeover | Computer | Needs a full GUI and streamable session |
| Public 24/7 app URL for customers | App Engine | Built for durable deployments and custom domains |
What is in the box
- Xfce desktop with Firefox and common Linux apps pre-installed.
- Terminal with
bash,python, and a standard CLI toolchain. - Persistent storage so files and browser state survive stop/start cycles through snapshot restore.
- Desktop streaming so the platform or your app can embed the live screen with short-lived tickets.
- Desktop control API for screenshots, clicks, typing, scrolling, clipboard, windows, accessibility, shell, and files.
- OSA agent pre-installed and disabled by default. Activate it when you want autonomous desktop task execution.
What a Computer is, concretely
| Layer | What it gives you |
|---|---|
| Desktop VM | A real Linux graphical session with browser, files, packages, and user state |
| Persistent disk | Durable filesystem and browser profile across stop/start cycles |
| Stream gateway | Live desktop pixels and input forwarding for platform UI or embedded apps |
| Control API | Screenshots, clicks, typing, scrolling, clipboard, shell, files, windows, and accessibility |
| Workspace attribution | Tenant, workspace, user, metadata, and billing ownership attached to the machine |
| Human takeover | A signed-in operator can open the same running desktop an agent was using |
Computers are not disposable command runners. They are long-lived desktop machines that can be resumed, inspected, embedded, and controlled.
Fast startup
MIOSA keeps ready desktop capacity on the managed fleet so a new Computer can be assigned instead of cold-booted from scratch. The production acceptance test measures the complete user-visible path from creation to the first usable desktop frame.
The verified 2026-08-06 canary completed 10 of 10 warm launches and reached a browser-ready desktop in a median 740 ms:
| Phase | Time |
|---|---|
| Create response median | 348 ms |
| Create request to browser-ready desktop median | 740 ms |
| Create request to browser-ready desktop p90 | 809 ms |
| Slowest sample | 942 ms |
This is a dated warm-path canary, not a guarantee that every region and capacity condition will complete inside the sampled range. See Fast start & readiness for the readiness contract, measurement boundary, and troubleshooting guidance.
Access model
There are three ways to enter a Computer desktop. They are intentionally different because they protect different surfaces.
| Access path | Who uses it | Authentication |
|---|---|---|
| Platform desktop button | Signed-in MIOSA users | Normal MIOSA session and workspace permissions |
| Embedded stream ticket | Your app backend and frontend | Your backend mints a short-lived URL with the MIOSA API key |
| Raw external desktop URL | Emergency or direct viewer access | Viewer password gate |
Use Embedding & Streaming for your own UI.
Use viewer_password() / rotate_viewer_password() only for raw external desktop viewer links.
Authenticated platform desktop links and stream tickets do not need the raw viewer password.
Quick example
Desktop action reference
Desktop methods available on a running computer:
| Group | Method | Description |
|---|---|---|
| Screen | screenshot() | Capture full desktop as PNG bytes |
screenshot_base64() | Same, base64-encoded - ready for LLM vision APIs | |
| Click | click(x, y) | Generic click (defaults to left button) |
left_click(x, y) | Left-button click | |
right_click(x, y) | Right-button click (context menu) | |
double_click(x, y) | Double-click | |
| Mouse | move_cursor(x, y) | Move cursor without clicking |
mouse_down(x, y) | Press and hold the mouse button | |
mouse_up(x, y) | Release a held mouse button | |
drag(from_x, from_y, to_x, to_y) | Click-drag between two coordinates | |
| Keyboard | type(text) | Type a string at the current focus |
key(key) | Send a single key (e.g. "Return", "ctrl+a") | |
hotkey(*keys) | Simultaneous key combo (e.g. "ctrl", "c") | |
key_down(key) | Press and hold a key | |
key_up(key) | Release a held key | |
| Scroll | scroll(direction, clicks) | Scroll up/down/left/right |
scroll_up/down/left/right(clicks) | Convenience scroll methods | |
| Clipboard | get_clipboard() | Read clipboard text |
set_clipboard(text) | Write text to clipboard | |
| Screen info | get_screen_size() | Desktop resolution {width, height} |
get_cursor_position() | Current cursor {x, y} in normalized coords | |
| Windows | windows() | List open windows with IDs, titles, positions |
launch(app) | Open an installed app by name | |
focus_window(id) | Bring a window to the foreground | |
get/set_window_size(id, ...) | Read or set window dimensions | |
get/set_window_position(id, ...) | Read or set window position | |
maximize/minimize/close_window(id) | Change window state | |
| Environment | get_desktop_environment() | DE name and version (e.g. xfce4) |
set_wallpaper(path) | Set desktop background from a VM file path | |
get_accessibility_tree() | AT-SPI element tree for structured agent perception | |
| Shell | bash(cmd) | Execute a shell command inside the VM |
python(code) | Execute a Python snippet inside the VM | |
write_file(path, content) | Write a file into the VM’s filesystem | |
read_file(path) | Read a file from the VM’s filesystem |
See Desktop Control for full examples, parameter details, and coordinate system documentation.
Workspace-scoped creation
Computers can be created inside a named workspace so that resources are isolated and billed separately. Pass external_workspace_id to attribute the computer to a tenant in your platform.
external_workspace_id is a free-form string you control.
Use your own tenant, org, customer, or workspace identifier.
Usage is tracked per workspace in the billing dashboard so you can attribute compute costs to individual customers.
Operator workflow
Most production Computer flows look like this:
The Computer is the stateful machine. The stream ticket is only temporary access to that machine. If the browser tab closes, the Computer keeps its state until you stop or delete it.
White-label desktops
Computers support per-tenant desktop branding. After starting a computer, push a wallpaper and apply it with two SDK calls. The wallpaper persists across stop/start cycles because it is stored in the VM’s snapshotted filesystem.
How it fits together
Your code talks to the MIOSA API. MIOSA routes actions to a desktop command service. The command service drives the X11 session and returns screenshots or action confirmations. For embedded views, MIOSA streams the desktop over WebSocket to a browser iframe.
Embed the desktop in a browser
Fetch signed Computer URLs from your backend, then pass the desktop URL to a browser iframe:
See Embedding & Streaming for the full pattern including authentication, iframe policy, and expiry handling.
Lifecycle
create -> provisioning -> running <-> stopped
-> recovering -> running
-> error
stopped or running -> deleted| State | Description |
|---|---|
provisioning | The VM is being claimed, restored, and prepared |
running | Desktop is up, streamable, and accepting API actions |
stopped | Compute is stopped and filesystem state is preserved |
recovering | MIOSA is restoring a desired-running Computer after host maintenance |
error | Recovery did not complete; the preserved disk or snapshot remains available for retry |
deleted | Permanent deletion; not reversible |
Stopping a computer pauses billing (or charges at the stopped rate, depending on your plan). Restarting resumes from the snapshot.
During host maintenance, MIOSA preserves Computer identity, disk state, snapshots, metadata, and desired state. Computers that were running are restored and verified before the host returns to active service. Intentionally stopped Computers remain stopped.
If a local resume fails, MIOSA preserves the disk and snapshot instead of replacing the Computer with a blank machine.
Use delete only when the state should be permanently removed.
Production checklist
Before you rely on a Computer in production, verify these points.
| Area | Check |
|---|---|
| Workspace attribution | Set external_workspace_id, external_user_id, or workspace/project fields when building a white-label app |
| Access | Use platform auth or stream tickets for normal users |
| Secrets | Put API keys in backend code or encrypted env, not inside frontend bundles |
| State | Use stop/start for durable sessions and delete only when state should be removed |
| Observability | Log the Computer ID, external IDs, and task/run ID together |
| Recovery | Design the app so a user can reopen the same running Computer after refreshing the browser |
Sizing
| Size | vCPU | RAM | Disk | Typical use |
|---|---|---|---|---|
xs | 1 | 2 GB | 10 GB | Lightweight headless tasks |
small | 2 | 4 GB | 20 GB | Default for a single agent and basic browsing |
medium | 4 | 8 GB | 50 GB | Heavier desktop apps, faster page loads |
large | 8 | 16 GB | 100 GB | Multi-app, large-context AI workloads |
xl | 16 | 32 GB | 200 GB | Intensive parallelism, large model weights |
GPU support for accelerated desktop and GPU-aware agent workflows is plan-dependent.
Next
Full action reference: screenshot, click, type, key, scroll, drag, hotkey, windows, accessibility tree, and more. Open
Embed the live pixel stream in your own UI using short-lived stream tokens. Open
Bring your own hardware (Mac, Linux, Windows). One command registers your machine as a MIOSA computer. Open