OpenComputers lets you register physical or virtual machines you already own (Mac, Linux, Windows) and control them through MIOSA’s API — run commands, manage files, expose HTTP tunnels, dispatch AI agents, build inference clusters, and manage secrets.

Base path: /api/v1/opencomputers

Verbs supported: GET (list/show), POST (register/create/exec/dispatch), PATCH (update tags/tunnels), DELETE (revoke/cancel).

Hosts

List hosts

GET /api/v1/opencomputers/hosts

{
  "data": [
    {
      "id": "host_abc123",
      "name": "my-mac",
      "region": "us-east",
      "status": "online",
      "tenant_id": "t_abc",
      "labels": { "env": "prod" },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 20 }
}

Host statuses: pending | online | offline | error | revoked

Register a host

POST /api/v1/opencomputers/hosts

{
  "id": "host_abc123",
  "name": "my-mac",
  "host_key": "hk_xxxxxxxxxxxxxxxx",
  "status": "pending",
  "tenant_id": "t_abc",
  "labels": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Get a host

GET /api/v1/opencomputers/hosts/{id}

Revoke a host

DELETE /api/v1/opencomputers/hosts/{id}

Returns 204 No Content. The host agent will no longer be able to authenticate.

Host event stream (SSE)

GET /api/v1/opencomputers/hosts/{id}/events

Streams real-time lifecycle events from the host as Server-Sent Events.

event: status_change
data: {"type":"status_change","host_id":"host_abc","data":{"status":"online"},"timestamp":"..."}

Jobs

Run shell commands on a registered host and retrieve output.

Run a job

POST /api/v1/opencomputers/hosts/{id}/exec

{
  "id": "job_xyz",
  "host_id": "host_abc123",
  "status": "completed",
  "command": "npm test",
  "args": [],
  "exit_code": 0,
  "stdout": "All tests passed.\n",
  "stderr": "",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:05Z"
}

Job statuses: queued | running | completed | failed | cancelled

List jobs

GET /api/v1/opencomputers/hosts/{id}/exec

Get a job

GET /api/v1/opencomputers/hosts/{id}/exec/{job_id}

Stream job output (SSE)

GET /api/v1/opencomputers/hosts/{id}/exec/{job_id}/stream

Streams stdout/stderr in real time while the job is running.

Cancel a job

DELETE /api/v1/opencomputers/hosts/{id}/exec/{job_id}

Returns 204 No Content.

File System

Manage files and directories on a registered host.

List response:

{
  "path": "/home/user/projects",
  "entries": [
    {
      "name": "my-app",
      "path": "/home/user/projects/my-app",
      "size": 0,
      "is_dir": true,
      "modified_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Terminal

Issue a terminal ticket

POST /api/v1/opencomputers/hosts/{id}/terminal/ticket

Returns a short-lived WebSocket authentication ticket. Connect to ws_url immediately using the ticket as a query parameter.

{
  "ticket": "tk_abc123",
  "ws_url": "wss://api.miosa.ai/opencomputers/ws/terminal?ticket=tk_abc123",
  "expires_at": "2026-01-01T00:00:30Z"
}

Desktop (VNC)

Issue a desktop ticket

POST /api/v1/opencomputers/hosts/{id}/desktop/ticket

Same shape as the terminal ticket. Connect to ws_url with the ticket to start a VNC session.

Tunnels

Expose local ports on the host over MIOSA-managed public URLs.

List tunnels

GET /api/v1/opencomputers/hosts/{id}/tunnels

Create a tunnel

POST /api/v1/opencomputers/hosts/{id}/tunnels

{
  "id": "tun_abc",
  "host_id": "host_abc123",
  "slug": "my-app-dev",
  "target_port": 3000,
  "auth_mode": "public",
  "public_url": "https://api.miosa.ai/t/my-app-dev",
  "enabled": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Get / Update / Delete a tunnel

GET /api/v1/opencomputers/hosts/{id}/tunnels/{tunnel_id}

PATCH /api/v1/opencomputers/hosts/{id}/tunnels/{tunnel_id}

DELETE /api/v1/opencomputers/hosts/{id}/tunnels/{tunnel_id} — 204 No Content

Agents

Dispatch an AI agent to complete a task autonomously on the host.

Dispatch an agent

POST /api/v1/opencomputers/hosts/{id}/agent/dispatch

{
  "id": "sess_abc",
  "host_id": "host_abc123",
  "task": "Run the test suite and fix any failing tests",
  "status": "pending",
  "max_turns": 20,
  "turns_used": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": null,
  "error": null
}

Session statuses: pending | running | completed | failed | cancelled

List / Get sessions

GET /api/v1/opencomputers/hosts/{id}/agent/sessions

GET /api/v1/opencomputers/hosts/{id}/agent/sessions/{session_id}

Stream agent events (SSE)

GET /api/v1/opencomputers/hosts/{id}/agent/sessions/{session_id}/stream

Cancel a session

DELETE /api/v1/opencomputers/hosts/{id}/agent/sessions/{session_id} — 204 No Content

Inference Clusters

Group multiple hosts to serve an LLM over an OpenAI-compatible endpoint.

List clusters

GET /api/v1/opencomputers/clusters

Create a cluster

POST /api/v1/opencomputers/clusters

{
  "id": "cl_abc",
  "name": "my-cluster",
  "model": "llama3:70b",
  "slug": "my-cluster",
  "status": "active",
  "host_ids": ["host_abc123"],
  "inference_url": "https://api.miosa.ai/inference/my-cluster/v1",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

The inference_url is OpenAI-compatible:

POST {inference_url}/chat/completions

Get / Start / Stop / Delete

GET /api/v1/opencomputers/clusters/{id}

POST /api/v1/opencomputers/clusters/{id}/start

POST /api/v1/opencomputers/clusters/{id}/stop

DELETE /api/v1/opencomputers/clusters/{id} — 204 No Content

Secrets

Store encrypted key-value secrets accessible to the host agent at runtime.

Tenant-scoped secrets

Host-scoped secrets

Create request:

{ "name": "GITHUB_TOKEN", "value": "ghp_xxx", "description": "CI token" }

Response (value is never returned):

{
  "id": "sec_abc",
  "name": "GITHUB_TOKEN",
  "description": "CI token",
  "host_id": null,
  "tenant_id": "t_abc",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

SDK Examples

Common Errors

See also

• Computers API — managed MIOSA VMs vs. BYOC hosts
• Exec API — exec on managed computers
• Regions — region slugs accepted on host creation
• Error Codes — complete error code reference