Agent Runs

Agent Runs are the durable prompt-dispatch interface for MIOSA devices. Use them when your product needs to send a natural-language task into a sandbox or computer, run it through OSA, Codex, Claude Code, Pi, Hermes, or a custom runtime, and store the result as a queryable record.

This is the API behind:

miosa sandbox prompt
the MCP agent_run tool
client.agentRuns.run(...) in the TypeScript SDK
client.agent_runs.run(...) in the Python SDK
client.AgentRuns.Run(...) in the Go SDK

Flow

Create a run

POST /api/v1/agent-runs
Authorization: Bearer msk_live_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "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

Field	Type	Required	Description
`prompt`	string	yes	Natural-language task to run.
`target_id`	UUID/string	yes	Sandbox or computer id.
`target_kind`	`sandbox` / `computer`	recommended	Target family. Defaults are inferred when using `sandbox_id` or `computer_id`.
`sandbox_id`	UUID/string	no	Shortcut for `target_id` with sandbox target.
`computer_id`	UUID/string	no	Shortcut for `target_id` with computer target.
`provider`	string	no	`osa`, `codex`, `claude`, `claude-code`, `pi`, `hermes`, or `custom`.
`command`	string	required for `custom`	Runtime command for custom providers.
`model`	string	no	Provider-specific model override.
`cwd`	string	no	Working directory, usually `/workspace`.
`timeout`	integer	no	Run timeout in seconds.
`metadata`	object	no	Product ids, UI labels, task ids, or trace metadata.

Response

{
  "data": {
    "id": "b1772e2f-89d1-4b59-9aa7-147eed4c902a",
    "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

Status	Meaning
`running`	The run record was created and the runtime is executing.
`succeeded`	The runtime completed successfully.
`failed`	The runtime returned a non-zero exit or backend error.
`canceled`	The run was canceled or interrupted.

List runs

GET /api/v1/agent-runs?target_id=41026070-9bb0-4d62-90b4-8ceeb0a131b6&limit=20
Authorization: Bearer msk_live_...

{
  "data": [
    {
      "id": "b1772e2f-89d1-4b59-9aa7-147eed4c902a",
      "target_kind": "sandbox",
      "target_id": "41026070-9bb0-4d62-90b4-8ceeb0a131b6",
      "provider": "claude-code",
      "status": "succeeded",
      "prompt": "Update the landing page..."
    }
  ]
}

Get a run

GET /api/v1/agent-runs/b1772e2f-89d1-4b59-9aa7-147eed4c902a
Authorization: Bearer msk_live_...

SDK examples

CLI

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 --provider custom --runtime-command "<command>" when you bring your own runtime harness.

Product guidance

Render the run status, provider, target, prompt, output, and request id in your task stream so users can see what the agent did.

The agent should write files and run commands inside the sandbox or computer, not build locally and upload a finished result afterward.

Store your workspace, user, project, artifact, or task ids in metadata so you can connect MIOSA runs to your product records.

Include Idempotency-Key when dispatching from queues so retries do not accidentally duplicate long-running work.