Computers are persistent desktop VMs with a Linux desktop, streamed desktop access, and APIs for exec, files, apps, metrics, and desktop control. Base path: /api/v1/computers.

Verbs supported: GET (list/get/config), POST (create/start/stop/restart/clone/resize), PATCH (update), PUT (update), DELETE (delete).

Create a Computer

POST /api/v1/computers

Creates a new computer and begins provisioning.

Request Body

If a default agent runtime profile exists for the workspace or tenant and it applies to computers, MIOSA applies it automatically. Profile env vars are stored in the encrypted computer env store and synced into the VM after OSA is healthy. Profile connectors are bound through MIOSA egress as opaque miosa-tok-* placeholder tokens.

Response - 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "...",
  "owner_user_id": "...",
  "name": "my-computer",
  "slug": "my-computer",
  "template_type": "miosa-desktop",
  "size": "small",
  "vcpus": 1,
  "memory_mb": 4096,
  "status": "provisioning",
  "vm_id": null,
  "workspace_id": "660e8400-e29b-41d4-a716-446655440001",
  "project_id": "770e8400-e29b-41d4-a716-446655440002",
  "external_workspace_id": null,
  "external_user_id": null,
  "external_project_id": null,
  "sandbox_url": "https://my-computer.sandbox.miosa.ai",
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "selected_apps": [],
  "settings": {},
  "ai_config": {},
  "agent_session_id": null,
  "agent_status": null,
  "resolution": "1280x720",
  "auto_stop": 0,
  "created_at": "2026-04-11T00:00:00Z",
  "updated_at": "2026-04-11T00:00:00Z"
}

sandbox_url is a legacy preview field on the Computer response. Use desktop_url for the desktop stream and the /computers/{id}/urls endpoint for short-lived desktop and terminal URLs.

Errors

curl -X POST https://api.miosa.ai/api/v1/computers 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "my-computer",
    "template_type": "miosa-desktop",
    "size": "small",
    "workspace_slug": "dr-smith-clinic",
    "workspace_name": "Dr. Smith Clinic",
    "project_slug": "records-portal",
    "project_name": "Records Portal",
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789",
    "agent_runtime_profile_id": "9f4b3d8e-0000-0000-0000-000000000000"
  }'

List Computers

GET /api/v1/computers

Returns all computers belonging to the authenticated user’s tenant.

Query Parameters

Response - 200 OK

{
  "computers": [
    {
      "id": "...",
      "name": "my-computer",
      "status": "running",
      "size": "small",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

# All computers
curl https://api.miosa.ai/api/v1/computers 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a workspace
curl "https://api.miosa.ai/api/v1/computers?workspace_id=660e8400-e29b-41d4-a716-446655440001" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a project
curl "https://api.miosa.ai/api/v1/computers?project_id=770e8400-e29b-41d4-a716-446655440002" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get a Computer

GET /api/v1/computers/{id}

Path Parameters

Response - 200 OK

Full computer object (same as create response, with current status).

Errors

curl https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Update a Computer

PATCH /api/v1/computers/{id}

Currently supports updating agent_session_id only.

Request Body

Response - 200 OK

Updated computer object.

curl -X PATCH https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"agent_session_id": "session-uuid"}'

Delete a Computer

DELETE /api/v1/computers/{id}

Permanently destroys the VM and removes the computer record.

Response - 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}

Errors

curl -X DELETE https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Start a Computer

POST /api/v1/computers/{id}/start

Resumes a stopped or paused computer.

Response - 200 OK

Updated computer object with status: "running".

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/start 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Stop a Computer

POST /api/v1/computers/{id}/stop

Pauses a running computer. Can be restarted later.

Response - 200 OK

Updated computer object with status: "stopped".

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stop 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Restart a Computer

POST /api/v1/computers/{id}/restart

Stops and immediately restarts a running computer.

Response - 200 OK

Updated computer object.

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/restart 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Auto-Stop Configuration

GET /api/v1/computers/{id}/auto-stop

Response - 200 OK

{
  "auto_stop_seconds": 3600,
  "enabled": true
}

curl https://api.miosa.ai/api/v1/computers/{id}/auto-stop 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Update Auto-Stop Configuration

PATCH /api/v1/computers/{id}/auto-stop

Request Body

Response - 200 OK

Updated auto-stop configuration.

curl -X PATCH https://api.miosa.ai/api/v1/computers/{id}/auto-stop 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"auto_stop_seconds": 3600}'

Get Desktop Stream Credentials

GET /api/v1/computers/{id}/vnc-credentials

Returns credentials for direct desktop streaming access.

Response - 200 OK

{
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "ws_url": "wss://my-computer.computer.miosa.ai/ws/vnc/550e8400-e29b-41d4-a716-446655440000?auth=stream_token",
  "token": "stream_auth_token",
  "expires_at": 1712700060,
  "computer_id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-computer"
}

curl https://api.miosa.ai/api/v1/computers/{id}/vnc-credentials 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Stream Token

POST /api/v1/computers/{id}/stream-token

Returns a time-limited auth token for desktop and terminal WebSocket connections.

Response - 200 OK

{
  "token": "stream_auth_token",
  "expires_at": 1712700060
}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stream-token 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Computer URLs

GET /api/v1/computers/{id}/urls

Returns all connection URLs for the computer.

Response - 200 OK

{
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "stream_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "terminal_url": "wss://my-computer.computer.miosa.ai/ws/terminal/550e8400-e29b-41d4-a716-446655440000",
  "computer_id": "550e8400-e29b-41d4-a716-446655440000"
}

curl https://api.miosa.ai/api/v1/computers/{id}/urls 
  -H "Authorization: Bearer $MIOSA_API_KEY"

List Installed Apps

GET /api/v1/computers/{id}/apps

Returns the list of applications installed on the computer.

Response - 200 OK

Response containing the list of installed applications.

curl https://api.miosa.ai/api/v1/computers/{id}/apps 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Clone a Computer

POST /api/v1/computers/{id}/clone

Creates a new computer from the current state of an existing one. The source computer must be running; the clone starts in provisioning and progresses to running.

Response - 201 Created

Full computer object for the new clone with its own ID.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/clone 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Resize a Computer

POST /api/v1/computers/{id}/resize

Changes the vCPU and memory allocation. The computer must be stopped first.

Request Body

Response - 200 OK

Updated computer object with new size, vcpus, and memory_mb.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/resize 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"size": "medium"}'

Move a Computer

POST /api/v1/computers/{id}/move

Migrates a computer to a different region. The computer must be stopped. Live migration is not supported; the computer will be moved offline.

Request Body

Response - 200 OK

Updated computer object with new region.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/move 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"region": "us-east-ny"}'

Get Metrics

GET /api/v1/computers/{id}/metrics

Returns time-series CPU, RAM, and credit-burn metrics. Useful for dashboards and auto-stop logic.

Query Parameters

Response - 200 OK

{
  "cpu_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 12.4},
    {"ts": "2026-05-17T10:01:00Z", "value": 8.1}
  ],
  "memory_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 45.2}
  ],
  "credits_per_hour": 3
}

curl "https://api.miosa.ai/api/v1/computers/{id}/metrics?window=1h" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Env Vars

Encrypted per-computer environment variables. Values are decrypted at boot and injected into the VM environment.

List

GET /api/v1/computers/{id}/env

curl https://api.miosa.ai/api/v1/computers/{id}/env 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Create

POST /api/v1/computers/{id}/env

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/env 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"name": "DATABASE_URL", "value": "postgres://user:pass@host/db"}'

Update

PATCH /api/v1/computers/{id}/env/{name}

Delete

DELETE /api/v1/computers/{id}/env/{name}

Returns 200 OK.

Port Exposure

Control per-port visibility for services running inside the computer.

List Ports

GET /api/v1/computers/{id}/ports

Expose a Port

POST /api/v1/computers/{id}/ports

Update Port Visibility

PATCH /api/v1/computers/{id}/ports/{port}

Remove Port

DELETE /api/v1/computers/{id}/ports/{port}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/ports 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"port": 3000, "visibility": "public"}'

Common Errors

See also

• Desktop API - screenshot, click, type, scroll, drag, windows
• Files API - read, write, stat, mkdir, rename, copy, chmod, download
• Exec API - bash and Python execution
• Snapshots API - create, restore, and delete checkpoints
• Events (SSE) - computer lifecycle event stream
• Regions - available regions for computer placement