Agent Runs

Agent Runs are the prompt-dispatch interface for MIOSA sandboxes and computers. Use them when your product needs to send a natural-language task into a device, run it through OSA, Codex, Claude Code, Pi, Hermes, or a custom runtime, and receive a stable run response your UI can render.

This is the API behind:

• miosa agent run --sandbox ...
• miosa agent run --computer ...
• miosa sandbox prompt
• client.agentRuns.run(...) in the TypeScript SDK
• client.agent_runs.run(...) in the Python SDK
• miosa runs files <run-id>
• miosa runs download-file <run-id> <file-id>

Flow

Create a run

POST /api/v1/agent-runs
Authorization: Bearer msk_u_...
Content-Type: application/json

{
  "target_kind": "sandbox",
  "target_id": "41026070-9bb0-4d62-90b4-8ceeb0a131b6",
  "provider": "claude-code",
  "prompt": "Update the landing page, run tests, and leave the preview running.",
  "cwd": "/workspace",
  "timeout": 1800,
  "metadata": {
    "workspace_id": "clinic-iq",
    "task_id": "task_123"
  }
}

Request fields

Response

{
  "data": {
    "id": "b1772e2f-89d1-4b59-9aa7-147eed4c902a",
    "agent_run_group_id": "grp_123",
    "parent_agent_run_id": null,
    "orchestration_role": "coder",
    "target_kind": "sandbox",
    "target_id": "41026070-9bb0-4d62-90b4-8ceeb0a131b6",
    "provider": "claude-code",
    "prompt": "Update the landing page, run tests, and leave the preview running.",
    "status": "succeeded",
    "output": "Updated app/page.tsx and started preview on port 3000.",
    "stderr": "",
    "exit_code": 0,
    "metadata": {
      "workspace_id": "clinic-iq",
      "task_id": "task_123"
    },
    "started_at": "2026-06-14T10:30:00Z",
    "finished_at": "2026-06-14T10:31:42Z",
    "created_at": "2026-06-14T10:30:00Z",
    "updated_at": "2026-06-14T10:31:42Z"
  }
}

Status values

Artifacts

Agent runs can record generated files as artifacts. MIOSA captures declared artifact bytes into managed storage when possible, then falls back to the live target filesystem for older or unpersisted artifacts.

That matters for product UX: if persisted is true, your users can download the file even after the sandbox or computer session has stopped. If persisted is false, keep the target running until the file has been downloaded, exported, or published.

Declare artifact paths in the request body:

{
  "sandbox_id": "41026070-9bb0-4d62-90b4-8ceeb0a131b6",
  "provider": "claude-code",
  "prompt": "Create /workspace/report.html",
  "metadata": {
    "artifact_paths": ["/workspace/report.html"]
  }
}

List artifacts:

GET /api/v1/agent-runs/{run_id}/artifacts
Authorization: Bearer msk_u_...

Download one artifact:

GET /api/v1/agent-runs/{run_id}/artifacts/{artifact_id}/download
Authorization: Bearer msk_u_...

Use ?disposition=inline when embedding an HTML/PDF/image artifact in your own preview UI. The default response is an attachment.

Artifact list responses also include short-lived signed_download_url values when the backend can mint them. Use these URLs for browser-facing downloads in your own UI; they do not require exposing the user’s API key.

Artifact records include persistence metadata:

MIOSA does not expose internal storage keys or bucket URLs in the public API. Use the download endpoint or signed download URL instead.

Events

Agent Run events are durable. Use them to build timelines, progress feeds, audit trails, and orchestration UIs.

List durable events:

GET /api/v1/agent-runs/{run_id}/events
Authorization: Bearer msk_u_...

Stream events with SSE:

GET /api/v1/agent-runs/{run_id}/events?stream=true
Accept: text/event-stream
Authorization: Bearer msk_u_...

The stream sends existing durable events first, then live PubSub events. Terminal events such as command_finished, failed, and canceled close the stream.

Cancellation

POST /api/v1/agent-runs/{run_id}/cancel
Authorization: Bearer msk_u_...

Cancellation is best-effort by target type:

For sandbox process-backed runs, the run metadata includes:

{
  "agent_process": {
    "target_kind": "sandbox",
    "target_id": "41026070-9bb0-4d62-90b4-8ceeb0a131b6",
    "process_id": "proc_123",
    "pid": 123,
    "started_at": "2026-06-15T16:45:00Z"
  }
}

Run history

Use the response from POST /agent-runs for the immediate task result. For long-running browser or desktop conversations, keep using the Computer session APIs alongside Agent Runs so your UI can show both the interactive session and the per-prompt run result.

SDK examples

CLI

Use miosa agent run when the product or operator is choosing a target family:

miosa agent run "Build the dashboard, run tests, and keep the preview live." 
  --sandbox 41026070-9bb0-4d62-90b4-8ceeb0a131b6 
  --agent-profile arp_123 
  --provider claude-code 
  --cwd /workspace 
  --timeout 1800 
  --json

miosa agent run "Open the CRM and verify the lead import" 
  --computer desktop-prod-1 
  --provider osa 
  --json

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

miosa runs files <run-id> --json
miosa runs download-file <run-id> <file-id> --output ./report.html

Use miosa sandbox prompt when you already know the target is a sandbox:

miosa sandbox prompt 41026070-9bb0-4d62-90b4-8ceeb0a131b6 
  --provider claude-code 
  --cwd /workspace 
  --timeout 1800 
  --json 
  -- "Build the dashboard, run tests, and keep the preview live."

Use the API-level command field with provider: "custom" when you bring your own runtime harness. The CLI exposes the built-in providers first.

Product guidance

See also

• Agent orchestration
• Backend orchestration
• Sandboxes API
• Computers API
• CLI