Create and run

Base path: /api/v1/sandboxes

Create a Sandbox

POST /api/v1/sandboxes

Spawns a new sandbox VM. The API returns the sandbox record immediately after the create request is accepted; poll GET /api/v1/sandboxes/{id} or subscribe to events until state is running and ready is true.

The production alias miosa-sandbox resolves to a certified immutable artifact generation.

Auth

Bearer token required.

Request Body

If a default agent runtime profile exists for the workspace or tenant, MIOSA applies it automatically during create. Profile env vars are merged with request env vars, request env wins on conflict, profile metadata is recorded under metadata.agent_runtime_profile, and profile connectors are attached through egress placeholder tokens rather than copied as plaintext secrets.

Available templates:

Request Headers

Response - 201 Created

{
  "id": "sbx_01j9xr2t4fk8me3n5q",
  "tenant_id": "tnt_abc123",
  "owner_id": "usr_def456",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "external_workspace_id": "acct_123",
  "external_user_id": "user-456",
  "external_project_id": "project_789",
  "template_id": "miosa-sandbox",
  "image_id": "miosa-sandbox",
  "state": "provisioning",
  "ready": false,
  "size": "small",
  "resource_contract": {
    "id": "sandbox/small@v1",
    "product": "sandbox",
    "size": "small",
    "version": "v1",
    "vcpus": 2,
    "memory_mb": 4096,
    "disk_size_mb": 10240
  },
  "cpu_count": 2,
  "memory_mb": 4096,
  "disk_size_mb": 10240,
  "preview_url": "https://sbx01j9x.sandbox.miosa.ai",
  "timeout_sec": 3600,
  "timeout_remaining_ms": null,
  "always_on": false,
  "persistent": true,
  "idle_timeout_sec": 0,
  "total_runtime_sec": null,
  "metadata": {},
  "created_at": "2026-04-25T10:00:00Z",
  "started_at": null,
  "ready_at": null,
  "destroyed_at": null
}

Errors

Create and Run

POST /api/v1/sandboxes/run

Creates a sandbox, waits for it to become running, executes the first command, and returns the sandbox record plus the command result in one request. Use this for agent loops where the first useful action is “create a sandbox and run code now.”

This is the production fast path for agents that need a sandbox and an immediate first command.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/run 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: run-2026-06-09-001" 
  -d '{
    "template_id": "miosa-sandbox",
    "command": "python3 -c "print(1+1)"",
    "size": "small",
    "timeout_sec": 300,
    "wait_timeout_ms": 30000,
    "metadata": { "agent_run": "abc123" }
  }'

Request Body

/run accepts the same sandbox creation fields as POST /api/v1/sandboxes, plus:

Response - 201 Created

{
  "data": {
    "id": "sbx_01j9xr2t4fk8me3n5q",
    "state": "running",
    "ready": true,
    "template_id": "miosa-sandbox",
    "cpu_count": 2,
    "memory_mb": 4096
  },
  "exec": {
    "stdout": "2\n",
    "stderr": "",
    "exit_code": 0
  },
  "timings": {
    "server_wait_and_exec_ms": 512
  }
}

Errors

Start a Template App

POST /api/v1/sandboxes/{id}/template/start

After your platform writes generated files into /workspace, call this endpoint to run the selected template lifecycle. MIOSA runs the template install command, launches the start command in the background, stores PID/log paths, and returns the preview URL.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/template/start 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"install":true}'

Response:

{
  "data": {
    "status": "started",
    "template_id": "nextjs",
    "workdir": "/workspace",
    "preview_port": 3000,
    "preview_url": "https://abc12345.sandbox.miosa.ai",
    "logs_path": "/tmp/miosa-run/template.log",
    "pid_path": "/tmp/miosa-run/template.pid",
    "artifact_paths": ["/workspace"]
  }
}

You can override install_command, start_command, port, or workdir in the request body when your generated project needs a custom command.

Get Artifacts

GET /api/v1/sandboxes/{id}/artifacts

Returns the template artifact contract and current lifecycle metadata.

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

The response includes preview.url, preview.port, artifact paths, and template lifecycle log/PID paths.

A create request with white-label attribution and env:

curl -X POST https://api.miosa.ai/api/v1/sandboxes 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "template_id": "miosa-sandbox",
    "workspace_slug": "acme-corp",
    "workspace_name": "Acme Corp",
    "project_slug": "lead-magnet",
    "project_name": "Lead Magnet",
    "external_workspace_id": "acct_123",
    "external_user_id": "user-456",
    "external_project_id": "project_789",
    "size": "small",
    "env": {"MY_VAR": "hello"}
  }'

Custom templates

The canonical public V1 contract exposes only promoted templates returned by GET /api/v1/templates. Standalone custom-template build, validation, log, retry, and cancellation endpoints are not part of that contract. Do not make a public integration depend on those operations.