OpenComputers API

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.

Hosts may be on-premises servers, workstations, or existing machines at a hosting provider. Available operations depend on the installed agent and the host’s capabilities. See On-premises servers for hardware, connectivity, and data responsibilities.

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

Returns an object with a hosts array. Inspect each host’s id, state, capabilities, and last_heartbeat before selecting it. Use the returned ID exactly; examples below use placeholders.

{
  "hosts": [
    {
      "id": "<host-id>",
      "name": "lab-server",
      "state": "active",
      "capabilities": ["exec"],
      "last_heartbeat": "2026-09-08T12:00:00Z"
    }
  ]
}

This is an abbreviated response. A recent heartbeat and a completed operation are stronger evidence of readiness than a host record alone.

Register a host

POST /api/v1/opencomputers/hosts

Registration returns { host, host_key, control_url, warning }. The host object contains the new host ID; host_key authenticates the installed agent. Use your platform API key for REST requests, not the host key.

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

With stream: true, the POST response carries exec_chunk, exec_result, or exec_error events. Keep the connection open until the terminal result. With stream: false, a completed command returns:

{
  "job_id": "<job-id>",
  "exit_code": 0,
  "stdout": "lab-server\n",
  "stderr": ""
}

A timeout or disconnected client is not proof that the process stopped. Inspect the job and host before retrying an operation with side effects.

List jobs

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

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": "/workspace/projects",
  "entries": [
    {
      "name": "my-app",
      "path": "/workspace/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.

The same CLI surface is available with:

miosa agent run "Audit the local browser workflow" 
  --host host_abc123 
  --agent-profile arp_123 
  --json

Dispatch an agent

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

{
  "id": "sess_abc",
  "session_id": "sess_abc",
  "host_id": "host_abc123",
  "task": "Run the test suite and fix any failing tests",
  "status": "running",
  "sse_url": "/api/v1/opencomputers/hosts/host_abc123/agent/sessions/sess_abc/events",
  "optimal_session_id": "opt_sess_123",
  "agent_runtime_profile_id": "arp_123",
  "runtime_context": {
    "agent_runtime_profile": {
      "id": "arp_123",
      "runtime": "claude-code",
      "tools": ["browser", "filesystem"],
      "env_keys": ["ANTHROPIC_API_KEY"]
    }
  }
}

Session statuses: running | succeeded | failed | canceled

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}/events

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