# MIOSA Documentation - Full Text

Generated: 2026-05-18T15:03:14.334Z
Canonical origin: https://miosa.ai
Worker fallback origin: https://miosa.roberto-c49.workers.dev

This file is generated from src/routes/docs. It is intended for AI agents, crawlers, search indexers, and customers who need a single plain-text copy of the public documentation.

---

# MIOSA Documentation

URL: https://miosa.ai/docs
Fallback URL: https://miosa.roberto-c49.workers.dev/docs
Source: src/routes/docs/+page.md
Description: Build, preview, and deploy AI-generated apps on managed compute — one workspace API key, your customers attributed.

# MIOSA Documentation

<div class="docs-hero-actions">
  <a class="docs-hero-cta primary" href="/docs/quickstart/">Quickstart →</a>
  <a class="docs-hero-cta secondary" href="/docs/api-reference/">API Reference</a>
</div>

<p class="docs-last-updated">Last updated: <time datetime="2026-05-17">May 17, 2026</time></p>

MIOSA is the AI compute platform — a unified surface for building, deploying, and operating AI-powered apps. Spin up isolated sandboxes for code-gen agents, publish versioned deployments with rollbacks, attach managed Postgres and storage, and embed the whole thing into your own product without surfacing the MIOSA brand to your users.

## Get started with MIOSA

Spin up your first sandbox in under two minutes. Connect the [Python](/docs/sdks/python/) or [TypeScript](/docs/sdks/typescript/) SDK, attribute resources to your downstream tenants with `external_workspace_id`, and publish to a stable production URL with one call.

The [MIOSA SDK ecosystem](/docs/sdks/python/) provides idiomatic clients for five languages — Python, TypeScript, Go, Java, and Elixir — all wrapping the same REST API.

Connect your [Git workflow](/docs/develop/sandboxes/) and your AI agent can write code directly into the sandbox, with previews proxied live to your browser before you publish.

See the [Quickstart](/docs/quickstart/) for a full walkthrough, or the [Concepts](/docs/concepts/) page for the resource model.

---

## Quick references

---

## Build your applications

Use one or more of the following primitives to build your application:

- **[Sandboxes](/docs/develop/sandboxes/)**: Mutable Firecracker microVMs that boot warm in ~150 ms. Where your AI agent writes code, runs builds, and streams output.
- **[Previews](/docs/develop/previews/)**: Live, share-tokened URLs proxied straight to a sandbox port. No build step, no preview-deploy round-trip.
- **[Templates](/docs/develop/templates/)**: Pre-configured sandbox images (Next.js, React, Python, Go, more) or your own BuildSpec for reusable team templates.
- **[Files and Exec](/docs/develop/files-and-exec/)**: Write, read, and list files; spawn processes; stream stdout/stderr — all over a single REST surface.
- **[AI Agent integration](/docs/guides/agent/)**: Hook your agent loop to the sandbox API. The agent decides what to do; MIOSA executes.

---

## Use MIOSA's infrastructure

Add AI-native compute to your platform:

- **[Computers](/docs/computers/overview/)** New: Full Linux desktop VMs with screenshot, click, and type APIs for computer-use agents.
- **[Snapshots](/docs/api-reference/snapshots/)**: Fork or rewind a sandbox state. Restore in under 200 ms.
- **[Sandbox Templates BuildSpec](/docs/develop/templates/)** New: Author and publish reusable sandbox images for your team or the public catalog.
- **[Events (SSE)](/docs/api-reference/events/)**: Subscribe to live build, publish, and runtime events with short-lived auth tickets.

---

## Embed MIOSA in your platform

Run MIOSA underneath your own product without exposing the MIOSA brand to your end users:

- **[Platform overview](/docs/platform/overview/)**: How MIOSA maps one workspace key to many downstream tenants.
- **[External Attribution](/docs/platform/attribution/)**: Tag every resource with `external_workspace_id`, `external_user_id`, `external_project_id`. Usage and billing roll up automatically.
- **[Browser Tokens](/docs/platform/browser-tokens/)**: Short-lived, scoped tokens that let browser code call MIOSA APIs without exposing your workspace key.
- **[Usage and Billing](/docs/platform/usage-and-billing/)**: Per-tenant usage reports, spend caps, and billing delegation.

---

## Deploy and scale

Ship code to production, manage versions, and operate at scale:

- **[Deployments](/docs/deploy/overview/)**: The runtime object — points at one immutable Version at a time, exposes a public URL.
- **[Publishing](/docs/deploy/publishing/)**: Turn a sandbox into a Version. Builder VMs, source snapshots, immutable releases, automatic promotion.
- **[Versions](/docs/deploy/versions/)** and **[Releases](/docs/deploy/releases/)**: How immutable build artifacts and the metadata pointing at them are modeled.
- **[Runtime Instances](/docs/deploy/runtime-instances/)**: Compute pods for dynamic deployments. Horizontal scale, health checks, autoscale-to-zero (planned).
- **[Custom Domains](/docs/deploy/domains/)**: DNS + TLS for production. Per-deployment or per-Version subdomains; CNAME or apex.
- **[Rollback](/docs/deploy/rollback/)**: Point a deployment at a previous Version in one call. Sub-second.

---

## Data services

Managed data attached to your sandbox as env vars at boot:

- **[Postgres](/docs/data/postgres/)**: Provision a database; `DATABASE_URL` injected. Branch and snapshot for staging environments (planned).
- **[Storage / Buckets](/docs/data/storage/)**: S3-compatible object storage. Pre-signed URLs for browser uploads.
- **[Redis / Cache](/docs/data/redis/)** Beta: Managed Redis for sessions, caches, and queues.
- **[Auth as a Service](/docs/data/auth/)** Coming soon: User auth (signup, signin, sessions, OAuth) wired into your generated apps.
- **[Volumes](/docs/data/volumes/)**: Persistent disk attached to a Runtime Instance.

---

## Explore guides and tutorials

Extend your knowledge with deep-dives:

- **[Concepts](/docs/concepts/)**: The full resource model — Sandbox, Preview, Deployment, Version, Runtime Instance, Domain.
- **[Fundamentals](/docs/fundamentals/)**: How authentication, tenancy, and the request lifecycle work.
- **[CLI](/docs/cli/)**: Scriptable access to every MIOSA surface from your terminal.
- **[Changelog](/docs/changelog/)**: What shipped, what's next.
- **[API Reference](/docs/api-reference/)**: Every public endpoint, request/response shape.

---

[View full sitemap](/docs/api-reference/)

---

# Interactive API Reference — MIOSA Docs

URL: https://miosa.ai/docs/api
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api
Source: src/routes/docs/api/+page.svelte
Description: Browse and try every MIOSA API endpoint interactively. Covers sandboxes, computers, deployments, API keys, events, and more.

{#if !mounted} {/if}

---

# API Reference

URL: https://miosa.ai/docs/api-reference
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference
Source: src/routes/docs/api-reference/+page.md
Description: REST API reference for the MIOSA platform — base URL, auth, request/response envelopes, and the full endpoint index.

Want to browse and try endpoints without writing code?
  The <a href="/docs/api">Interactive API Reference</a> renders the full
  OpenAPI spec with an in-browser request runner — no setup required.

Every MIOSA API endpoint is REST over HTTPS, returns JSON, and follows a consistent envelope format. The SDKs wrap these endpoints — you can use them directly when you need low-level control or want to integrate from a language without an official SDK.

## Base URL
```

https://api.miosa.ai/api/v1
```

## Authentication

All requests require a Bearer token:
```http
Authorization: Bearer msk_live_...
```

MIOSA API keys (`msk_*`) and short-lived JWT tokens are both accepted. Keys are scoped to an organization and its workspaces/projects. See [API Keys](/docs/platform/api-keys/) for scope details.

## Request format

- `Content-Type: application/json` for all request bodies.
- File uploads use `multipart/form-data`.
- All field names are **snake_case**.
- Mutation requests (`POST`, `PUT`, `PATCH`, `DELETE`) should include an `Idempotency-Key` header to enable safe retries:
```http
POST /api/v1/sandboxes
Authorization: Bearer msk_live_...
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "template": "miosa-sandbox",
  "workspace_slug": "dr-smith-clinic",
  "project_slug": "lead-magnet",
  "external_workspace_id": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789"
}
```

Use a UUID v4 as the idempotency key. Repeating the same key within 24 hours returns the original response without re-executing the mutation.

## Response envelope

Single-resource responses:
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-sandbox",
    "status": "running",
    "created_at": "2026-05-17T10:00:00Z"
  }
}
```

List responses include a pagination object:
```json
{
  "data": [ { "id": "...", "name": "..." } ],
  "page": {
    "page": 1,
    "page_size": 20,
    "total": 150
  }
}
```

Pagination parameters accepted by all list endpoints:

| Parameter | Type | Default | Max |
|---|---|---|---|
| `page` | integer | 1 | — |
| `page_size` | integer | 20 | 100 |

## Error envelope

All errors follow a single shape:
```json
{
  "error": {
    "code": "sandbox_not_found",
    "message": "No sandbox with id sbx_abc exists in this workspace.",
    "request_id": "req_01jv..."
  }
}
```

Include the `request_id` when contacting support.

### HTTP status codes

| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 202 | Accepted — async operation started |
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — invalid or missing token |
| 403 | Forbidden — valid token, insufficient scope |
| 404 | Not found |
| 409 | Conflict — invalid state transition (e.g. starting a running computer) |
| 413 | Payload too large — file upload exceeds 10 MB |
| 422 | Unprocessable entity — validation error |
| 429 | Rate limited |
| 500 | Internal server error |
| 502 | Bad gateway — in-VM agent unreachable |

## Rate limits

| Scope | Limit |
|---|---|
| General API | 300 req/min per workspace |
| Auth endpoints | 20 req/min |
| Public/unauthenticated | 60 req/min |

## IDs and timestamps

All resource IDs are UUID v4. All timestamps are ISO 8601 in UTC: `2026-05-17T10:00:00Z`.

## Ownership fields

Create endpoints for resources accept the same ownership selectors:

| Field | Use |
|---|---|
| `workspace_id` | Existing MIOSA workspace UUID |
| `workspace_slug` | Existing or auto-created workspace slug |
| `workspace_name` | Display name used when auto-creating a workspace |
| `project_id` | Existing MIOSA project UUID |
| `project_slug` | Existing or auto-created project slug |
| `project_name` | Display name used when auto-creating a project |
| `external_workspace_id` | Your customer/account/workspace ID |
| `external_user_id` | Your end-user ID |
| `external_project_id` | Your project/app/document ID |

Responses include `workspace_id` and `project_id` when the resource is owned by a workspace/project. See [Ownership and Attribution](/docs/platform/attribution/).

---

## Compute


    Create, list, get, stop, and delete sandbox environments. The core compute primitive.
    [Open →](/docs/api-reference/sandboxes/)


    Run bash commands and Python code inside a running computer or sandbox.
    [Open →](/docs/api-reference/exec/)


    Server-sent events stream for long-running commands — line-by-line stdout/stderr.
    [Open →](/docs/api-reference/streaming-exec/)


    Read, write, stat, mkdir, rename, copy, and chmod files inside a computer.
    [Open →](/docs/api-reference/files/)


    Directory listings, multi-file operations, and archive upload/download.
    [Open →](/docs/api-reference/filesystem/)


    Create, restore, and delete point-in-time snapshots of a computer's disk state.
    [Open →](/docs/api-reference/snapshots/)


## Deploy


    Manage static and server deployments — create, list, get, and delete.
    [Open →](/docs/api-reference/deployments/)


    Immutable deployment versions. Each publish creates a new version.
    [Open →](/docs/api-reference/versions/)


    Promote a version to a named release (production, staging, etc.).
    [Open →](/docs/api-reference/releases/)


    Register, verify, and manage custom domains on deployments.
    [Open →](/docs/api-reference/custom-domains/)


## Computers


    Full lifecycle for desktop VM computers — create, start, stop, restart, clone, resize.
    [Open →](/docs/api-reference/computers/)


    Desktop control actions: screenshot, click, type, key, scroll, drag, hotkey, windows, accessibility tree.
    [Open →](/docs/api-reference/desktop/)


    Register your own hardware as a MIOSA computer (BYOC). One command, any machine.
    [Open →](/docs/api-reference/open-computers/)


## Platform


    Customer/client workspaces inside an organization.
    [Open →](/docs/api-reference/workspaces/)


    Apps, websites, documents, and workflows inside a workspace.
    [Open →](/docs/api-reference/projects/)


    Managed background services attached to a computer (databases, queues, etc.).
    [Open →](/docs/api-reference/services/)


    Inbound and outbound network rules for a computer.
    [Open →](/docs/api-reference/network-policy/)


    Lifecycle events emitted by computers and sandboxes — for webhooks and audit logs.
    [Open →](/docs/api-reference/events/)


    Read credit balance, list usage transactions, and top up.
    [Open →](/docs/api-reference/credits/)


    List available regions and their current capacity.
    [Open →](/docs/api-reference/regions/)


The SDKs expose every endpoint listed above. If you prefer not to make raw HTTP calls, start with the [Python SDK](https://pypi.org/project/miosa/) or [TypeScript SDK](https://www.npmjs.com/package/@miosa/sdk).

---

# Computers API

URL: https://miosa.ai/docs/api-reference/computers
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/computers
Source: src/routes/docs/api-reference/computers/+page.md
Description: API reference for creating, managing, and controlling MIOSA computers — full lifecycle, desktop control, files, metrics, and env vars.

Computers are persistent desktop VMs — full Firecracker microVMs with a Linux desktop, VNC streaming, and a resident envd agent that accepts exec, file, and desktop commands. Base path: `/api/v1/computers`.

Verbs supported: **GET** (list/get/config), **POST** (create/start/stop/restart/clone/resize), **PATCH** (update), **PUT** (update), **DELETE** (delete).

All mutation endpoints (`POST`, `PATCH`, `PUT`, `DELETE`) accept an `Idempotency-Key` header. Use a UUID v4. Repeating the same key within 24 hours returns the original response without re-executing the mutation.

Rate limit: 300 requests/min per workspace across all API endpoints. Exceeding the limit returns HTTP 429 with a `Retry-After` header.

---

## Create a Computer

**`POST /api/v1/computers`**

Creates a new computer and begins provisioning.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name |
| `template_type` | string | Yes | Template (`"miosa-desktop"`) |
| `size` | string | No | `"small"` (4GB/1CPU), `"medium"` (8GB/2CPU), `"large"` (16GB/4CPU). Default: `"small"` |
| `selected_apps` | string[] | No | Applications to install after boot |
| `workspace_id` | UUID | No | Workspace to assign this computer to. Defaults to the tenant's default workspace. |
| `workspace_slug` | string | No | Existing or auto-created workspace slug. |
| `workspace_name` | string | No | Workspace display name if auto-created. |
| `project_id` | UUID | No | Project to assign this computer to. Defaults to the workspace default project. |
| `project_slug` | string | No | Existing or auto-created project slug. |
| `project_name` | string | No | Project display name if auto-created. |
| `external_workspace_id` | string | No | Your own customer/account/workspace ID. |
| `external_user_id` | string | No | Your own end-user ID. |
| `external_project_id` | string | No | Your own project/app/document ID. |

### Response — `201 Created`
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "...",
  "owner_user_id": "...",
  "name": "my-computer",
  "slug": "my-computer",
  "template_type": "miosa-desktop",
  "size": "small",
  "vcpus": 1,
  "memory_mb": 4096,
  "status": "provisioning",
  "vm_id": null,
  "workspace_id": "660e8400-e29b-41d4-a716-446655440001",
  "project_id": "770e8400-e29b-41d4-a716-446655440002",
  "external_workspace_id": null,
  "external_user_id": null,
  "external_project_id": null,
  "sandbox_url": "https://my-computer.sandbox.miosa.ai",
  "desktop_url": "https://my-computer.sandbox.miosa.ai/desktop/index.html",
  "selected_apps": [],
  "settings": {},
  "ai_config": {},
  "agent_session_id": null,
  "agent_status": null,
  "resolution": "1280x720",
  "auto_stop": 0,
  "created_at": "2026-04-11T00:00:00Z",
  "updated_at": "2026-04-11T00:00:00Z"
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 400 | `name is required` | Missing name or template_type |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits to create |
| 422 | `TENANT_RESOLUTION_FAILED` | Cannot determine tenant for user |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-computer",
    "template_type": "miosa-desktop",
    "size": "small",
    "workspace_slug": "dr-smith-clinic",
    "workspace_name": "Dr. Smith Clinic",
    "project_slug": "records-portal",
    "project_name": "Records Portal",
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789"
  }'
```

---

## List Computers

**`GET /api/v1/computers`**

Returns all computers belonging to the authenticated user's tenant.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `workspace_id` | UUID | Filter computers to a specific workspace. Omit to return computers across all workspaces. |
| `project_id` | UUID | Filter computers to a specific project. |
| `external_workspace_id` | string | Filter by your customer/account/workspace ID. |
| `external_user_id` | string | Filter by your end-user ID. |
| `external_project_id` | string | Filter by your project/app/document ID. |

### Response — `200 OK`
```json
{
  "computers": [
    {
      "id": "...",
      "name": "my-computer",
      "status": "running",
      "size": "small",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
# All computers
curl https://api.miosa.ai/api/v1/computers \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a workspace
curl "https://api.miosa.ai/api/v1/computers?workspace_id=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a project
curl "https://api.miosa.ai/api/v1/computers?project_id=770e8400-e29b-41d4-a716-446655440002" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get a Computer

**`GET /api/v1/computers/{id}`**

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Computer ID |

### Response — `200 OK`

Full computer object (same as create response, with current status).

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 400 | `invalid computer id` | Not a valid UUID |
| 404 | `computer not found` | Does not exist or belongs to different tenant |
```bash
curl https://api.miosa.ai/api/v1/computers/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Update a Computer

**`PATCH /api/v1/computers/{id}`**

Currently supports updating `agent_session_id` only.

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `agent_session_id` | string | Link an AI agent session |

### Response — `200 OK`

Updated computer object.
```bash
curl -X PATCH https://api.miosa.ai/api/v1/computers/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_session_id": "session-uuid"}'
```

---

## Delete a Computer

**`DELETE /api/v1/computers/{id}`**

Permanently destroys the VM and removes the computer record.

### Response — `200 OK`
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `not a member of this computer` | No access to this computer |
| 404 | `computer not found` | Does not exist |
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Start a Computer

**`POST /api/v1/computers/{id}/start`**

Resumes a stopped or paused computer.

### Response — `200 OK`

Updated computer object with `status: "running"`.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits |
| 409 | `computer cannot be started from its current status` | Not in a startable state |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/start \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Stop a Computer

**`POST /api/v1/computers/{id}/stop`**

Pauses a running computer. Can be restarted later.

### Response — `200 OK`

Updated computer object with `status: "stopped"`.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `computer cannot be stopped from its current status` | Not running |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stop \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Restart a Computer

**`POST /api/v1/computers/{id}/restart`**

Stops and immediately restarts a running computer.

### Response — `200 OK`

Updated computer object.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `computer must be running to restart` | Not running |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/restart \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Auto-Stop Configuration

**`GET /api/v1/computers/{id}/auto-stop`**

### Response — `200 OK`
```json
{
  "auto_stop_seconds": 3600,
  "enabled": true
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/auto-stop \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Update Auto-Stop Configuration

**`PATCH /api/v1/computers/{id}/auto-stop`**

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `auto_stop_seconds` | integer | Seconds of inactivity before auto-stop. `0` or `null` to disable. |

### Response — `200 OK`

Updated auto-stop configuration.
```bash
curl -X PATCH https://api.miosa.ai/api/v1/computers/{id}/auto-stop \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_stop_seconds": 3600}'
```

---

## Get VNC Credentials

**`GET /api/v1/computers/{id}/vnc-credentials`**

Returns credentials for direct VNC desktop access.

### Response — `200 OK`
```json
{
  "vnc_url": "https://my-computer.sandbox.miosa.ai/desktop/index.html",
  "ws_url": "wss://my-computer.sandbox.miosa.ai/ws/vnc/550e8400-e29b-41d4-a716-446655440000?auth=stream_token",
  "token": "stream_auth_token",
  "expires_at": 1712700060,
  "computer_id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-computer"
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/vnc-credentials \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Stream Token

**`POST /api/v1/computers/{id}/stream-token`**

Returns a time-limited auth token for VNC and terminal WebSocket connections.

### Response — `200 OK`
```json
{
  "token": "stream_auth_token",
  "expires_at": 1712700060
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stream-token \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Computer URLs

**`GET /api/v1/computers/{id}/urls`**

Returns all connection URLs for the computer.

### Response — `200 OK`
```json
{
  "desktop_url": "https://my-computer.sandbox.miosa.ai/desktop/index.html",
  "vnc_url": "https://my-computer.sandbox.miosa.ai/desktop/index.html",
  "terminal_url": "wss://my-computer.sandbox.miosa.ai/ws/terminal/550e8400-e29b-41d4-a716-446655440000",
  "computer_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/urls \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## List Installed Apps

**`GET /api/v1/computers/{id}/apps`**

Returns the list of applications installed on the computer. This endpoint is proxied to the in-VM envd daemon.

### Response — `200 OK`

Proxied response from envd containing the list of installed applications.
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/apps \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Clone a Computer

**`POST /api/v1/computers/{id}/clone`**

Creates a new computer from the current state of an existing one. The source computer must be running; the clone starts in `provisioning` and progresses to `running`.

### Response — `201 Created`

Full computer object for the new clone with its own ID.

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/clone \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Resize a Computer

**`POST /api/v1/computers/{id}/resize`**

Changes the vCPU and memory allocation. The computer must be stopped first.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `size` | string | Yes | `"small"` (4 GB/1 CPU), `"medium"` (8 GB/2 CPU), `"large"` (16 GB/4 CPU) |

### Response — `200 OK`

Updated computer object with new `size`, `vcpus`, and `memory_mb`.

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/resize \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "medium"}'
```

---

## Move a Computer

**`POST /api/v1/computers/{id}/move`**

Migrates a computer to a different region. The computer must be stopped. Live migration is not supported; the computer will be moved offline.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `region` | string | Yes | Target region slug (e.g. `"us-east-ny"`) |

### Response — `200 OK`

Updated computer object with new `region`.

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/move \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region": "us-east-ny"}'
```

---

## Get Metrics

**`GET /api/v1/computers/{id}/metrics`**

Returns time-series CPU, RAM, and credit-burn metrics. Useful for dashboards and auto-stop logic.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `window` | string | Time window: `"1h"` (default), `"24h"`, `"7d"` |

### Response — `200 OK`

```json
{
  "cpu_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 12.4},
    {"ts": "2026-05-17T10:01:00Z", "value": 8.1}
  ],
  "memory_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 45.2}
  ],
  "credits_per_hour": 3
}
```

```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/metrics?window=1h" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Env Vars

Encrypted per-computer environment variables. Values are decrypted at boot and injected into the VM environment.

### List

**`GET /api/v1/computers/{id}/env`**

```bash
curl https://api.miosa.ai/api/v1/computers/{id}/env \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Create

**`POST /api/v1/computers/{id}/env`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Variable name (e.g. `DATABASE_URL`) |
| `value` | string | Yes | Plaintext value — encrypted at rest |

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/env \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "DATABASE_URL", "value": "postgres://user:pass@host/db"}'
```

### Update

**`PATCH /api/v1/computers/{id}/env/{name}`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | string | Yes | New plaintext value |

### Delete

**`DELETE /api/v1/computers/{id}/env/{name}`**

Returns `200 OK`.

---

## Port Exposure

Control per-port visibility for services running inside the computer.

### List Ports

**`GET /api/v1/computers/{id}/ports`**

### Expose a Port

**`POST /api/v1/computers/{id}/ports`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `port` | integer | Yes | Port number (1–65535) |
| `visibility` | string | Yes | `"public"`, `"private"`, or `"protected"` |

### Update Port Visibility

**`PATCH /api/v1/computers/{id}/ports/{port}`**

### Remove Port

**`DELETE /api/v1/computers/{id}/ports/{port}`**

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/ports \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000, "visibility": "public"}'
```

---

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `invalid computer id` | Path parameter is not a valid UUID |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits to start or create |
| 403 | `not a member of this computer` | No access to this computer |
| 404 | `computer not found` | Does not exist or belongs to a different tenant |
| 409 | `COMPUTER_NOT_RUNNING` | Operation requires a running computer |
| 502 | `AGENT_UNAVAILABLE` | In-VM envd agent unreachable |

---

## See also

- [Desktop API](/docs/api-reference/desktop/) — screenshot, click, type, scroll, drag, windows
- [Files API](/docs/api-reference/files/) — read, write, stat, mkdir, rename, copy, chmod, download
- [Exec API](/docs/api-reference/exec/) — bash and Python execution
- [Snapshots API](/docs/api-reference/snapshots/) — create, restore, and delete checkpoints
- [Events (SSE)](/docs/api-reference/events/) — computer lifecycle event stream
- [Regions](/docs/api-reference/regions/) — available regions for computer placement

---

# Credits API

URL: https://miosa.ai/docs/api-reference/credits
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/credits
Source: src/routes/docs/api-reference/credits/+page.md
Description: API reference for checking credit balance, transaction history, and usage data.

MIOSA uses a credit-based billing system. Credits are consumed for compute time and AI API calls.

Base path: `/api/v1/credits`

---

## Get Balance

**`GET /api/v1/credits/balance`**

Returns the current credit balance for your tenant.

### Response — `200 OK`
```json
{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "balance_credits": 850,
  "lifetime_earned": 1000,
  "lifetime_spent": 150,
  "credit_expiry_at": "2026-10-08T00:00:00Z",
  "updated_at": "2026-04-11T15:00:00Z"
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `tenant_id` | UUID | Your tenant ID |
| `balance_credits` | integer | Current available credits |
| `lifetime_earned` | integer | Total credits ever earned (purchases + promos) |
| `lifetime_spent` | integer | Total credits ever spent |
| `credit_expiry_at` | ISO 8601 | When current credits expire (180 days from purchase) |
| `updated_at` | ISO 8601 | Last balance change |

If no credit balance record exists yet, returns zeros:
```json
{
  "tenant_id": "...",
  "balance_credits": 0,
  "lifetime_earned": 0,
  "lifetime_spent": 0,
  "credit_expiry_at": null,
  "updated_at": null
}
```
```bash
curl https://api.miosa.ai/api/v1/credits/balance \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Transactions

**`GET /api/v1/credits/transactions`**

Returns paginated credit transaction history.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-based) |
| `page_size` | integer | 20 | Items per page (max: 100) |

### Response — `200 OK`
```json
{
  "transactions": [
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "user_id": "uuid",
      "computer_id": "uuid",
      "type": "spend",
      "amount_credits": -5,
      "description": "LLM API call",
      "provider": "ollama",
      "model": "nemotron-3-super",
      "input_tokens": 1500,
      "output_tokens": 500,
      "cost_usd_micros": 250,
      "inserted_at": "2026-04-11T15:00:00Z"
    },
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "user_id": "uuid",
      "computer_id": null,
      "type": "earn",
      "amount_credits": 1000,
      "description": "Starter plan monthly credits",
      "provider": null,
      "model": null,
      "input_tokens": null,
      "output_tokens": null,
      "cost_usd_micros": null,
      "inserted_at": "2026-04-01T00:00:00Z"
    }
  ],
  "total": 47,
  "page": 1,
  "page_size": 20
}
```

### Transaction Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Transaction ID |
| `tenant_id` | UUID | Tenant ID |
| `user_id` | UUID | User who triggered the transaction |
| `computer_id` | UUID | Associated computer (if applicable) |
| `type` | string | `"earn"` or `"spend"` |
| `amount_credits` | integer | Credits (positive = earned, negative = spent) |
| `description` | string | Human-readable description |
| `provider` | string | LLM provider (for AI transactions) |
| `model` | string | Model name (for AI transactions) |
| `input_tokens` | integer | Input tokens used (for AI transactions) |
| `output_tokens` | integer | Output tokens generated (for AI transactions) |
| `cost_usd_micros` | integer | Cost in microdollars (1/1,000,000 USD) |
| `inserted_at` | ISO 8601 | Transaction timestamp |
```bash
curl "https://api.miosa.ai/api/v1/credits/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Usage Summary

**`GET /api/v1/credits/usage`**

Returns daily usage rollups grouped by provider and model.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `from` | ISO 8601 | 30 days ago | Start of date range |
| `to` | ISO 8601 | Now | End of date range |

### Response — `200 OK`
```json
{
  "usage": [
    {
      "day": "2026-04-11T00:00:00Z",
      "provider": "ollama",
      "model": "nemotron-3-super",
      "credits_spent": 45,
      "input_tokens": 15000,
      "output_tokens": 5000,
      "cost_usd_micros": 2250,
      "call_count": 12
    },
    {
      "day": "2026-04-10T00:00:00Z",
      "provider": "ollama",
      "model": "nemotron-3-super",
      "credits_spent": 30,
      "input_tokens": 10000,
      "output_tokens": 3000,
      "cost_usd_micros": 1500,
      "call_count": 8
    }
  ],
  "from": "2026-03-12T00:00:00Z",
  "to": "2026-04-11T15:00:00Z"
}
```

### Usage Entry Fields

| Field | Type | Description |
|-------|------|-------------|
| `day` | ISO 8601 | Date (truncated to day) |
| `provider` | string | LLM provider |
| `model` | string | Model name |
| `credits_spent` | integer | Total credits spent that day |
| `input_tokens` | integer | Total input tokens |
| `output_tokens` | integer | Total output tokens |
| `cost_usd_micros` | integer | Total cost in microdollars |
| `call_count` | integer | Number of API calls |

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 400 | `invalid 'from' timestamp` | Not valid RFC 3339 |
| 400 | `invalid 'to' timestamp` | Not valid RFC 3339 |
| 400 | `'from' must be before 'to'` | Invalid date range |
```bash
curl "https://api.miosa.ai/api/v1/credits/usage?from=2026-04-01T00:00:00Z&to=2026-04-11T23:59:59Z" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Credit Pricing

### Compute Credits

| Size | Credits/hour |
|------|-------------|
| Small (4GB/1CPU) | 3 |
| Medium (8GB/2CPU) | 6 |
| Large (16GB/4CPU) | 12 |

### AI Credits (per 1M tokens)

| Tier | Input | Output |
|------|-------|--------|
| Standard models | 10 | 20 |
| Advanced models | 60 | 100 |

### Plans

| Plan | Price/month | Credits |
|------|------------|---------|
| Free | $0 | 100 |
| Starter | $29 | 1,000 |
| Pro | $79 | 3,000 |
| Scale | $199 | 10,000 |

Credits expire **180 days** from purchase. Unused plan credits do not roll over.

---

## See also

- [API Reference overview](/docs/api-reference/) — base URL and authentication
- [Error Codes](/docs/api-reference/errors/) — `INSUFFICIENT_CREDITS` error handling
- [Workspaces](/docs/api-reference/workspaces/) — workspace and tenant management

---

# Custom Domains API

URL: https://miosa.ai/docs/api-reference/custom-domains
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/custom-domains
Source: src/routes/docs/api-reference/custom-domains/+page.md
Description: API reference for mapping tenant-owned FQDNs to MIOSA previews with automatic TLS.

Custom domains let you expose MIOSA previews, computers, and deployments under tenant-owned FQDNs. There are four related surfaces:

- **Computer custom domains** map one fully qualified domain, such as `app.yourdomain.com`, to one Computer service.
- **Deployment custom domains** map one fully qualified domain, such as `program.drsmithclinic.com`, to one Deployment.
- **Tenant preview domains** white-label generated preview links for the whole organization. After configuration, sandbox `/expose` responses use URLs such as `https://5173-sbx01j9x.sandbox.cliniciq.dev`.
- **Workspace and project preview domains** override the organization preview domain for one client workspace or one project.

MIOSA handles verification and automatic TLS certificate issuance via Caddy on-demand TLS.

Nested base paths: `/api/v1/computers/{id}/domains` and `/api/v1/deployments/{id}/domains`.

Flat frontend-compatible base path: `/api/v1/custom-domains`.

Custom domains must not end in `miosa.ai` — that namespace is reserved for platform subdomains. Use a domain you control.

---

## Quick Start
```typescript

const client = new Miosa();

// 1. Register the domain
const domain = await client.domains.register(computerId, {
  domain: 'app.yourcompany.com',
});
console.log(domain.verificationTarget); // e.g. "verify.miosa.ai"

// 2. Add a CNAME record at your DNS provider:
//    app.yourcompany.com → verify.miosa.ai

// 3. Trigger verification
const verified = await client.domains.verify(computerId, domain.id);
console.log(verified.status); // "verified" or "failed"
```
```bash
# Register
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.yourcompany.com"}'
```

---

## Endpoints

### Computer custom domains

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/computers/{id}/domains` | Register a custom domain |
| `GET` | `/computers/{id}/domains` | List domains for a computer |
| `POST` | `/computers/{id}/domains/{domain_id}/verify` | Trigger DNS verification |
| `DELETE` | `/computers/{id}/domains/{domain_id}` | Remove a domain |

### Deployment custom domains

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/deployments/{id}/domains` | Register a custom domain |
| `GET` | `/deployments/{id}/domains` | List domains for a deployment |

### Flat custom domains

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/custom-domains?computer_id={id}` | List domains for a computer |
| `GET` | `/custom-domains?deployment_id={id}` | List domains for a deployment |
| `POST` | `/custom-domains` | Register a domain with `computer_id` or `deployment_id` |
| `DELETE` | `/custom-domains/{id}` | Remove a domain |

### Tenant preview domains

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/tenant/preview-domain` | Read the tenant preview domain |
| `PUT` | `/tenant/preview-domain` | Set the tenant preview domain |
| `DELETE` | `/tenant/preview-domain` | Clear the tenant preview domain |
| `GET` | `/tenant/preview-domain/verify` | Check DNS/TLS readiness |

### Workspace and project preview domains

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/workspaces/{id}/preview-domain` | Read the workspace preview domain |
| `PUT` | `/workspaces/{id}/preview-domain` | Set the workspace preview domain |
| `DELETE` | `/workspaces/{id}/preview-domain` | Clear the workspace preview domain |
| `GET` | `/workspaces/{id}/preview-domain/verify` | Check workspace DNS readiness |
| `GET` | `/projects/{id}/preview-domain` | Read the project preview domain |
| `PUT` | `/projects/{id}/preview-domain` | Set the project preview domain |
| `DELETE` | `/projects/{id}/preview-domain` | Clear the project preview domain |
| `GET` | `/projects/{id}/preview-domain/verify` | Check project DNS readiness |

---

## White-label Managed Links

Use a tenant preview domain when generated app/artifact preview URLs should use your organization's domain instead of the platform default `miosa.app`.
```bash
curl -X PUT https://api.miosa.ai/api/v1/tenant/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview_domain":"preview.yourcompany.com"}'
```

Then expose a sandbox port:
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/expose \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":5173}'
```

Response:
```json
{
  "url": "https://5173-sbx01j9x.sandbox.preview.yourcompany.com"
}
```

For a client workspace domain:
```bash
curl -X PUT https://api.miosa.ai/api/v1/workspaces/$WORKSPACE_ID/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview_domain":"drsmithclinic.com"}'
```

For a single project domain:
```bash
curl -X PUT https://api.miosa.ai/api/v1/projects/$PROJECT_ID/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview_domain":"program.drsmithclinic.com"}'
```

DNS must delegate wildcard traffic to the MIOSA preview router:

| Record type | Name | Value | Used for |
|---|---|---|---|
| `CNAME` | `*` | `proxy.miosa.ai` | `https://{slug}.{domain}` managed deployment/computer/default preview URLs |
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` | `https://{port}-{slug}.sandbox.{domain}` sandbox port previews |

If no preview domain is configured, MIOSA returns the managed `miosa.app` fallback. This fallback remains available even after custom domains are attached.

Preview-domain precedence is project → workspace → tenant → MIOSA fallback. Exact deployment/computer custom domains still take priority over preview-domain inheritance.

---

## Register a Domain

**`POST /api/v1/computers/{id}/domains`**

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domain` | string | Yes | Fully qualified domain name. RFC 1123 hostname, max 253 chars |

### Response — `201 Created`
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "...",
    "deployment_id": null,
    "tenant_id": "...",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "fqdn": "app.yourcompany.com",
    "status": "pending",
    "verification_target": "verify.miosa.ai",
    "verified_at": null,
    "tls_issued_at": null,
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789",
    "created_at": "2026-04-11T00:00:00Z",
    "updated_at": "2026-04-11T00:00:00Z"
  }
}
```

### Status Values

| Status | Description |
|--------|-------------|
| `pending` | Registered; awaiting DNS verification |
| `verified` | CNAME confirmed; Caddy may issue a cert |
| `active` | TLS certificate issued and in use |
| `failed` | Verification or TLS issuance failed |
| `removed` | Domain detached (soft marker before deletion) |

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `has already been taken` | FQDN already registered (globally unique) |
| 422 | Validation error | Invalid FQDN format or ends with `miosa.ai` |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "preview.yourapp.io"}'
```

### Register a deployment domain
```bash
curl -X POST https://api.miosa.ai/api/v1/deployments/{id}/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "program.drsmithclinic.com"}'
```

Deployment domains inherit `workspace_id`, `project_id`, and external attribution from the deployment.

---

## List Domains

**`GET /api/v1/computers/{id}/domains`**

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "...",
      "fqdn": "app.yourcompany.com",
      "status": "active",
      "verified_at": "2026-04-11T01:00:00Z",
      "tls_issued_at": "2026-04-11T01:05:00Z",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Verify a Domain

**`POST /api/v1/computers/{id}/domains/{domain_id}/verify`**

Checks that the CNAME record at `fqdn` resolves to `verification_target`. On success the domain transitions to `"verified"` and Caddy will issue a TLS certificate on the next HTTPS request to the FQDN.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Computer ID |
| `domain_id` | UUID | Domain ID |

### Response — `200 OK`
```json
{
  "data": {
    "id": "...",
    "fqdn": "app.yourcompany.com",
    "status": "verified",
    "verified_at": "2026-04-11T01:00:00Z"
  }
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `domain is already verified` | Already completed |
| 422 | `CNAME not found` | DNS record missing or not yet propagated |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains/{domain_id}/verify \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Remove a Domain

**`DELETE /api/v1/computers/{id}/domains/{domain_id}`**

Detaches the domain from the computer. The certificate is not revoked immediately (Caddy lets it expire naturally), but the domain will no longer route to the computer.

### Response — `200 OK`
```json
{
  "data": { "id": "...", "fqdn": "app.yourcompany.com", "status": "removed" }
}
```
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/domains/{domain_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## DNS Setup Reference

After registering a domain, add the following DNS record at your registrar or DNS provider:

| Record | Host | Value |
|--------|------|-------|
| CNAME | `app` (or full subdomain) | `verify.miosa.ai` |

DNS propagation typically takes 1–60 minutes. Call `verify` once propagation is complete. If verification fails, wait a few minutes and retry — the endpoint is idempotent.

---

## Common Recipes

### Automate full domain onboarding
```python

from miosa import Miosa

client = Miosa()

domain = client.domains.register(computer_id, fqdn="api.yourcompany.com")
print(f"Add CNAME: {domain.fqdn} → {domain.verification_target}")
print("Waiting for DNS propagation...")

while True:
    result = client.domains.verify(computer_id, domain.id)
    if result.status == "verified":
        print("Domain verified! TLS will be issued on first HTTPS request.")
        break
    elif result.status == "failed":
        raise RuntimeError("Verification failed — check your DNS records.")
    time.sleep(30)
```

### List all pending domains (potential stuck ACME issuances)
```typescript
const computers = await client.computers.list();
for (const computer of computers.data) {
  const { data: domains } = await client.domains.list(computer.id);
  const pending = domains.filter(d => d.status === 'pending');
  if (pending.length > 0) {
    console.log(`${computer.name}: ${pending.length} domain(s) pending verification`);
  }
}
```

---

# API Reference / Deployments

URL: https://miosa.ai/docs/api-reference/deployments
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/deployments
Source: src/routes/docs/api-reference/deployments/+page.md
Description: REST API for the Deployment resource — create, list, get, update, delete, publish, rollback.

A **Deployment** is the stable production object for a published app/site/API. See [Deploy / Overview](/docs/deploy/overview/) for the conceptual model.

Sandbox-sourced create + publish + rollback are part of Phase 2B / 3 of the deployment refactor. Today, the backward-compatible `POST /api/v1/sandboxes/:id/deploy` route exists and uses the sandbox-backed bridge. Endpoints below show the steady-state shape; in-progress endpoints are marked.

## Endpoints
```http
POST   /api/v1/projects/:project_id/deployments        # Phase 2B
GET    /api/v1/deployments
GET    /api/v1/deployments/:id
PATCH  /api/v1/deployments/:id
DELETE /api/v1/deployments/:id
POST   /api/v1/deployments/:id/publish                 # Phase 2B
POST   /api/v1/deployments/:id/rollback                # Phase 2B
POST   /api/v1/sandboxes/:id/deploy                    # Backward-compat
```

All endpoints require `Authorization: Bearer &lt;msk_*&gt;`. Mutations should include an `Idempotency-Key` header.

## Create
```http
POST /api/v1/projects/:project_id/deployments
```

Body:
```json
{
  "name": "Smile Dental Landing",
  "source_type": "sandbox",
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "smile-dental-landing",
  "project_name": "Smile Dental Landing",
  "external_workspace_id": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789",
  "metadata": { }
}
```

Ownership fields accepted on create: `workspace_id`, `workspace_slug`, `workspace_name`, `project_id`, `project_slug`, `project_name`, `external_workspace_id`, `external_user_id`, and `external_project_id`.

Scopes: `deployments:write`.

## Publish
```http
POST /api/v1/deployments/:id/publish
```

Body:
```json
{
  "source_sandbox_id": "sbx_...",
  "kind": "auto",
  "environment": "production",
  "output_path": "/workspace",
  "build_command": "npm run build",
  "run_command": "npm start",
  "port": 3000,
  "health_check_path": "/_health",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "external_workspace_id": "clinic_123"
}
```

Server-side behavior is documented in [Publishing](/docs/deploy/publishing/).

Response:
```json
{
  "data": {
    "deployment": {
      "id": "dep_...",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "660e8400-e29b-41d4-a716-446655440001",
      "active_version_id": "ver_...",
      "state": "running",
      "public_url": "https://smile-dental.cliniciq.miosa.app"
    },
    "version": {
      "id": "ver_...",
      "kind": "static",
      "state": "ready",
      "artifact_uri": "s3://...",
      "artifact_sha256": "...",
      "source_sha256": "..."
    },
    "services": [
      { "id": "svc_...", "type": "static_web", "state": "healthy" }
    ],
    "promoted": true
  }
}
```

## List
```http
GET /api/v1/deployments
GET /api/v1/deployments?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/deployments?project_id=660e8400-e29b-41d4-a716-446655440001
GET /api/v1/deployments?external_workspace_id=clinic_123
GET /api/v1/deployments?external_user_id=dr-smith-456
GET /api/v1/deployments?state=running
```

All filters are organization-scoped server-side. See [Ownership and Attribution](/docs/platform/attribution/).

## Get
```http
GET /api/v1/deployments/:id
```

Returns the full deployment row including `workspace_id`, `project_id`, `active_version_id`, attribution, and metadata.

## Update
```http
PATCH /api/v1/deployments/:id
```

Body: any subset of mutable fields (`name`, `auto_deploy`, `metadata`, `external_*`).

## Rollback
```http
POST /api/v1/deployments/:id/rollback
```

Body:
```json
{
  "version_id": "ver_..."
}
```

See [Rollback](/docs/deploy/rollback/).

## Delete
```http
DELETE /api/v1/deployments/:id
```

Tears down runtime instances, removes routes, marks the deployment deleted. Versions and releases are retained per the retention policy.

## See also

- [Versions](/docs/api-reference/versions/) — version sub-resource
- [Releases](/docs/api-reference/releases/) — build artifact reference (Phase 2B)
- [Custom Domains](/docs/api-reference/custom-domains/) — domain sub-resource
- [Deploy / Overview](/docs/deploy/overview/) — conceptual model

---

# Desktop API

URL: https://miosa.ai/docs/api-reference/desktop
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/desktop
Source: src/routes/docs/api-reference/desktop/+page.md
Description: API reference for all desktop control endpoints — screenshot, mouse, keyboard, clipboard, windows, accessibility tree.

Desktop control endpoints proxy commands to the resident envd agent inside the computer VM via the MIOSA control plane. All coordinates are in screen pixels (0,0 = top-left).

Base path: `/api/v1/computers/{id}/desktop`

All desktop endpoints require the computer to be in `"running"` status. Returns `409 COMPUTER_NOT_RUNNING` if the computer is stopped or provisioning.

Rate limit: 300 req/min per workspace. Individual desktop actions are fast but high-frequency AI agents should batch operations where possible.

---

## Screenshot

**`GET /api/v1/computers/{id}/desktop/screenshot`**

Captures the full desktop as a PNG image.

### Response — `200 OK`

Binary PNG data with `Content-Type: image/png`.
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/desktop/screenshot \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  --output screenshot.png
```

---

## Screenshot Region

**`POST /api/v1/computers/{id}/desktop/screenshot/region`**

Captures a rectangular region of the screen.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | Left edge X coordinate |
| `y` | integer | Yes | Top edge Y coordinate |
| `width` | integer | Yes | Width in pixels |
| `height` | integer | Yes | Height in pixels |

### Response — `200 OK`

Binary PNG data.
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/screenshot/region \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 0, "y": 0, "width": 800, "height": 600}' \
  --output region.png
```

---

## Click

**`POST /api/v1/computers/{id}/desktop/click`**

Performs a mouse click at the specified coordinates.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | X coordinate |
| `y` | integer | Yes | Y coordinate |
| `button` | string | No | `"left"` (default), `"right"`, `"middle"` |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/click \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300}'
```

---

## Double-Click

**`POST /api/v1/computers/{id}/desktop/double-click`**

Performs a double-click at the specified coordinates.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | X coordinate |
| `y` | integer | Yes | Y coordinate |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/double-click \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300}'
```

---

## Type Text

**`POST /api/v1/computers/{id}/desktop/type`**

Types a string of text as keyboard input.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | Text to type |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/type \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, World!"}'
```

---

## Key Press

**`POST /api/v1/computers/{id}/desktop/key`**

Presses a key or key combination.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | string | Yes | Key name or combination |

Key combinations use `+` as separator: `"ctrl+c"`, `"alt+Tab"`, `"ctrl+shift+t"`.

### Common Keys

| Key | Value |
|-----|-------|
| Enter | `Return` |
| Tab | `Tab` |
| Escape | `Escape` |
| Backspace | `BackSpace` |
| Delete | `Delete` |
| Space | `space` |
| Arrows | `Up`, `Down`, `Left`, `Right` |
| Function | `F1`...`F12` |
| Home/End | `Home`, `End` |
| Page Up/Down | `Page_Up`, `Page_Down` |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/key \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "ctrl+c"}'
```

---

## Scroll

**`POST /api/v1/computers/{id}/desktop/scroll`**

Scrolls the mouse wheel at the specified position.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | X coordinate |
| `y` | integer | Yes | Y coordinate |
| `direction` | string | Yes | `"up"` or `"down"` |
| `amount` | integer | No | Number of scroll steps (default: 3) |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/scroll \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300, "direction": "down", "amount": 5}'
```

---

## Drag

**`POST /api/v1/computers/{id}/desktop/drag`**

Performs a click-and-drag from one point to another.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `start_x` | integer | Yes | Starting X coordinate |
| `start_y` | integer | Yes | Starting Y coordinate |
| `end_x` | integer | Yes | Ending X coordinate |
| `end_y` | integer | Yes | Ending Y coordinate |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/drag \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_x": 100, "start_y": 200, "end_x": 400, "end_y": 500}'
```

---

## Wait

**`POST /api/v1/computers/{id}/desktop/wait`**

Server-side pause. Holds the connection for the specified duration before responding.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `seconds` | number | No | Seconds to wait (default: 1, max: 30) |

### Response — `200 OK`
```json
{
  "success": true,
  "waited_seconds": 2
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/wait \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds": 2}'
```

---

## List Windows

**`GET /api/v1/computers/{id}/desktop/windows`**

Returns a list of open windows on the desktop.

### Response — `200 OK`
```json
{
  "windows": [
    {
      "id": "0x2200003",
      "title": "Terminal - user@computer",
      "class": "Xfce4-terminal",
      "x": 100,
      "y": 50,
      "width": 800,
      "height": 600
    }
  ]
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/desktop/windows \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Focus Window

**`POST /api/v1/computers/{id}/desktop/window/focus`**

Brings a window to the foreground.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `window_id` | string | Yes | Window ID from the list windows response |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/window/focus \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"window_id": "0x2200003"}'
```

---

## Launch Application

**`POST /api/v1/computers/{id}/desktop/launch`**

Launches an application by name or command.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `app` | string | Yes | Application name or command (e.g., `"firefox"`, `"xfce4-terminal"`) |

### Response — `200 OK`
```json
{
  "success": true
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/launch \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app": "firefox"}'
```

---

## Cursor Position

**`GET /api/v1/computers/{id}/desktop/cursor`**

Returns the current mouse cursor coordinates.

### Response — `200 OK`
```json
{
  "x": 500,
  "y": 300
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/desktop/cursor \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Hotkey

**`POST /api/v1/computers/{id}/desktop/hotkey`**

Presses a hotkey combination. Functionally equivalent to `key` but uses a dedicated endpoint for named combinations.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keys` | string[] | Yes | Ordered list of keys to press simultaneously (e.g. `["ctrl", "shift", "t"]`) |

### Response — `200 OK`
```json
{"success": true}
```

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/hotkey \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["ctrl", "shift", "t"]}'
```

---

## Key Down / Key Up

**`POST /api/v1/computers/{id}/desktop/key-down`**

**`POST /api/v1/computers/{id}/desktop/key-up`**

Send individual key-down or key-up events. Use these for precise control when holding a modifier key while performing another action.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | string | Yes | Key name (same format as `key` endpoint) |

### Response — `200 OK`
```json
{"success": true}
```

---

## Mouse Down / Mouse Up

**`POST /api/v1/computers/{id}/desktop/mouse-down`**

**`POST /api/v1/computers/{id}/desktop/mouse-up`**

Send individual mouse-button-down or mouse-button-up events. Use for custom drag sequences or long-press interactions.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | X coordinate |
| `y` | integer | Yes | Y coordinate |
| `button` | string | No | `"left"` (default), `"right"`, `"middle"` |

### Response — `200 OK`
```json
{"success": true}
```

---

## Move Mouse

**`POST /api/v1/computers/{id}/desktop/move`**

Moves the mouse cursor to the specified position without clicking.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | Target X coordinate |
| `y` | integer | Yes | Target Y coordinate |

### Response — `200 OK`
```json
{"success": true}
```

---

## Clipboard

### Get Clipboard

**`GET /api/v1/computers/{id}/desktop/clipboard`**

Returns the current clipboard contents.

### Response — `200 OK`
```json
{"text": "Hello, World!"}
```

### Set Clipboard

**`POST /api/v1/computers/{id}/desktop/clipboard`**

Sets the clipboard contents.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | Text to place in the clipboard |

### Response — `200 OK`
```json
{"success": true}
```

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/desktop/clipboard \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, World!"}'
```

---

## Screen Size

**`GET /api/v1/computers/{id}/desktop/screen-size`**

Returns the current desktop resolution.

### Response — `200 OK`
```json
{"width": 1280, "height": 720}
```

---

## Environment

**`GET /api/v1/computers/{id}/desktop/environment`**

Returns desktop session metadata — display server, session type, active user, and desktop environment name.

---

## Set Wallpaper

**`POST /api/v1/computers/{id}/desktop/wallpaper`**

Sets the desktop wallpaper. Supports per-tenant white-label branding.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Publicly accessible URL of the image to set as wallpaper |

---

## Accessibility Tree

**`GET /api/v1/computers/{id}/desktop/accessibility-tree`**

Returns the AT-SPI accessibility tree for the current desktop state. The tree describes all visible UI elements with their roles, labels, states, and bounding boxes. Use this for element discovery when exact coordinates are unknown.

### Response — `200 OK`
```json
{
  "tree": {
    "role": "application",
    "name": "Firefox",
    "children": [
      {
        "role": "button",
        "name": "Close",
        "x": 1260,
        "y": 10,
        "width": 20,
        "height": 20
      }
    ]
  }
}
```

---

## Window Management

### List Windows

See [List Windows](#list-windows) above.

### Window Size

**`GET /api/v1/computers/{id}/desktop/window/{window_id}/size`**

Returns the width and height of a specific window.

### Window Position

**`GET /api/v1/computers/{id}/desktop/window/{window_id}/position`**

Returns the x,y position of a specific window.

### Resize Window

**`POST /api/v1/computers/{id}/desktop/window/{window_id}/resize`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `width` | integer | Yes | New width in pixels |
| `height` | integer | Yes | New height in pixels |

### Move Window

**`POST /api/v1/computers/{id}/desktop/window/{window_id}/move`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | integer | Yes | New X position |
| `y` | integer | Yes | New Y position |

### Maximize Window

**`POST /api/v1/computers/{id}/desktop/window/{window_id}/maximize`**

### Minimize Window

**`POST /api/v1/computers/{id}/desktop/window/{window_id}/minimize`**

### Close Window

**`POST /api/v1/computers/{id}/desktop/window/{window_id}/close`**

All window management endpoints return `{"success": true}` on `200 OK`.

---

## Common Errors

All desktop endpoints share these error responses:

| Status | Code | Description |
|--------|------|-------------|
| 400 | `invalid computer id` | UUID format invalid |
| 403 | `FORBIDDEN` | Not a member of this computer |
| 404 | `NOT_FOUND` | Computer does not exist |
| 409 | `COMPUTER_NOT_RUNNING` | Computer is stopped or provisioning |
| 502 | `AGENT_UNAVAILABLE` | Cannot reach the in-VM agent (envd) |

---

## See also

- [Computers API](/docs/api-reference/computers/) — create, start, stop, clone computers
- [Exec API](/docs/api-reference/exec/) — run bash/Python without desktop interaction
- [Files API](/docs/api-reference/files/) — read and write files in the VM
- [Error Codes](/docs/api-reference/errors/) — complete error code reference

---

# Error Codes

URL: https://miosa.ai/docs/api-reference/errors
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/errors
Source: src/routes/docs/api-reference/errors/+page.md
Description: Every error code the MIOSA API returns, what it means, and how to handle it.

Every MIOSA API error follows a single envelope shape. The HTTP status indicates the broad class; the `code` field is the machine-readable reason.

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "sandbox not found",
    "request_id": "req_01jv..."
  }
}
```

Include `request_id` whenever you contact support. It correlates the request across all internal services.

---

## Authentication errors

Returned by the `ApiKeyAuth` plug before the request reaches any controller.

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `invalid_token` | 401 | `Authorization` header missing, malformed, or the key/JWT is invalid | Verify the header is `Authorization: Bearer msk_...` |
| `invalid_token` | 401 | Refresh token used on a non-auth endpoint | Use a workspace API key (`msk_*`), not a refresh token |
| `insufficient_scope` | 403 | Key exists but lacks the required scope for this operation | Adjust key scopes in the dashboard |
| `rate_limit_exceeded` | 429 | Too many requests from this key or IP | Back off and retry after `Retry-After` seconds |

All API endpoints are rate-limited. General API: 300 req/min per workspace. Auth endpoints: 20 req/min. Retry-After is included in 429 responses.

---

## General resource errors

These codes appear across all resource types (computers, sandboxes, deployments, workspaces, etc.).

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `NOT_FOUND` | 404 | Resource does not exist or belongs to a different tenant | Confirm the ID and that the key's tenant owns the resource |
| `FORBIDDEN` | 403 | Authenticated but not authorized to access this resource | Check membership or ownership |
| `INVALID_ID` | 400 | Path parameter is not a valid UUID | Use a UUID v4 ID, not a slug or name |
| `MISSING_PARAM` | 400 | A required request body field is absent | Check the field name in the request body schema |
| `VALIDATION_ERROR` | 422 | One or more fields failed schema validation | Inspect `details` for per-field messages |
| `VALIDATION_FAILED` | 422 | Changeset validation failed (alias of `VALIDATION_ERROR` in some controllers) | Inspect `details` |
| `TENANT_RESOLUTION_FAILED` | 422 | Cannot determine the tenant for the authenticated identity | The API key may belong to a workspace that has been deleted or suspended |
| `INTERNAL_ERROR` | 500 | Unexpected server-side error | Retry with exponential backoff; report if persistent |

---

## Sandbox errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits to provision this sandbox | Top up credits in the dashboard or reduce the resource request |
| `SANDBOX_LIMIT_REACHED` | 409 | Tenant has hit the concurrent sandbox cap (default 10) | Destroy idle sandboxes or contact support to raise the limit |
| `SANDBOX_NOT_RUNNING` | 409 | Operation requires the sandbox to be in `running` state | Wait until state is `running`; poll `GET /sandboxes/{id}` or subscribe to events |
| `AGENT_UNAVAILABLE` | 502 | The in-VM envd agent is reachable but not responding | Wait and retry; if persistent, destroy and recreate the sandbox |
| `INVALID_TEMPLATE` | 400 | `template_id` is not a recognized template | Use `GET /api/v1/sandbox-templates` to list valid IDs |
| `MISSING_PATH` | 400 | `path` field is required but absent | Include `path` in the request body |
| `INVALID_PATH` | 400 | `path` is not a valid absolute filesystem path | Use an absolute path (starts with `/`) |
| `MISSING_FILE` | 400 | Multipart upload missing the `file` part | Include the file part in the multipart form |
| `INVALID_BODY` | 400 | Request body could not be parsed or decoded | Verify JSON or base64 encoding |
| `MISSING_MODE` | 400 | `chmod` call missing `mode` field | Include an octal mode string, e.g. `"0644"` |
| `INVALID_PORT` | 422 | Expose port is outside `1`–`65535` | Use a port in the valid range |
| `MISSING_PARAM` | 400 | `port` omitted on `/expose` and template has no default preview port | Provide `port` explicitly |
| `SANDBOX_NOT_RUNNING` | 409 | `/deploy` called but sandbox is not running | Confirm sandbox state before promoting |
| `SANDBOX_RUNTIME_UNAVAILABLE` | 409 | Sandbox is marked running but has no VM IP yet | Retry after a few seconds |

---

## Sandbox template build errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `TEMPLATE_NOT_FOUND` | 404 | Template ID does not exist | Verify the template ID |
| `BUILD_NOT_FOUND` | 404 | Build record does not exist | Verify the build ID |
| `BUILD_ALREADY_TERMINAL` | 409 | Cannot cancel a build that is already `ready`, `failed`, or `cancelled` | No action needed; build is in a terminal state |
| `BUILD_NOT_RETRYABLE` | 409 | Build is not in a state that allows retry (`failed` or `cancelled` only) | Only `failed` or `cancelled` builds may be retried |
| `UNAUTHORIZED` | 401 | SSE ticket missing, invalid, or expired | Re-issue a ticket via `POST /auth/sse-ticket` and reconnect |

---

## Computer errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits to start this computer | Top up credits |
| `COMPUTER_NOT_RUNNING` | 409 | Desktop or exec operation requires a running computer | Start the computer first |
| `COMPUTER_NOT_FOUND` | 404 | Computer does not exist in this tenant | Verify the computer ID |
| `AGENT_UNAVAILABLE` | 502 | In-VM envd agent unreachable | Computer may be starting; retry after a few seconds |

---

## Deployment errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `DEPLOYMENT_NOT_FOUND` | 404 | Deployment ID does not exist | Verify the deployment ID |
| `VALIDATION_ERROR` | 422 | Deployment fields failed validation | Check `details` for field-level messages |
| `SANDBOX_NOT_RUNNING` | 409 | Publishing requires a running sandbox | Confirm sandbox state |
| `RUNTIME_TARGET_UNAVAILABLE` | 409 | Sandbox has no IP yet — cannot route to it | Retry after a few seconds |
| `RUNTIME_LOGS_UNAVAILABLE` | 502 | Cannot fetch runtime logs from the sandbox | Retry or check sandbox health |
| `EMPTY_ARTIFACT` | 422 | Publish output contained no files | Verify your build step produces output files |
| `SERVICE_UNAVAILABLE` | 503 | A required internal service (e.g. encryption) is not configured | Contact support |

---

## Snapshot errors

Snapshots are accessed under `/api/v1/computers/{id}/snapshots` and `/api/v1/sandboxes/{id}/snapshots`.

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `NOT_FOUND` (snapshot) | 404 | Snapshot does not exist or belongs to a different computer | Verify snapshot ID and computer ID |
| `FORBIDDEN` | 403 | Authenticated tenant does not own this snapshot | Check ownership |
| `already_deleted` | 409 | Snapshot has already been deleted | No action; already in terminal state |
| `snapshot is not in ready state` | 409 | Restore attempted before snapshot reached `ready` | Poll snapshot status until `ready` |
| `missing sse ticket` | 401 | SSE stream opened without a ticket | Issue a ticket via `POST /auth/sse-ticket` first |

---

## Custom domain errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `DOMAIN_NOT_FOUND` | 404 | Custom domain record not found | Verify the domain ID |
| `COMPUTER_NOT_FOUND` | 404 | The computer this domain is attached to was not found | Verify the computer ID |
| `FORBIDDEN` | 403 | Domain belongs to a different tenant | Verify ownership |
| `VALIDATION_FAILED` | 422 | `fqdn` missing or invalid | Include a valid fully-qualified domain name |

---

## Workspace errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `VALIDATION_FAILED` | 422 | Workspace creation or update fields are invalid | Inspect `details` |
| `TEMPLATE_NAME_TAKEN` | 409 | A template with that name already exists in this workspace | Choose a different name |

---

## Rate-limit and quota errors

| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| `rate_limit_exceeded` | 429 | General API rate limit hit | Respect the `Retry-After` response header |
| `SANDBOX_LIMIT_REACHED` | 409 | Concurrent sandbox cap reached | Destroy idle sandboxes or upgrade plan |
| `INSUFFICIENT_CREDITS` | 402 | Credit balance depleted | Purchase credits from the billing dashboard |

All 429 responses include a `Retry-After` header (seconds). Honor it — repeated violations may result in temporary IP blocks.

---

## See also

- [API Reference overview](/docs/api-reference/) — base URL, auth, and request format
- [Sandboxes](/docs/api-reference/sandboxes/) — sandbox lifecycle and file operations
- [Computers](/docs/api-reference/computers/) — computer CRUD and desktop control
- [Deployments](/docs/api-reference/deployments/) — deployment and version errors

---

# Events (SSE)

URL: https://miosa.ai/docs/api-reference/events
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/events
Source: src/routes/docs/api-reference/events/+page.md
Description: Server-Sent Event streams for real-time updates from sandboxes, computers, deployments, and builds.

MIOSA exposes SSE streams for resources that produce timed events: sandboxes, computer sessions, deployment builds, sandbox-template builds, and computer logs. All streams follow the same authentication and envelope pattern.

---

## Authentication pattern

The browser `EventSource` API cannot send an `Authorization` header. Use the two-step ticket flow for all SSE connections:
Diagram:
sequenceDiagram
  participant Client
  participant MIOSA API
  Client->>MIOSA API: POST /api/v1/auth/sse-ticket<br/>Authorization: Bearer msk_u_...
  MIOSA API-->>Client: { "ticket": "sset_..." }
  Client->>MIOSA API: GET <stream-endpoint>?ticket=sset_...<br/>Accept: text/event-stream
  MIOSA API-->>Client: text/event-stream (open connection)

**Step 1 — Mint a ticket:**
```bash
curl -X POST https://api.miosa.ai/api/v1/auth/sse-ticket \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json"
# Response: { "ticket": "sset_01hx9z...", "expires_in": 60 }
```

Tickets are single-use and expire in 60 seconds. Mint one immediately before opening the `EventSource`.

**Step 2 — Open the stream:**
```bash
curl -N "https://api.miosa.ai/api/v1/sandboxes/{id}/events?ticket=sset_01hx9z..." \
  -H "Accept: text/event-stream"
```

---

## Live SSE streams

| Stream | Endpoint | Description |
|---|---|---|
| Sandbox events | `GET /sandboxes/{id}/events` | Exec progress, file change notifications, preview readiness |
| Computer agent events | `GET /computers/{id}/agent/events` | Agent task progress and computer lifecycle |
| Computer logs | `GET /computers/{id}/logs/stream` | stdout/stderr from in-VM agent processes |
| Sandbox logs | `GET /sandboxes/{id}/logs/stream` | stdout/stderr from sandbox template lifecycle |
| Build events | `GET /sandbox-template-builds/{id}/logs/stream` | Custom template build progress |

---

## Event envelope

All events arrive in standard SSE format:
```

event: <event_type>
data:
id: <monotonic ULID>
```

All payloads are JSON. The `id:` line allows clients to resume with `Last-Event-ID` on reconnect.

---

## Sandbox event types

| Event | Payload | Description |
|---|---|---|
| `sandbox.started` | `{sandbox_id, region}` | Boot complete; ready to accept exec |
| `sandbox.exec.started` | `{exec_id, command}` | Command began |
| `sandbox.exec.stdout` | `{exec_id, line}` | stdout chunk |
| `sandbox.exec.stderr` | `{exec_id, line}` | stderr chunk |
| `sandbox.exec.completed` | `{exec_id, exit_code, duration_ms}` | Command exited |
| `sandbox.preview.ready` | `{preview_id, url, port}` | Preview URL available |
| `sandbox.idle` | `{sandbox_id, last_activity_at}` | Going to auto-suspend |
| `sandbox.suspended` | `{sandbox_id}` | Auto-suspended after idle window |

---

## Deployment event types

| Event | Payload | Description |
|---|---|---|
| `deployment.publish.queued` | `{version_id}` | Publish accepted, waiting for builder |
| `deployment.publish.building` | `{version_id, stage}` | Builder running |
| `deployment.publish.uploading` | `{version_id, size_bytes}` | Release artifact upload |
| `deployment.publish.promoting` | `{version_id}` | Switching active version |
| `deployment.publish.completed` | `{version_id, deployment_id, url}` | Live |
| `deployment.publish.failed` | `{version_id, error_code, message}` | Build or health-check failure |

---

## Computer event types

| Event | Payload | Description |
|---|---|---|
| `computer.started` | `{computer_id, region}` | VM booted, desktop ready |
| `computer.stream.token_ready` | `{token, expires_at}` | New short-lived stream credential |
| `computer.idle` | `{computer_id, idle_seconds}` | Approaching auto-stop |
| `computer.stopped` | `{computer_id, reason}` | Stopped (manual or auto) |

---

## Reconnect and replay

Send `Last-Event-ID: &lt;ULID&gt;` on the resubscribe request. The server replays all events since that ID. Events are retained for **15 minutes** per resource.
```bash
curl -N "https://api.miosa.ai/api/v1/sandboxes/{id}/events?ticket=sset_..." \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 01hwqz4b3c2v1x..."
```

---

## Error handling

If the connection drops or the ticket expires, the next request returns `401`. Mint a fresh ticket and resubscribe:
```typescript
async function openStream(sandboxId: string): Promise<void> {
  const { ticket } = await fetch('/api/v1/auth/sse-ticket', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.MIOSA_API_KEY}` },
  }).then(r => r.json());

  const es = new EventSource(
    `https://api.miosa.ai/api/v1/sandboxes/${sandboxId}/events/stream?ticket=${ticket}`
  );

  es.addEventListener('error', () => {
    es.close();
    setTimeout(() => openStream(sandboxId), 1000);
  });

  es.addEventListener('sandbox.exec.completed', (e) => {
    console.log('Exec done:', JSON.parse(e.data));
  });
}
```

---

## See also


    Create sandboxes, run exec, write files, open previews.

    [Sandboxes →](/docs/develop/sandboxes/)


    Builder, Release, Version — the full deploy pipeline.

    [Publishing →](/docs/deploy/publishing/)


    Desktop lifecycle, screenshot, click, keyboard APIs.

    [Computers →](/docs/computers/overview/)


    API keys, browser tokens, SSE tickets.

    [Authentication →](/docs/authentication/)

---

# Exec API

URL: https://miosa.ai/docs/api-reference/exec
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/exec
Source: src/routes/docs/api-reference/exec/+page.md
Description: API reference for executing bash commands and Python code on MIOSA computers.

Run commands and scripts directly on a computer without desktop interaction. Both endpoints block until the command exits and return combined stdout+stderr.

Base path: `/api/v1/computers/{id}/exec`

The computer must be in `"running"` status. Commands run as the default user inside the VM. Maximum timeout is 300 s.

Rate limit: 300 req/min per workspace. For long-running output, prefer the streaming exec endpoint which avoids holding an HTTP connection open for the full duration.

---

## Execute Bash Command

**`POST /api/v1/computers/{id}/exec`**

Runs a shell command on the computer.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Shell command to execute |
| `timeout` | integer | No | Timeout in seconds (default: 30, max: 300) |

### Response — `200 OK`
```json
{
  "output": "total 24\ndrwxr-xr-x 6 user user 4096 Apr 11 10:00 .\n",
  "exit_code": 0
}
```

The `output` field contains combined stdout and stderr.

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 409 | `COMPUTER_NOT_RUNNING` | Computer is not running |
| 502 | — | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /home/user", "timeout": 30}'
```

### Examples
```bash
# Install a package
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "sudo apt-get install -y jq", "timeout": 120}'

# Check disk space
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "df -h"}'

# Multi-line script
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "cd /home/user && mkdir -p project && echo done"}'
```

---

## Execute Python Code

**`POST /api/v1/computers/{id}/exec/python`**

Runs Python code on the computer. The code is written to a temporary file and executed with `python3`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | string | Yes | Python source code |
| `timeout` | integer | No | Timeout in seconds (default: 30, max: 300) |

### Response — `200 OK`
```json
{
  "output": "42\n",
  "exit_code": 0
}
```

### How It Works

1. Code is written to `/tmp/miosa_exec_&lt;random&gt;.py`
2. Executed via `timeout &lt;N&gt; python3 /tmp/miosa_exec_&lt;random&gt;.py 2&gt;&1`
3. Temporary file is deleted after execution
4. stdout and stderr are captured in `output`

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 409 | `COMPUTER_NOT_RUNNING` | Computer is not running |
| 502 | — | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import sys\nprint(f\"Python {sys.version}\")\nprint(2 + 2)",
    "timeout": 30
  }'
```

### Examples
```bash
# JSON processing
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\ndata = {\"hello\": \"world\"}\nprint(json.dumps(data, indent=2))",
    "timeout": 10
  }'

# File processing
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os\nfor f in os.listdir(\"/home/user\"):\n    print(f)",
    "timeout": 10
  }'

# Long-running computation
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "total = sum(range(10_000_000))\nprint(f\"Sum: {total}\")",
    "timeout": 60
  }'
```

---

## Terminal

### Create Terminal Session

**`POST /api/v1/computers/{id}/terminal`**

Creates a WebSocket-based terminal session on the computer.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cols` | integer | No | Terminal columns (default: 80) |
| `rows` | integer | No | Terminal rows (default: 24) |
| `shell` | string | No | Shell to use (default: `/bin/bash`) |

#### Response — `201 Created`
```json
{
  "data": {
    "session_id": "default",
    "ws_url": "wss://my-computer.sandbox.miosa.ai/ws/terminal/550e8400-.../default?auth=stream_token",
    "stream_auth": "stream_token",
    "expires_at": 1712700060,
    "computer_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/terminal \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cols": 80, "rows": 24, "shell": "/bin/bash"}'
```

---

### Resize Terminal

**`POST /api/v1/computers/{id}/pty/{session_id}/resize`**

Resizes an active terminal session.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cols` | integer | Yes | New column count |
| `rows` | integer | Yes | New row count |

#### Response — `200 OK`
```json
{
  "status": "ok"
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/pty/{session_id}/resize \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cols": 120, "rows": 40}'
```

---

## Timeout Behavior

- Commands exceeding the timeout are killed with SIGTERM
- The maximum timeout is **300 seconds** (5 minutes)
- If no timeout is specified, the default is **30 seconds**
- The timeout value is clamped: `min(requested, 300)`

## Pre-installed Software

The default template includes:

- Python 3 with pip
- Node.js (if installed via selected_apps)
- Common CLI tools: curl, wget, git, vim, jq
- System utilities: htop, tree, zip/unzip

Install additional packages via the bash exec endpoint:
```bash
# Python packages
{"command": "pip install requests pandas numpy"}

# System packages
{"command": "sudo apt-get install -y postgresql-client"}
```

---

## See also

- [Streaming Exec](/docs/api-reference/streaming-exec/) — SSE stream for long-running commands
- [Computers API](/docs/api-reference/computers/) — computer CRUD and lifecycle
- [Files API](/docs/api-reference/files/) — read and write files without exec
- [Error Codes](/docs/api-reference/errors/) — `COMPUTER_NOT_RUNNING`, `AGENT_UNAVAILABLE`

---

# Files API

URL: https://miosa.ai/docs/api-reference/files
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/files
Source: src/routes/docs/api-reference/files/+page.md
Description: API reference for file upload, download, list, export, and delete operations.

Manage files on a running computer. All paths are restricted to `/home/user`, `/home/ubuntu`, and `/tmp`.

Base path: `/api/v1/computers/{id}/files`

The computer must be in `"running"` status. All operations go through the in-VM agent (envd).

---

## Upload a File

**`POST /api/v1/computers/{id}/files/upload`**

Uploads a file to the computer via multipart form data.

### Request

Content-Type: `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | Yes | File to upload |
| `path` | string | No | Remote path. If ends with `/`, filename is appended. Default: `/home/user/` |

### Response — `201 Created`
```json
{
  "success": true,
  "file": {
    "path": "/home/user/script.py",
    "filename": "script.py",
    "size_bytes": 1234
  }
}
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_FILE` | No file field in request |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 413 | `FILE_TOO_LARGE` | File exceeds 10 MB limit |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/upload \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -F "file=@./script.py" \
  -F "path=/home/user/scripts/"
```

---

## List Directory

**`GET /api/v1/computers/{id}/files`**

Lists files and directories at a given path.

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | No | Directory to list. Default: `/home/user` |

### Response — `200 OK`
```json
{
  "files": [
    {
      "name": "Documents",
      "type": "directory",
      "size_bytes": 4096,
      "modified_at": "2026-04-11T10:30:00Z"
    },
    {
      "name": "script.py",
      "type": "file",
      "size_bytes": 1234,
      "modified_at": "2026-04-11T10:25:00Z"
    }
  ],
  "path": "/home/user"
}
```

### File Entry Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | File or directory name |
| `type` | string | `"file"` or `"directory"` |
| `size_bytes` | integer | Size in bytes |
| `modified_at` | ISO 8601 | Last modification time |
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files?path=/home/user" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Download a File

**`GET /api/v1/computers/{id}/files/download`**

Downloads a file from the computer as binary data.

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Full path to the file |

### Response — `200 OK`

Binary file content. Content-Type is inferred from the file extension. The `Content-Disposition` header is set for download.

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_PATH` | No path parameter |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files/download?path=/home/user/output.txt" \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  --output output.txt
```

---

## Export a File

**`POST /api/v1/computers/{id}/files/export`**

Returns file metadata and base64-encoded content in a single response.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Full path to the file |

### Response — `200 OK`
```json
{
  "success": true,
  "file": {
    "path": "/home/user/data.json",
    "filename": "data.json",
    "size_bytes": 5678,
    "content_type": "application/json",
    "modified_at": "2026-04-11T10:30:00Z"
  },
  "content_base64": "eyJrZXkiOiAidmFsdWUifQ=="
}
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_PATH` | No path in request body |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 404 | `FILE_NOT_FOUND` | File does not exist or is empty |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/export \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/data.json"}'
```

---

## Delete a File

**`DELETE /api/v1/computers/{id}/files`**

Removes a file from the computer.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Full path to the file to delete |

### Response — `200 OK`
```json
{
  "success": true,
  "path": "/home/user/old-file.txt"
}
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_PATH` | No path in request body |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/files \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/old-file.txt"}'
```

---

## Path Security

All paths are validated before execution:

1. **Expansion** — `Path.expand` resolves `..`, `~`, and symlinks
2. **Prefix check** — Expanded path must start with `/home/user`, `/home/ubuntu`, or `/tmp`
3. **Rejection** — Paths outside these prefixes return `403 FORBIDDEN_PATH`

This prevents path traversal attacks. For example, `/home/user/../../etc/passwd` expands to `/etc/passwd` and is rejected.

---

# Filesystem API

URL: https://miosa.ai/docs/api-reference/filesystem
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/filesystem
Source: src/routes/docs/api-reference/filesystem/+page.md
Description: Complete API reference for file and directory operations on MIOSA computers — upload, download, stat, mkdir, rename, copy, chmod, and readdir.

The Filesystem API gives you full programmatic access to files and directories inside a running computer. All operations are proxied through the in-VM envd daemon and restricted to allowed paths.

Base path: `/api/v1/computers/{id}/files`

**Allowed paths:** `/home/user`, `/home/ubuntu`, `/tmp`

The computer must be in `"running"` status. Paths outside the allowed prefixes return `403 FORBIDDEN_PATH`.

---

## Quick Start
```typescript

const client = new Miosa();

// Write a file
await client.files.write(computerId, {
  path: '/home/user/hello.py',
  content: 'print("Hello from MIOSA")',
});

// List the directory
const { files } = await client.files.list(computerId, '/home/user');

// Download it back
const content = await client.files.download(computerId, '/home/user/hello.py');
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/files/upload` | Upload a file (multipart) |
| `POST` | `/files/write` | Write text/binary content directly |
| `GET` | `/files` | List directory (`readdir`) |
| `GET` | `/files/download` | Download a file |
| `POST` | `/files/export` | Download with metadata (base64) |
| `DELETE` | `/files` | Delete a file |
| `GET` | `/files/stat` | Stat a file or directory |
| `POST` | `/files/mkdir` | Create a directory |
| `POST` | `/files/rename` | Rename or move a file/directory |
| `POST` | `/files/copy` | Copy a file |
| `POST` | `/files/chmod` | Change file permissions |

---

## Upload a File

**`POST /api/v1/computers/{id}/files/upload`**

Multipart upload — use this for binary files or large payloads.

### Request — `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | Yes | File to upload |
| `path` | string | No | Remote path. If ends with `/`, filename is appended. Default: `/home/user/` |

### Response — `201 Created`
```json
{
  "success": true,
  "file": {
    "path": "/home/user/script.py",
    "filename": "script.py",
    "size_bytes": 1234
  }
}
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_FILE` | No file field in request |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 413 | `FILE_TOO_LARGE` | File exceeds 10 MB limit |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/upload \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -F "file=@./script.py" \
  -F "path=/home/user/scripts/"
```

---

## Write a File

**`POST /api/v1/computers/{id}/files/write`**

Write text or base64-encoded binary content. Faster than multipart for programmatic use.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Full destination path |
| `content` | string | Yes | File content (UTF-8 text or base64 when `encoding="base64"`) |
| `encoding` | string | No | `"utf8"` (default) or `"base64"` |

### Response — `201 Created`
```json
{
  "success": true,
  "file": {
    "path": "/home/user/config.json",
    "size_bytes": 256
  }
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/write \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/config.json", "content": "{\"key\": \"value\"}"}'
```

---

## List Directory (readdir)

**`GET /api/v1/computers/{id}/files`**

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | No | Directory to list. Default: `/home/user` |

### Response — `200 OK`
```json
{
  "files": [
    {
      "name": "Documents",
      "type": "directory",
      "size_bytes": 4096,
      "permissions": "drwxr-xr-x",
      "modified_at": "2026-04-11T10:30:00Z"
    },
    {
      "name": "script.py",
      "type": "file",
      "size_bytes": 1234,
      "permissions": "-rw-r--r--",
      "modified_at": "2026-04-11T10:25:00Z"
    }
  ],
  "path": "/home/user"
}
```
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files?path=/home/user" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Download a File

**`GET /api/v1/computers/{id}/files/download`**

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Full path to the file |

### Response — `200 OK`

Binary file content. `Content-Disposition` is set for browser download.

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 400 | `MISSING_PATH` | No path parameter |
| 403 | `FORBIDDEN_PATH` | Path outside allowed directories |
| 404 | `FILE_NOT_FOUND` | File does not exist |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files/download?path=/home/user/output.txt" \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  --output output.txt
```

---

## Export a File

**`POST /api/v1/computers/{id}/files/export`**

Returns metadata and base64-encoded content in a single JSON response. Useful when you need the file and its metadata together without handling binary responses.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Full path to the file |

### Response — `200 OK`
```json
{
  "success": true,
  "file": {
    "path": "/home/user/data.json",
    "filename": "data.json",
    "size_bytes": 5678,
    "content_type": "application/json",
    "modified_at": "2026-04-11T10:30:00Z"
  },
  "content_base64": "eyJrZXkiOiAidmFsdWUifQ=="
}
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/export \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/data.json"}'
```

---

## Delete a File

**`DELETE /api/v1/computers/{id}/files`**

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Full path to delete |

### Response — `200 OK`
```json
{ "success": true, "path": "/home/user/old-file.txt" }
```
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/files \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/old-file.txt"}'
```

---

## Stat a File or Directory

**`GET /api/v1/computers/{id}/files/stat`**

Returns metadata without downloading file content.

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Full path |

### Response — `200 OK`
```json
{
  "path": "/home/user/script.py",
  "type": "file",
  "size_bytes": 1234,
  "permissions": "-rw-r--r--",
  "owner": "user",
  "group": "user",
  "modified_at": "2026-04-11T10:25:00Z",
  "created_at": "2026-04-11T09:00:00Z"
}
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 404 | `FILE_NOT_FOUND` | Path does not exist |
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files/stat?path=/home/user/script.py" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Create a Directory

**`POST /api/v1/computers/{id}/files/mkdir`**

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Directory path to create |
| `recursive` | boolean | No | Create parent directories if missing (default: `false`) |

### Response — `201 Created`
```json
{ "success": true, "path": "/home/user/project/src" }
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/mkdir \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/project/src", "recursive": true}'
```

---

## Rename or Move

**`POST /api/v1/computers/{id}/files/rename`**

Renames a file or directory, or moves it to a different path. Both source and destination must be within allowed paths.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source` | string | Yes | Current path |
| `destination` | string | Yes | Target path |

### Response — `200 OK`
```json
{ "success": true, "source": "/home/user/old.txt", "destination": "/home/user/new.txt" }
```

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 404 | `FILE_NOT_FOUND` | Source path does not exist |
| 409 | `DESTINATION_EXISTS` | Destination already exists |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/rename \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "/home/user/app.py", "destination": "/home/user/app_v2.py"}'
```

---

## Copy a File

**`POST /api/v1/computers/{id}/files/copy`**

Copies a file to a new path. Directory copy is not supported — copy individual files.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source` | string | Yes | Source file path |
| `destination` | string | Yes | Destination file path |

### Response — `201 Created`
```json
{ "success": true, "source": "/home/user/template.py", "destination": "/home/user/project/main.py" }
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/copy \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "/home/user/template.py", "destination": "/home/user/project/main.py"}'
```

---

## Change Permissions

**`POST /api/v1/computers/{id}/files/chmod`**

Sets UNIX file permissions.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | File path |
| `mode` | string | Yes | Octal permission string, e.g. `"755"` or `"644"` |

### Response — `200 OK`
```json
{ "success": true, "path": "/home/user/script.sh", "mode": "755" }
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/files/chmod \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/script.sh", "mode": "755"}'
```

---

## Path Security

All paths are validated before execution:

1. **Expansion** — `Path.expand` resolves `..`, `~`, and symlinks
2. **Prefix check** — Must start with `/home/user`, `/home/ubuntu`, or `/tmp`
3. **Rejection** — Paths outside these prefixes return `403 FORBIDDEN_PATH`

`/home/user/../../etc/passwd` expands to `/etc/passwd` and is rejected.

---

## Common Recipes

### Scaffold a project directory
```typescript
// Create structure
await client.files.mkdir(computerId, { path: '/home/user/app/src', recursive: true });
await client.files.mkdir(computerId, { path: '/home/user/app/tests', recursive: true });

// Write files
await client.files.write(computerId, { path: '/home/user/app/src/main.py', content: mainPy });
await client.files.write(computerId, { path: '/home/user/app/requirements.txt', content: reqs });

// Make entrypoint executable
await client.files.chmod(computerId, { path: '/home/user/app/src/main.py', mode: '755' });
```

### Retrieve build artifacts
```python
# List the build output directory
files = client.files.list(computer_id, path="/home/user/app/dist")
for f in files["files"]:
    if f["type"] == "file":
        content = client.files.export(computer_id, path=f"/home/user/app/dist/{f['name']}")
        save_artifact(f["name"], content["content_base64"])
```

---

# Network Policy API

URL: https://miosa.ai/docs/api-reference/network-policy
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/network-policy
Source: src/routes/docs/api-reference/network-policy/+page.md
Description: API reference for configuring per-computer network access controls on MIOSA computers.

Network policies control what external hosts and ports a computer can reach. Use them to sandbox untrusted workloads, enforce egress restrictions, or prevent AI agents from making unexpected outbound connections.

Base path: `/api/v1/computers/{id}/network-policy`

Network policies apply at the Firecracker VM level. Changing a policy takes effect within seconds without restarting the computer.

---

## Quick Start
```typescript

const client = new Miosa();

// Restrict to only allow HTTPS to GitHub and PyPI
await client.networkPolicy.update(computerId, {
  mode: 'allowlist',
  rules: [
    { host: 'github.com',  port: 443, protocol: 'tcp' },
    { host: 'pypi.org',    port: 443, protocol: 'tcp' },
    { host: 'files.pythonhosted.org', port: 443, protocol: 'tcp' },
  ],
});
```
```bash
curl -X PUT https://api.miosa.ai/api/v1/computers/{id}/network-policy \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "allowlist",
    "rules": [
      { "host": "github.com", "port": 443, "protocol": "tcp" }
    ]
  }'
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/computers/{id}/network-policy` | Get current network policy |
| `PUT` | `/computers/{id}/network-policy` | Set network policy (replaces existing) |
| `DELETE` | `/computers/{id}/network-policy` | Reset to default (unrestricted) |

---

## Get Network Policy

**`GET /api/v1/computers/{id}/network-policy`**

### Response — `200 OK`
```json
{
  "data": {
    "computer_id": "...",
    "mode": "unrestricted",
    "rules": [],
    "updated_at": "2026-04-11T00:00:00Z"
  }
}
```

### Policy Modes

| Mode | Description |
|------|-------------|
| `unrestricted` | Default. All outbound traffic allowed |
| `allowlist` | Only listed hosts/ports permitted |
| `denylist` | All traffic permitted except listed rules |
| `isolated` | All outbound blocked (DNS and MIOSA internal excluded) |
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/network-policy \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Set Network Policy

**`PUT /api/v1/computers/{id}/network-policy`**

Replaces the entire policy. Partial updates are not supported — send all rules on every PUT.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mode` | string | Yes | `"unrestricted"`, `"allowlist"`, `"denylist"`, or `"isolated"` |
| `rules` | array | No | Required when mode is `"allowlist"` or `"denylist"` |

#### Rule Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `host` | string | Yes | Hostname or CIDR block (e.g. `10.0.0.0/8`) |
| `port` | integer | No | Port number. Omit to match all ports |
| `protocol` | string | No | `"tcp"`, `"udp"`, or `"any"` (default) |

### Response — `200 OK`

Updated policy object.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 400 | `rules required for allowlist/denylist mode` | Empty rules for a filtering mode |
| 404 | `computer not found` | Computer does not exist |
```bash
# Full isolation except for GitHub
curl -X PUT https://api.miosa.ai/api/v1/computers/{id}/network-policy \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "allowlist",
    "rules": [
      { "host": "github.com", "port": 443, "protocol": "tcp" },
      { "host": "objects.githubusercontent.com", "port": 443, "protocol": "tcp" }
    ]
  }'
```

---

## Reset to Default

**`DELETE /api/v1/computers/{id}/network-policy`**

Removes any custom policy. The computer reverts to unrestricted outbound access.

### Response — `200 OK`
```json
{
  "data": { "computer_id": "...", "mode": "unrestricted" }
}
```
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/network-policy \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Common Recipes

### Sandbox an untrusted AI task
```python
# Lock down before running untrusted code
client.network_policy.update(computer_id, mode="isolated")

# Run the task
result = client.exec(computer_id, command="python3 /home/user/untrusted.py")

# Restore after
client.network_policy.delete(computer_id)
```

### Allow only package registries for a build environment
```typescript
const packageHosts = [
  { host: 'registry.npmjs.org', port: 443, protocol: 'tcp' as const },
  { host: 'pypi.org',           port: 443, protocol: 'tcp' as const },
  { host: 'files.pythonhosted.org', port: 443, protocol: 'tcp' as const },
  { host: 'pkg.go.dev',         port: 443, protocol: 'tcp' as const },
  { host: 'proxy.golang.org',   port: 443, protocol: 'tcp' as const },
];

await client.networkPolicy.update(computerId, {
  mode: 'allowlist',
  rules: packageHosts,
});
```

### Block a known malicious IP range
```typescript
await client.networkPolicy.update(computerId, {
  mode: 'denylist',
  rules: [
    { host: '185.220.0.0/16' },
  ],
});
```

---

# OpenComputers API

URL: https://miosa.ai/docs/api-reference/open-computers
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/open-computers
Source: src/routes/docs/api-reference/open-computers/+page.md
Description: Register and control your own machines (BYOC) via the MIOSA API — exec, files, tunnels, AI agents, inference clusters, and secrets.

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).

Rate limit: 300 req/min per workspace. Exec jobs and agent sessions run asynchronously — poll or stream for results rather than holding the connection.

OpenComputers hosts are registered by installing the `miosa-host` agent on
the target machine. The **host key** returned on registration is shown exactly
once — store it securely.

---

## Hosts

### List hosts

**`GET /api/v1/opencomputers/hosts`**

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Items per page (default: 20, max: 100) |
```json
{
  "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`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name for the host |
| `region` | string | No | Region label |
| `labels` | object | No | Key-value metadata |
```json
{
  "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"
}
```

`host_key` is returned **only once** at registration time. The host agent uses
it to authenticate. Store it immediately — it cannot be retrieved later.

---

### 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`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Command to execute |
| `args` | string[] | No | Arguments (passed separately from shell expansion) |
| `env` | string[] | No | Environment variables in `KEY=VALUE` format |
| `cwd` | string | No | Working directory |
| `timeout` | integer | No | Timeout in seconds (default: 60) |
```json
{
  "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.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/opencomputers/hosts/{id}/fs/list` | GET | List directory (`?path=`) |
| `/opencomputers/hosts/{id}/fs/stat` | GET | Stat a path (`?path=`) |
| `/opencomputers/hosts/{id}/fs/download` | GET | Download a file (`?path=`) |
| `/opencomputers/hosts/{id}/fs/upload` | POST | Upload a file (multipart, `?path=`) |
| `/opencomputers/hosts/{id}/fs/delete` | DELETE | Delete file/dir (`?path=`) |
| `/opencomputers/hosts/{id}/fs/mkdir` | POST | Create directory (`{"path":"..."}`) |

**List response:**
```json
{
  "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.
```json
{
  "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`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_port` | integer | Yes | Local port to expose |
| `auth_mode` | string | No | `public` \| `tenant_only` \| `password` (default: `public`) |
| `slug` | string | No | Custom slug for the public URL |
```json
{
  "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}`**

| Field | Type | Description |
|-------|------|-------------|
| `target_port` | integer | Change target port |
| `auth_mode` | string | Change auth mode |
| `enabled` | boolean | Enable or disable the tunnel |

**`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`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `task` | string | Yes | Natural-language task description |
| `model_id` | string | No | Override the default model |
| `max_turns` | integer | No | Maximum conversation turns (default: 20) |
| `context` | object | No | Additional context key-value pairs |
```json
{
  "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`**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Cluster name |
| `model` | string | Yes | Model to serve (e.g. `llama3:70b`) |
| `host_ids` | string[] | Yes | IDs of hosts in the cluster |
```json
{
  "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

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/opencomputers/secrets` | GET | List tenant secrets |
| `/opencomputers/secrets` | POST | Create a secret |
| `/opencomputers/secrets/{id}` | PATCH | Update value or description |
| `/opencomputers/secrets/{id}` | DELETE | Delete a secret |

### Host-scoped secrets

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/opencomputers/hosts/{id}/secrets` | GET | List host secrets |
| `/opencomputers/hosts/{id}/secrets` | POST | Create a host secret |
| `/opencomputers/hosts/{id}/secrets/{secret_id}` | DELETE | Delete a host secret |

**Create request:**
```json
{ "name": "GITHUB_TOKEN", "value": "ghp_xxx", "description": "CI token" }
```

**Response (value is never returned):**
```json
{
  "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

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY });

// Register a host — save host_key immediately
const host = await miosa.openComputers.hosts.create({ name: 'my-mac' });
console.log('Host key (save this!):', host.host_key);

// Run a command
const job = await miosa.openComputers.jobs.run(host.id, {
  command: 'npm test',
});
console.log('Exit code:', job.exit_code);
console.log('Output:', job.stdout);

// Expose a local dev server
const tunnel = await miosa.openComputers.tunnels.create(host.id, {
  target_port: 3000,
});
console.log('Public URL:', tunnel.public_url);

// Dispatch an AI agent
const session = await miosa.openComputers.agents.dispatch(host.id, {
  task: 'Run the test suite and fix any failing tests',
  max_turns: 30,
});
console.log('Session:', session.id, session.status);
```

```python

client = miosa.Miosa(api_key="msk_u_...")

# Register a host
host = client.open_computers.hosts.create(
    miosa.resources.open_computers.types.HostCreateParams(name="my-mac")
)
print("Host key:", host.host_key)

# Run a command
from miosa.resources.open_computers.types import JobRunParams
job = client.open_computers.jobs.run(host.id, JobRunParams(command="npm test"))
print(f"Exit code: {job.exit_code}, stdout: {job.stdout}")

# Create a tunnel
from miosa.resources.open_computers.types import TunnelCreateParams
tunnel = client.open_computers.tunnels.create(host.id, TunnelCreateParams(target_port=3000))
print("Public URL:", tunnel.public_url)
```

```go
client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))

// Register a host
host, err := client.OpenComputers.Hosts.Create(ctx, miosa.CreateHostInput{
    Name: "my-mac",
})
if err != nil { log.Fatal(err) }
fmt.Println("Host key:", *host.HostKey)

// Run a command
job, err := client.OpenComputers.Jobs.Run(ctx, host.ID, miosa.RunJobInput{
    Command: "npm test",
})
if err != nil { log.Fatal(err) }
fmt.Printf("Exit code: %d\nStdout: %s\n", *job.ExitCode, *job.Stdout)

// Create a tunnel
tunnel, err := client.OpenComputers.Tunnels.Create(ctx, host.ID, miosa.CreateTunnelInput{
    TargetPort: 3000,
})
fmt.Println("Public URL:", tunnel.PublicURL)
```

```elixir
client = Miosa.client("msk_u_...")

# Register a host
{:ok, host} = Miosa.OpenComputers.Hosts.create(client, %{name: "my-mac"})
IO.puts("Host key: #{host["host_key"]}")

# Run a command
{:ok, job} = Miosa.OpenComputers.Jobs.run(client, host["id"], %{command: "npm test"})
IO.puts("Exit code: #{job["exit_code"]}")

# Create a tunnel
{:ok, tunnel} = Miosa.OpenComputers.Tunnels.create(client, host["id"], %{target_port: 3000})
IO.puts("Public URL: #{tunnel["public_url"]}")
```

```java
MiosaClient miosa = new MiosaClient(System.getenv("MIOSA_API_KEY"));

// Register a host
HostData host = miosa.openComputers().hosts()
    .create(new CreateHostParams("my-mac"));
System.out.println("Host key: " + host.hostKey);

// Run a command
JobData job = miosa.openComputers().jobs()
    .run(host.id, new RunJobParams("npm test"));
System.out.printf("Exit code: %d%nStdout: %s%n", job.exitCode, job.stdout);

// Create a tunnel
TunnelData tunnel = miosa.openComputers().tunnels()
    .create(host.id, new CreateTunnelParams(3000));
System.out.println("Public URL: " + tunnel.publicUrl);
```

---

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `NOT_FOUND` | Host or resource does not exist in this tenant |
| 403 | `FORBIDDEN` | Authenticated but not authorized |
| 400 | `INVALID_ID` | Path parameter is not a valid ID |
| 409 | — | Host is offline; command cannot be dispatched |
| 502 | — | Host agent is unreachable |

---

## See also

- [Computers API](/docs/api-reference/computers/) — managed MIOSA VMs vs. BYOC hosts
- [Exec API](/docs/api-reference/exec/) — exec on managed computers
- [Regions](/docs/api-reference/regions/) — region slugs accepted on host creation
- [Error Codes](/docs/api-reference/errors/) — complete error code reference

---

# Projects API

URL: https://miosa.ai/docs/api-reference/projects
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/projects
Source: src/routes/docs/api-reference/projects/+page.md
Description: API reference for creating and managing projects inside MIOSA workspaces.

A **Project** is the app, website, lead magnet, document, workflow, or customer build inside a workspace. Projects own sandboxes, computers, deployments, databases, storage buckets, volumes, functions, jobs, auth configuration, integrations, and custom domains.

Base path: `/api/v1/projects`

If a resource create call includes `project_slug`, `project_name`, or `external_project_id`, MIOSA resolves or creates the project before creating the resource. You can also create projects explicitly with this API.

## Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/projects` | List projects for the organization |
| `POST` | `/projects` | Create a project inside a workspace |
| `GET` | `/projects/{id}` | Get one project |
| `PATCH` | `/projects/{id}` | Update a project |
| `GET` | `/projects/{id}/preview-domain` | Read the project preview domain |
| `PUT` | `/projects/{id}/preview-domain` | Set the project preview domain |
| `DELETE` | `/projects/{id}/preview-domain` | Clear the project preview domain |
| `GET` | `/projects/{id}/preview-domain/verify` | Check DNS readiness |
| `GET` | `/workspaces/{id}/projects` | List projects in one workspace |

---

## List Projects

**`GET /api/v1/projects`**

### Query Parameters

| Parameter | Type | Description |
|---|---|---|
| `workspace_id` | UUID | Limit results to one workspace |

### Response - `200 OK`
```json
{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "tenant_id": "tnt_abc123",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "external_workspace_id": "clinic_123",
      "external_project_id": "project_789",
      "name": "Lead Magnet",
      "slug": "lead-magnet",
      "description": null,
      "metadata": {},
      "settings": {},
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:00:00Z"
    }
  ],
  "total": 1
}
```

```bash
curl "https://api.miosa.ai/api/v1/projects?workspace_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Create a Project

**`POST /api/v1/projects`**

A project must belong to a workspace. Supply one of `workspace_id`, `workspace_slug`, or `external_workspace_id`.

### Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `workspace_id` | UUID | Conditional | Existing MIOSA workspace ID |
| `workspace_slug` | string | Conditional | Existing workspace slug |
| `external_workspace_id` | string | Conditional | Your external workspace/customer ID |
| `name` | string | Yes | Human-readable project name |
| `slug` | string | No | URL-safe identifier. Auto-derived from `name` if omitted. |
| `external_project_id` | string | No | Your project/app/document ID |
| `description` | string | No | Optional description |
| `metadata` | object | No | Caller metadata stored on the project |

### Example
```bash
curl -X POST https://api.miosa.ai/api/v1/projects \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_slug": "dr-smith-clinic",
    "name": "Lead Magnet",
    "slug": "lead-magnet",
    "external_workspace_id": "clinic_123",
    "external_project_id": "project_789"
  }'
```

### Response - `201 Created`

Full project object.

### Errors

| Status | Code | Cause |
|---|---|---|
| 400 | `WORKSPACE_REQUIRED` | No `workspace_id`, `workspace_slug`, or `external_workspace_id` was supplied |
| 404 | `WORKSPACE_NOT_FOUND` | Workspace selector did not resolve inside the organization |
| 422 | `VALIDATION_FAILED` | Name, slug, or external project ID failed validation |

---

## Get a Project

**`GET /api/v1/projects/{id}`**

Returns one project if it belongs to the authenticated organization.

```bash
curl https://api.miosa.ai/api/v1/projects/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Update a Project

**`PATCH /api/v1/projects/{id}`**

### Request Body

| Field | Type | Description |
|---|---|---|
| `name` | string | New display name |
| `slug` | string | New URL-safe slug, unique inside the workspace |
| `description` | string | New description (`null` to clear) |
| `external_project_id` | string | Your project/app/document ID |
| `external_workspace_id` | string | Your customer/workspace ID |
| `metadata` | object | Replacement metadata map |
| `settings` | object | Replacement settings map. Prefer the preview-domain endpoint for domain changes. |

```bash
curl -X PATCH https://api.miosa.ai/api/v1/projects/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Summer Lead Magnet"}'
```

---

## Use Projects on Resource Create

Most create endpoints accept the same ownership fields:

```json
{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "external_workspace_id": "clinic_123",
  "external_project_id": "project_789"
}
```

You can use slugs instead of UUIDs:

```json
{
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "lead-magnet",
  "project_name": "Lead Magnet"
}
```

This applies to sandboxes, computers, deployments, databases, storage buckets, volumes, edge functions, cron jobs, project auth, and integrations. Derived records inherit ownership automatically.

---

## Project Preview Domain

**`PUT /api/v1/projects/{id}/preview-domain`**

Sets a project-level base domain for generated URLs. This overrides the workspace preview domain and organization preview domain for resources in this project.

```bash
curl -X PUT https://api.miosa.ai/api/v1/projects/{id}/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview_domain":"program.drsmithclinic.com"}'
```

Response:
```json
{
  "scope": "project",
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "preview_domain": "program.drsmithclinic.com",
  "effective_domain": "program.drsmithclinic.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "url_examples": {
    "default_preview": "https://<slug>.program.drsmithclinic.com",
    "port_preview": "https://3000-<slug>.sandbox.program.drsmithclinic.com",
    "deployment": "https://<deployment-slug>.program.drsmithclinic.com"
  }
}
```

Required DNS records:

| Record type | Name | Value |
|---|---|---|
| `CNAME` | `*` | `proxy.miosa.ai` |
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` |

Verify:
```bash
curl https://api.miosa.ai/api/v1/projects/{id}/preview-domain/verify \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Clear and inherit from the workspace/organization fallback:
```bash
curl -X DELETE https://api.miosa.ai/api/v1/projects/{id}/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

## See also

- [Workspaces API](/docs/api-reference/workspaces/) - parent resource
- [Ownership and Attribution](/docs/platform/attribution/) - how IDs flow to usage and events
- [Sandboxes API](/docs/api-reference/sandboxes/) - create resources inside a project
- [Deployments API](/docs/api-reference/deployments/) - publish projects to URLs

---

# Regions API

URL: https://miosa.ai/docs/api-reference/regions
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/regions
Source: src/routes/docs/api-reference/regions/+page.md
Description: List available regions and pin Computers and Sandboxes to a specific region.

MIOSA Computers and Sandboxes run in geographic regions. Every Computer (and every Sandbox, since a Sandbox is a lightweight Computer flavor) is created in exactly one region and stays there for its lifetime.

Base path: `/api/v1/regions`

---

## Overview

- **3 regions are live today.** All have equal status — none are preview, none are restricted.
- **Default region** when you don't specify one: `us-west-la`.
- **All VM sizes** (XS, S, M, L, XL) are available in every region for both Computers and Sandboxes.
- **Latency** is roughly equidistant for US users — pick by data residency or proximity preference rather than performance.
- **No multi-region resources.** A Computer lives in exactly one region. To run workloads in multiple regions, create multiple Computers.

---

## Available Regions

| Slug             | Location          | City             | Status |
|------------------|-------------------|------------------|--------|
| `us-west-la`     | US West           | Los Angeles, CA  | Live   |
| `us-east-ny`     | US East           | New York, NY     | Live   |
| `us-mia`  | US East 2        | Miami         | Live   |

The region slug is what you pass on create and what comes back on read — every Computer and Sandbox response includes a `region` field, e.g. `"region": "us-west-la"`.

---

## Specify a region on create

Pass `region` in the request body when creating a Computer or Sandbox. If omitted, the default (`us-west-la`) is used.

```python
  computer = client.computers.create(
      name="ny-build-box",
      size="M",
      region="us-east-ny",
  )
  print(computer.region)  # "us-east-ny"
```

```typescript
  const computer = await client.computers.create({
    name: 'ny-build-box',
    size: 'M',
    region: 'us-east-ny',
  });
  console.log(computer.region); // "us-east-ny"
```

```bash
  curl -X POST https://api.miosa.ai/api/v1/computers \
    -H "Authorization: Bearer $MIOSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "ny-build-box",
      "size": "M",
      "region": "us-east-ny"
    }'
```

The same `region` field works on `POST /api/v1/sandboxes`.

### Errors

| Status | Error                | Cause                                          |
|--------|----------------------|------------------------------------------------|
| 400    | `invalid_region`     | Slug not in the list above                     |
| 409    | `region_unavailable` | Transient capacity issue — retry or pick another |

---

## Default region behavior

If `region` is omitted from the create request:

- Computers default to **`us-west-la`**.
- Sandboxes default to **`us-west-la`**.
- The response still includes the resolved `region` so you always know where the resource lives.

You can change your tenant's default region in dashboard settings — that override applies to API calls that omit `region`.

---

## List regions

**`GET /api/v1/regions`**

Returns the regions available to your tenant. Useful for region pickers in UIs.

### Response — `200 OK`
```json
{
  "regions": [
    {
      "slug": "us-west-la",
      "name": "US West (Los Angeles)",
      "city": "Los Angeles",
      "country": "US",
      "status": "live",
      "default": true
    },
    {
      "slug": "us-east-ny",
      "name": "US East (New York)",
      "city": "New York",
      "country": "US",
      "status": "live",
      "default": false
    },
    {
      "slug": "us-mia",
      "name": "US East 2 (Miami)",
      "city": "Miami",
      "country": "US",
      "status": "live",
      "default": false
    }
  ]
}
```

### Response Fields

| Field      | Type    | Description                                           |
|------------|---------|-------------------------------------------------------|
| `slug`     | string  | Stable identifier — pass this as `region` on create   |
| `name`     | string  | Human-readable label (safe to render in UIs)          |
| `city`     | string  | City the region is hosted in                          |
| `country`  | string  | Two-letter ISO country code                           |
| `status`   | string  | Always `"live"` today — reserved for future states     |
| `default`  | boolean | `true` for exactly one region (the tenant default)    |
```bash
curl https://api.miosa.ai/api/v1/regions \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

The list endpoint is unauthenticated-friendly — you can use a short-lived ticket or a public token to populate region pickers without exposing your `msk_*` key.

---

## FAQ

### Why these 3 regions?

We picked Los Angeles, New York, and Miami to cover the US west coast, east coast, and central corridor. The three sites are roughly equidistant for the median US user, and they each sit on independent network and power footprints — so a regional outage at one doesn't take the others down.

### How do I pick a region?

Pick by **data residency** first. If you have a customer or compliance requirement that pins data to a coast, that decides for you.

If you have no residency requirement, pick by **proximity to your users or your CI runners** — shorter physical distance means lower RTT for VNC streaming and PTY round-trips. Compute performance itself is identical across regions.

### Can a Computer span multiple regions?

No. A Computer (or Sandbox) lives in exactly one region for its lifetime. To run workloads in multiple regions:

- Create one Computer per region.
- Use OpenComputers federation if you want a single logical workspace across them (see [OpenComputers](/docs/api-reference/open-computers/)).

There's no live migration between regions today.

### Will more regions ship?

Yes — EU and APAC regions are on the roadmap. When they ship they'll appear in `GET /api/v1/regions` with the same `"status": "live"` shape. Watch the [changelog](/docs/changelog/) for announcements.

---

## See also

- [Computers API](/docs/api-reference/computers/) — pass `region` on create
- [Sandboxes API](/docs/api-reference/sandboxes/) — sandbox region support
- [OpenComputers](/docs/api-reference/open-computers/) — federate BYOC hosts across regions

---

# API Reference / Releases

URL: https://miosa.ai/docs/api-reference/releases
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/releases
Source: src/routes/docs/api-reference/releases/+page.md
Description: The immutable build artifact — static tarball or dynamic rootfs / OCI image, sha256-keyed.

First-class `deployment_releases` records and their dedicated endpoints arrive in Phase 2B of the deployment refactor. Today, release content is referenced via the `artifact_uri` / `artifact_sha256` fields on `deployment_versions`. This page documents the steady-state target.

A **Release** is the physical artifact produced by a build — what a [Version](/docs/api-reference/versions/) references. See [Releases](/docs/deploy/releases/) for the conceptual model.

## Endpoints (Phase 2B)
```http
GET /api/v1/releases/:id
GET /api/v1/deployments/:id/versions/:version_id/release
```

Releases are not typically created directly — they're produced by [Publish](/docs/api-reference/deployments/#publish). The endpoints above are for inspection and audit.

## Release shape
```json
{
  "id": "rel_...",
  "deployment_version_id": "ver_...",
  "service_id": "svc_...",
  "tenant_id": "...",
  "kind": "static",
  "storage_uri": "s3://miosa-releases/dep_xyz/rel_abc.tar.zst",
  "sha256": "a5e6f0c1...",
  "size_bytes": 184320,
  "start_command": null,
  "port": null,
  "metadata": {
    "build_log_uri": "s3://...",
    "build_duration_ms": 8420
  },
  "created_at": "2026-05-14T18:19:48Z"
}
```

For dynamic releases: `kind: "oci" | "rootfs"`, `start_command` and `port` populated.

## Immutability

Releases are content-addressed by sha256. A release with sha256 `abc...` is always the same bytes. This is what makes [Rollback](/docs/deploy/rollback/) trivial and horizontal scaling identical across instances.

A release is never mutated. To "change" it, publish a new version, which produces a new release.

## Garbage collection

Static release artifacts older than the retention window (default 30 days for archived versions) are eligible for GC. The version row remains for audit; the artifact itself may be removed from object storage.

If you attempt to rollback to a version whose artifact has been GC'd, MIOSA returns `410 Gone`. Active versions (any deployment's `active_version_id`) are never GC'd.

## Permissions

| Action | Scope |
|---|---|
| Get | `deployments:read` |

## See also

- [Versions](/docs/api-reference/versions/) — parent resource
- [Deployments](/docs/api-reference/deployments/) — top-level resource
- [Releases](/docs/deploy/releases/) — conceptual model

---

# Sandboxes API

URL: https://miosa.ai/docs/api-reference/sandboxes
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandboxes
Source: src/routes/docs/api-reference/sandboxes/+page.md
Description: API reference for creating, managing, and executing code in MIOSA sandboxes — ephemeral Firecracker microVMs.

Sandboxes are ephemeral Firecracker microVMs that restore from a pre-seeded snapshot, accept exec and file operations, expose previews, and are billed by compute/runtime usage. They are designed for AI-agent code execution workloads, artifact generation, and app previews.

Base path: `/api/v1/sandboxes`

All endpoints require `Authorization: Bearer &lt;api_key&gt;`. Get a key from the [MIOSA dashboard](https://app.miosa.ai/settings/api-keys).

For higher-level access, use the official SDKs: [Python](/docs/sdks/python/), [TypeScript](/docs/sdks/typescript/), [Go](/docs/sdks/go/), [Java](/docs/sdks/java/), [Elixir](/docs/sdks/elixir/).

---

## List Sandbox Templates

**`GET /api/v1/sandbox-templates`**

Returns the platform-managed sandbox template catalog. Pass one of these IDs as `template_id` when creating a sandbox. The catalog describes what your app should run: workdir, install command, start command, preview port, readiness probe, and artifact paths.
```bash
curl https://api.miosa.ai/api/v1/sandbox-templates \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Response — `200 OK`
```json
{
  "default_template_id": "miosa-sandbox",
  "data": [
    {
      "id": "nextjs",
      "name": "Next.js",
      "image_id": "miosa-sandbox",
      "category": "web",
      "cpu_count": 2,
      "memory_mb": 2048,
      "disk_mb": 4096,
      "workdir": "/workspace",
      "preview_port": 3000,
      "install_command": "npm install",
      "start_command": "npm run dev -- --hostname 0.0.0.0 --port 3000",
      "readiness_probe": {
        "type": "http",
        "url": "http://127.0.0.1:3000"
      }
    }
  ]
}
```

Use `GET /api/v1/sandbox-templates/{id}` to fetch one template. Add `?include_aliases=true` on the list endpoint to include compatibility aliases such as `python-3.12`, `react-vite`, and `static`.

---

## Sandbox Template BuildSpec

Phase 4 introduces the public BuildSpec contract for reusable sandbox templates.
The API validates and normalizes BuildSpecs, persists tenant-owned template
records, queues template build records, and runs a builder worker that turns
the normalized BuildSpec into a Firecracker rootfs artifact.

### Get the BuildSpec schema

**`GET /api/v1/sandbox-templates/build-spec`**
```bash
curl https://api.miosa.ai/api/v1/sandbox-templates/build-spec \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Validate a BuildSpec

**`POST /api/v1/sandbox-templates/validate`**
```bash
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates/validate \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "build_spec": {
      "from": "node:22-bookworm",
      "vcpu": 2,
      "memoryMib": 2048,
      "diskMib": 8192,
      "steps": [
        {"run": "corepack enable"},
        {"workdir": "/workspace"}
      ],
      "env": {"NODE_ENV": "development"},
      "workdir": "/workspace",
      "user": "root",
      "startCmd": "pnpm dev --host 0.0.0.0 --port 3000",
      "readyCmd": "curl -f http://127.0.0.1:3000",
      "previewPort": 3000,
      "artifactPaths": ["/workspace"]
    }
  }'
```

Response:
```json
{
  "valid": true,
  "build_spec": {
    "from": "node:22-bookworm",
    "vcpu": 2,
    "memoryMib": 2048,
    "diskMib": 8192,
    "steps": [{"run": "corepack enable"}, {"workdir": "/workspace"}],
    "env": {"NODE_ENV": "development"},
    "workdir": "/workspace",
    "user": "root",
    "startCmd": "pnpm dev --host 0.0.0.0 --port 3000",
    "readyCmd": "curl -f http://127.0.0.1:3000",
    "previewPort": 3000,
    "artifactPaths": ["/workspace"]
  }
}
```

Validation errors use stable codes:

| Code | Meaning |
|------|---------|
| `REQUIRED` | A required field such as `from` is missing. |
| `UNSUPPORTED_BASE_IMAGE` | Alpine/distroless bases are rejected for public agent templates. |
| `OUT_OF_RANGE` | Resource values are outside tenant-safe defaults. |
| `INVALID_INTEGER` | Numeric fields are not integers. |
| `INVALID_PORT` | Preview port is outside `1..65535`. |
| `INVALID_PATH` | Workdir or artifact path is not absolute. |
| `INVALID_STEP` | A build step is not a supported object. |

### Create a custom template

**`POST /api/v1/sandbox-templates`**
```bash
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Web App",
    "slug": "agent-web-app",
    "description": "Reusable Node app sandbox",
    "build_spec": {
      "from": "node:22-bookworm",
      "vcpu": 2,
      "memoryMib": 2048,
      "diskMib": 8192,
      "startCmd": "pnpm dev --host 0.0.0.0 --port 3000",
      "readyCmd": "curl -f http://127.0.0.1:3000",
      "previewPort": 3000,
      "artifactPaths": ["/workspace"]
    }
  }'
```

### Queue a template build

**`POST /api/v1/sandbox-templates/{template_id}/builds`**
```bash
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates/tpl_123/builds \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Build records start in `queued`. The builder worker moves them through
`building`, `snapshotting`, `certifying`, `distributing`, and then `ready` or `failed`.
`ready` means the rootfs exists, a Firecracker memory snapshot has been seeded,
certification passed, and the rootfs/snapshot artifacts have been published to
the fleet artifact source. Each compute host reconciles or fetches the artifacts
before it boots that custom template. After that, pass the template slug to
`POST /api/v1/sandboxes` as `template_id`.

If a custom template exists but is not ready, sandbox creation returns
`409 TEMPLATE_NOT_READY`. If snapshot seeding fails, the build fails with
`SNAPSHOT_FAILED`; if certification fails, it fails with
`CERTIFICATION_FAILED`.

### Read template builds
```bash
curl https://api.miosa.ai/api/v1/sandbox-templates/tpl_123/builds \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl https://api.miosa.ai/api/v1/sandbox-template-builds/build_123 \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Observe and control template builds
```bash
curl https://api.miosa.ai/api/v1/sandbox-template-builds/build_123/logs \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Browsers/EventSource cannot send Authorization headers. Issue a short-lived
# SSE ticket first, then pass it as ?ticket=...
curl -X POST https://api.miosa.ai/api/v1/auth/sse-ticket \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -N "https://api.miosa.ai/api/v1/sandbox-template-builds/build_123/logs/stream?ticket=$SSE_TICKET" \
  -H "Accept: text/event-stream"

curl -X POST https://api.miosa.ai/api/v1/sandbox-template-builds/build_123/cancel \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -X POST https://api.miosa.ai/api/v1/sandbox-template-builds/build_123/retry \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

`/logs` returns persisted lifecycle events from build metadata. `/logs/stream`
opens an SSE stream that first replays persisted events, then emits live
`build_event` messages until the build reaches `ready`, `failed`, or
`cancelled`.

Example SSE payload:
```text
event: build_event
data: {"event":"snapshotting","state":"snapshotting","at":"2026-05-13T10:00:00Z"}
```

Retry is allowed for `failed` or `cancelled` builds. Cancel is accepted for
non-terminal builds and records `BUILD_CANCELLED`.

### BuildSpec fields

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | OCI base image. Debian/Ubuntu/Bookworm bases are recommended. |
| `vcpu` | integer | Template-owned vCPU count. |
| `memoryMib` | integer | Template-owned memory in MiB. |
| `diskMib` | integer | Template-owned root disk in MiB. |
| `steps` | array | Ordered build steps. Each step may define `run`, `workdir`, or `env`. |
| `env` | object | Runtime-default environment variables. |
| `workdir` | string | Runtime working directory. Defaults to `/workspace`. |
| `user` | string | Runtime user. Defaults to `root`. |
| `startCmd` | string | Long-running command used by `/template/start`. |
| `readyCmd` | string | Readiness command for the started app. |
| `previewPort` | integer | Default preview port for `/expose` and template start. |
| `artifactPaths` | array | Paths returned by the artifact manifest. |

---

## 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 current production alias, `miosa-sandbox`, points at `miosa-sandbox`. On the deployed six-host fleet, the snapshot path benchmarks at **48 ms p50 / 51 ms p95 runtime boot** and **156 ms p50 / 208 ms p95 create-to-ready**.

### Auth

Bearer token required.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `template_id` | string | No | Boot template. Defaults to `miosa-sandbox`. See available templates below. |
| `cpu_count` | integer | No | vCPU count. Default `1`, default cap `4`. |
| `memory_mb` | integer | No | RAM in MB. Default `1024`, default cap `8192`. |
| `disk_mb` | integer | No | Disk in MB. Default `3072`, default cap `10240`. |
| `timeout_sec` | integer | No | Max wall-clock seconds before force-destroy. Day-long/always-on use is available when billing and policy allow it. |
| `env` | object | No | Key-value env vars injected at boot. |
| `metadata` | object | No | Arbitrary caller-supplied metadata stored on the record. |
| `auto_start` | boolean | No | If `true`, MIOSA starts the selected template after the sandbox reaches `running`. Generated-app platforms usually keep this false, write files first, then call `/template/start`. |
| `workspace_id` | UUID | No | Existing MIOSA workspace that owns the sandbox. Defaults to the organization default workspace. |
| `workspace_slug` | string | No | Existing or auto-created workspace slug. |
| `workspace_name` | string | No | Workspace display name if auto-created. |
| `project_id` | UUID | No | Existing MIOSA project that owns the sandbox. Defaults to the workspace default project. |
| `project_slug` | string | No | Existing or auto-created project slug inside the workspace. |
| `project_name` | string | No | Project display name if auto-created. |
| `external_workspace_id` | string | No | Your customer/account/workspace ID. |
| `external_user_id` | string | No | Your end-user ID. |
| `external_project_id` | string | No | Your project/app/document ID. |

**Available templates:**

| `template_id` | Description |
|---------------|-------------|
| `miosa-sandbox` | Stable production alias for the current sandbox image. |
| `nextjs` | Next.js app preview profile. |
| `vite-react` | Vite React app preview profile. |
| `python` | Python script/artifact generation profile. |
| `streamlit` | Streamlit data app preview profile. |
| `gradio` | Gradio ML/demo app preview profile. |
| `static-html` | Static HTML/CSS/JS preview profile. |

### Request Headers

| Header | Description |
|--------|-------------|
| `Idempotency-Key` | Client-generated key (UUID recommended). Same key within 24 h returns the existing sandbox instead of creating a new one. |

### Response — `201 Created`
```json
{
  "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": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789",
  "template_id": "miosa-sandbox",
  "image_id": "miosa-sandbox",
  "state": "provisioning",
  "ready": false,
  "cpu_count": 1,
  "memory_mb": 1024,
  "disk_size_mb": 3072,
  "boot_path": null,
  "boot_ms": null,
  "preview_url": "https://sbx01j9x.sandbox.miosa.app",
  "timeout_sec": 300,
  "total_runtime_sec": null,
  "metadata": {},
  "created_at": "2026-04-25T10:00:00Z",
  "started_at": null,
  "ready_at": null,
  "destroyed_at": null
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_TEMPLATE` | `template_id` is not a recognized template. |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits to provision the VM. |
| 409 | `SANDBOX_LIMIT_EXCEEDED` | Tenant has reached the concurrent sandbox limit (default 10). |
| 422 | `VALIDATION_ERROR` | Invalid field values (for example, a resource request above the tenant's plan cap). |

---

## 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.
```bash
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:
```json
{
  "data": {
    "status": "started",
    "template_id": "nextjs",
    "workdir": "/workspace",
    "preview_port": 3000,
    "preview_url": "https://abc12345.sandbox.miosa.app",
    "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.
```bash
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.
```bash
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": "dr-smith-clinic",
    "workspace_name": "Dr. Smith Clinic",
    "project_slug": "lead-magnet",
    "project_name": "Lead Magnet",
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789",
    "memory_mb": 1024,
    "env": {"MY_VAR": "hello"}
  }'
```

---

## List Sandboxes

**`GET /api/v1/sandboxes`**

Returns all sandboxes belonging to the authenticated tenant.

### Query Parameters

| Parameter | Type | Description |
|---|---|---|
| `workspace_id` | UUID | Filter to one MIOSA workspace |
| `project_id` | UUID | Filter to one MIOSA project |
| `external_workspace_id` | string | Filter by your customer/account ID |
| `external_user_id` | string | Filter by your end-user ID |
| `external_project_id` | string | Filter by your project/app/document ID |
| `state` | string | Filter by lifecycle state: `provisioning`, `running`, `paused`, `destroyed`, `error`. |

### Auth

Bearer token required.

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "sbx_01j9xr2t4fk8me3n5q",
      "template_id": "miosa-sandbox",
      "state": "running",
      "cpu_count": 1,
      "memory_mb": 1024,
      "created_at": "2026-04-25T10:00:00Z"
    }
  ]
}
```
```bash
curl "https://api.miosa.ai/api/v1/sandboxes?state=running" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get a Sandbox

**`GET /api/v1/sandboxes/{id}`**

### Auth

Bearer token required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. |

### Response — `200 OK`

Full sandbox object (same shape as the create response with current `state`).

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `NOT_FOUND` | Sandbox does not exist or belongs to a different tenant. |
```bash
curl https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Destroy a Sandbox

**`DELETE /api/v1/sandboxes/{id}`**

Terminates the VM immediately and settles billing.

### Auth

Bearer token required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. |

### Response — `200 OK`
```json
{
  "id": "sbx_01j9xr2t4fk8me3n5q",
  "state": "destroyed",
  "total_runtime_sec": 42
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `NOT_FOUND` | Sandbox does not exist or belongs to a different tenant. |
```bash
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Execute a Command

**`POST /api/v1/sandboxes/{id}/exec`**

Runs a shell command inside the sandbox. Blocks until the process exits.

### Auth

Bearer token required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. Must be in `running` state. |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Shell command to execute. |
| `timeout` | integer | No | Per-command timeout in seconds. Default `30`, max `300`. |
| `working_dir` | string | No | Working directory inside the VM. Default `/root`. |
| `env` | object | No | Env vars for this invocation only. |

### Response — `200 OK`
```json
{
  "data": {
    "sandbox_id": "sbx_01j9xr2t4fk8me3n5q",
    "stdout": "2\n",
    "stderr": "",
    "exit_code": 0
  }
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox is not in `running` state. |
| 504 | — | Command timed out. |
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(1+1)\"", "timeout": 30}'
```

---

## Stream Command Output

**`POST /api/v1/sandboxes/{id}/exec/stream`**

Runs a command and streams stdout/stderr events as Server-Sent Events. Use this
for installer output, long-running agent tasks, and build logs that should show
progress before the command exits.

Request body is the same as `/exec`.
```bash
curl -N -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/exec/stream \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"command":"npm install && npm run build","working_dir":"/workspace","timeout":300}'
```

Example events:
```text
event: stdout
data: {"line":"added 342 packages"}

event: exit
data: {"exit_code":0}
```

---

## Open a Terminal Session

**`POST /api/v1/sandboxes/{id}/terminal`**

Creates a PTY session inside a running sandbox and returns a short-lived stream
token for browser WebSocket clients.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cols` | integer | No | Initial terminal width. Defaults to `80`. |
| `rows` | integer | No | Initial terminal height. Defaults to `24`. |
| `shell` | string | No | Shell command. Defaults to login bash when available. |

### Response — `201 Created`
```json
{
  "session_id": "52d1df5a0a3a0018",
  "ws_url": "wss://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/terminal/stream",
  "stream_auth": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "stream_auth_expires_at": "2026-05-13T12:30:00Z"
}
```

Open the WebSocket with:
```text
wss://api.miosa.ai/api/v1/sandboxes/{id}/terminal/stream?session_id={session_id}&cols=120&rows=32&token={stream_auth}
```

Clients should send raw terminal input as binary frames. Resize events are sent
as JSON text frames:
```json
{"type":"resize","cols":120,"rows":32}
```

Delete the session when finished:
```bash
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/{id}/terminal/{session_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Expose a Preview Port

**`POST /api/v1/sandboxes/{id}/expose`**

Returns a public, tenant-aware preview URL for a server running inside the sandbox. Use this when an agent generated a Vite/Next/FastAPI/Flask app and started it on a local port.

Inside the sandbox, bind dev servers to `0.0.0.0`, not `localhost`:
```bash
npm run dev -- --host 0.0.0.0 --port 5173
python -m http.server 8000 --bind 0.0.0.0
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `port` | integer | No | Port inside the sandbox to expose. If omitted, MIOSA uses the template lifecycle preview port when available. Must be `1` through `65535` when provided. |

### Response — `200 OK`
```json
{
  "url": "https://5173-sbx01j9x.sandbox.miosa.app"
}
```

If the tenant has a white-label preview domain configured, the same endpoint returns that domain instead of the platform default. Default app ports such as `3000`, `5173`, `8080`, `8000`, and `80` may be returned as `https://{slug}.sandbox.{domain}`; non-default ports use `https://{port}-{slug}.sandbox.{domain}`.

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `MISSING_PARAM` | `port` was omitted and the sandbox template has no default preview port. |
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox is not in `running` state. |
| 422 | `INVALID_PORT` | Port is outside `1` through `65535`. |
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/expose \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 5173}'
```

For static artifacts such as PDFs, images, Markdown, CSV, or ZIP files, write them under `/workspace` and download them through the files API. For web apps, start a server and expose the port.

---

## Promote a Sandbox to a Deployment

**`POST /api/v1/sandboxes/{id}/deploy`**

Promotes a running sandbox into a persistent deployment URL. This is the publish step for generated-app platforms: the sandbox remains the runtime behind the deployment route, its auto-destroy timer is cancelled, and the deployment is marked `running` against the sandbox VM IP and preview port.

Use this after your generated app is serving successfully through `/template/start` or `/expose`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Human-readable deployment name. Used to create the deployment slug. |
| `port` | integer | No | Runtime port to route. Defaults to the template lifecycle preview port, then `80`. |
| `domain` | string | No | Custom domain to attach. |
| `custom_domain` | string | No | Alias for `domain`, used by frontend clients. |

### Response — `201 Created`
```json
{
  "deployment_id": "dep_01j9xr2t4fk8me3n5q",
  "url": "https://my-app-a1b2c3.acme.miosa.app",
  "state": "running"
}
```

Managed deployment URLs are tenant-scoped: `https://{deployment-slug}.{tenant-slug}.miosa.app`. MIOSA persists the sandbox runtime target on the deployment and reconciles running routes, so a temporary proxy restart or admin API outage can be repaired from the database.

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `MISSING_PARAM` | `name` was omitted. |
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox is not in `running` state. |
| 409 | `SANDBOX_RUNTIME_UNAVAILABLE` | Sandbox is marked running but has no VM IP yet. |
| 422 | `INVALID_PORT` | Port is outside `1` through `65535`. |
| 422 | `VALIDATION_ERROR` | Deployment record validation failed. |
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/deploy \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","port":8000}'
```

---

## Upload a File

**`POST /api/v1/sandboxes/{id}/files`**

Writes a file to the sandbox filesystem. Two request formats are accepted.

### Auth

Bearer token required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. Must be in `running` state. |

### Request Body — JSON

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Absolute destination path inside the sandbox. |
| `content` | string | Yes | Base64-encoded file content. |
```json
{
  "path": "/workspace/script.py",
  "content": "cHJpbnQoJ2hlbGxvJyk="
}
```

### Request Body — Multipart

Alternatively, send `multipart/form-data` with fields:

| Field | Description |
|-------|-------------|
| `path` | Absolute destination path. |
| `file` | File part containing the raw content. |

### Response — `200 OK`
```json
{
  "data": {
    "sandbox_id": "sbx_01j9xr2t4fk8me3n5q",
    "path": "/workspace/script.py",
    "size": 16
  }
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox is not in `running` state. |
| 413 | — | File exceeds the 100 MB upload limit. |
```bash
# JSON (base64-encoded content)
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/files \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"path\": \"/workspace/script.py\", \"content\": \"$(base64 -w0 script.py)\"}"

# Multipart
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/files \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -F "path=/workspace/script.py" \
  -F "file=@script.py"
```

---

## Download a File

**`GET /api/v1/sandboxes/{id}/files/{path}`**

Downloads a file from the sandbox filesystem.

### Auth

Bearer token required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. Must be in `running` state. |
| `path` | string | URL-encoded path to the file inside the sandbox (leading `/` stripped). |

### Response — `200 OK`

Raw file bytes with `Content-Type: application/octet-stream`.

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `FILE_NOT_FOUND` | Path does not exist inside the sandbox. |
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox is not in `running` state. |
```bash
curl -o output.json \
  "https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/files/workspace%2Foutput.json" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## List Files

**`GET /api/v1/sandboxes/{id}/files?path=/workspace`**

Lists files and directories in a sandbox directory.
```bash
curl "https://api.miosa.ai/api/v1/sandboxes/{id}/files?path=/workspace" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Response:
```json
{
  "data": {
    "path": "/workspace",
    "entries": [
      {"name": "index.html", "path": "/workspace/index.html", "is_dir": false, "size": 128}
    ]
  }
}
```

---

## Stat a File

**`POST /api/v1/sandboxes/{id}/files/stat`**

Returns metadata for one file or directory.
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/files/stat \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/workspace/index.html"}'
```

---

## Read Logs

**`GET /api/v1/sandboxes/{id}/logs`**

Returns recent sandbox/template lifecycle logs. Pass `lines` to control the
tail length.
```bash
curl "https://api.miosa.ai/api/v1/sandboxes/{id}/logs?lines=200" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Stream logs with SSE:
```bash
curl -N "https://api.miosa.ai/api/v1/sandboxes/{id}/logs/stream" \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Accept: text/event-stream"
```

---

## Snapshot Lifecycle

**`POST /api/v1/sandboxes/{id}/snapshots`**

Creates a named checkpoint for a running sandbox.
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment":"before dependency upgrade"}'
```

List, inspect, restore, and delete snapshots:
```bash
curl https://api.miosa.ai/api/v1/sandboxes/{id}/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY"

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

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/restore/{snapshot_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/{id}/snapshots/{snapshot_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Pause and Resume

**`POST /api/v1/sandboxes/{id}/pause`**

Pauses a running sandbox using the Firecracker snapshot path. Paused sandboxes
keep their lifecycle record and can be resumed.
```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/pause \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/resume \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Subscribe to Events (SSE)

**`GET /api/v1/sandboxes/{id}/events`**

Opens a Server-Sent Events (SSE) stream that emits sandbox lifecycle events. The connection closes automatically when the sandbox reaches `destroyed` or `error`.

### Auth

Bearer token required (sent as `Authorization: Bearer &lt;key&gt;` header).

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Sandbox ID. |

### Response — `200 OK` (event stream)

`Content-Type: text/event-stream`

**Event: `state_changed`**
```

event: state_changed
data: {"state":"running","previous_state":"provisioning","timestamp":"2026-04-25T10:00:07Z"}
```

**Event: `exec_output`**
```

event: exec_output
data: {"exec_id":"exec_abc","stream":"stdout","data":"2\n","timestamp":"2026-04-25T10:00:10Z"}
```

**Event: `error`**
```

event: error
data: {"message":"VM terminated unexpectedly","timestamp":"2026-04-25T10:05:00Z"}
```
```bash
curl -N "https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q/events" \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Accept: text/event-stream"
```

---

## Sandbox Object

The full sandbox object returned by create, get, and list endpoints:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique sandbox identifier. |
| `tenant_id` | string | Owning tenant ID. |
| `owner_id` | string | Creating user ID. |
| `template_id` | string | Boot template name. |
| `state` | string | Current lifecycle state. |
| `cpu_count` | integer | Allocated vCPUs. |
| `memory_mb` | integer | Allocated RAM in MB. |
| `disk_size_mb` | integer | Allocated root disk in MB. |
| `image_id` | string | Resolved rootfs image, for example `miosa-sandbox`. |
| `boot_path` | string/null | Boot mechanism used, for example `snapshot` or `cold`. |
| `boot_ms` | integer/null | Runtime boot time in milliseconds once known. |
| `ready` | boolean | Whether envd and readiness checks are accepting work. |
| `ready_at` | string/null | ISO timestamp when `ready` became true. |
| `preview_url` | string/null | Tenant-aware base preview URL for the sandbox slug. Use `/expose` for a specific port. |
| `timeout_sec` | integer | Max seconds before force-destroy. |
| `total_runtime_sec` | integer \| null | Billed seconds. Set only after destruction. |
| `metadata` | object | Caller-supplied metadata. |
| `created_at` | string | ISO-8601 creation timestamp. |
| `started_at` | string \| null | ISO-8601 timestamp when VM entered `running`. |
| `destroyed_at` | string \| null | ISO-8601 timestamp when VM was destroyed. |

---

## Lifecycle States
```

provisioning → running → destroyed
running → paused → running
* → error  (terminal)
```

| State | Description |
|-------|-------------|
| `provisioning` | VM is booting. Exec and file operations are not yet available. |
| `running` | VM is reachable. All operations allowed. |
| `paused` | VM has a RAM snapshot on disk. Can be resumed. |
| `destroyed` | Terminal. VM is gone, billing is settled. |
| `error` | Terminal failure. Destroy and create a new sandbox. |

---

## Error Response Format

All error responses use this shape:
```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "sandbox not found",
    "details": null
  }
}
```

The `x-request-id` response header is set on every request. Include it in support requests.

---

## Rate Limits

| Limit | Value |
|-------|-------|
| Requests per minute per workspace | 300 |
| Concurrent sandboxes per tenant | 10 (contact support to increase) |
| Max sandbox runtime | Plan/policy dependent; day-long and always-on sandboxes are supported when billing policy allows it |
| Default resource shape | 1 vCPU, 1 GB RAM, 3 GB disk |
| Default resource caps | 4 vCPU, 8 GB RAM, 10 GB disk |
| Max exec timeout | 300 s (5 minutes) |
| Max file upload size | 100 MB |

Rate-limited responses return HTTP `429` with a `Retry-After` header indicating seconds to wait.

---

## See also

- [Python SDK](/docs/sdks/python/) — `miosa`
- [TypeScript SDK](/docs/sdks/typescript/) — `@miosa/sdk`
- [Go SDK](/docs/sdks/go/) — `github.com/miosa-ai/miosa-go`
- [Java SDK](/docs/sdks/java/) — `ai.miosa:miosa-sdk`
- [Elixir SDK](/docs/sdks/elixir/) — `:miosa`
- [Events (SSE)](/docs/api-reference/events/) — SSE reference for other MIOSA resources
- [Error Codes](/docs/api-reference/errors/) — full error code catalog including sandbox-specific codes

---

# Services API

URL: https://miosa.ai/docs/api-reference/services
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/services
Source: src/routes/docs/api-reference/services/+page.md
Description: API reference for managing long-running systemd services inside MIOSA computers.

Services are persistent processes managed by systemd inside a computer. Use them for web servers, background workers, databases, or any daemon that should survive across exec calls and restart automatically on failure.

Base path: `/api/v1/computers/{id}/services`

Services map directly to systemd unit files (`/etc/systemd/system/miosa-{name}.service`) managed by the in-VM envd daemon. The computer must be **running** to interact with services.

---

## Quick Start
```typescript

const client = new Miosa();

// Register and start a web server
const svc = await client.services.create(computerId, {
  name: 'webserver',
  command: 'python3 -m http.server 8080',
  cwd: '/home/user/app',
  restart: 'always',
});

console.log(svc.status); // "starting"

// Check status later
const updated = await client.services.get(computerId, svc.id);
console.log(updated.status); // "running"
```
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "webserver",
    "command": "python3 -m http.server 8080",
    "cwd": "/home/user/app",
    "restart": "always"
  }'
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/computers/{id}/services` | Create and start a service |
| `GET` | `/computers/{id}/services` | List all services on a computer |
| `GET` | `/computers/{id}/services/{name}` | Get a service by name |
| `POST` | `/computers/{id}/services/{name}/start` | Start a stopped service |
| `POST` | `/computers/{id}/services/{name}/stop` | Stop a running service |
| `POST` | `/computers/{id}/services/{name}/restart` | Restart a service |
| `DELETE` | `/computers/{id}/services/{name}` | Remove a service |

---

## Create a Service

**`POST /api/v1/computers/{id}/services`**

Writes the systemd unit file and starts the service.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Service name. Pattern: `[a-z][a-z0-9-]{0,62}` |
| `command` | string | Yes | Full command to run |
| `env` | object | No | Environment variables as `{ "KEY": "value" }` |
| `cwd` | string | No | Working directory (default: `/home/user`) |
| `restart` | string | No | `"always"`, `"on-failure"` (default), or `"no"` |

### Response — `201 Created`
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "...",
    "tenant_id": "...",
    "name": "webserver",
    "command": "python3 -m http.server 8080",
    "env": {},
    "cwd": "/home/user/app",
    "restart": "always",
    "status": "starting",
    "pid": null,
    "exit_code": null,
    "last_started_at": null,
    "last_exited_at": null,
    "created_at": "2026-04-11T00:00:00Z",
    "updated_at": "2026-04-11T00:00:00Z"
  }
}
```

### Status Values

| Status | Description |
|--------|-------------|
| `stopped` | Registered but not started |
| `starting` | Start dispatched to systemd |
| `running` | systemd reports `ActiveState=active` |
| `failed` | systemd reports `ActiveState=failed` |
| `removed` | Unit file deleted; record kept for audit |

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `a service with this name already exists` | Name must be unique per computer |
| 422 | Validation error | Invalid name format or restart policy |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-server",
    "command": "/home/user/app/server",
    "env": {"PORT": "3000", "NODE_ENV": "production"},
    "cwd": "/home/user/app",
    "restart": "on-failure"
  }'
```

---

## List Services

**`GET /api/v1/computers/{id}/services`**

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "...",
      "name": "webserver",
      "status": "running",
      "pid": 12345,
      "restart": "always",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/services \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get a Service

**`GET /api/v1/computers/{id}/services/{name}`**

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Computer ID |
| `name` | string | Service name |

### Response — `200 OK`

Full service object (same as create response).

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `service not found` | Does not exist on this computer |

---

## Start, Stop, Restart

**`POST /api/v1/computers/{id}/services/{name}/start`**
**`POST /api/v1/computers/{id}/services/{name}/stop`**
**`POST /api/v1/computers/{id}/services/{name}/restart`**

All return a `200 OK` with the updated service object.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `service is already running` | Cannot start a running service |
| 409 | `service is not running` | Cannot stop a non-running service |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
# Stop a service
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services/webserver/stop \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Restart it
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services/webserver/restart \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Remove a Service

**`DELETE /api/v1/computers/{id}/services/{name}`**

Stops the service and removes the systemd unit file. The database record transitions to `"removed"` status.

### Response — `200 OK`
```json
{
  "data": { "name": "webserver", "status": "removed" }
}
```
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/services/webserver \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Common Recipes

### Deploy a Node.js app as a service
```typescript
// Upload app files first
await client.files.write(computerId, {
  path: '/home/user/app/server.js',
  content: serverJsContent,
});

// Register and start
const svc = await client.services.create(computerId, {
  name: 'node-app',
  command: 'node /home/user/app/server.js',
  env: { PORT: '3000' },
  restart: 'on-failure',
});
```

### Wait until a service is running
```python

svc = client.services.create(computer_id, name="worker", command="/usr/bin/worker")
while svc.status == "starting":
    time.sleep(1)
    svc = client.services.get(computer_id, svc.name)

if svc.status != "running":
    raise RuntimeError(f"Service failed to start: {svc.status}")
```

### Check for failed services in a fleet
```typescript
const computers = await client.computers.list();
for (const computer of computers.data) {
  if (computer.status !== 'running') continue;
  const services = await client.services.list(computer.id);
  const failed = services.data.filter(s => s.status === 'failed');
  if (failed.length > 0) {
    console.log(`${computer.name}: ${failed.length} failed services`);
  }
}
```

---

# Snapshots API

URL: https://miosa.ai/docs/api-reference/snapshots
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/snapshots
Source: src/routes/docs/api-reference/snapshots/+page.md
Description: API reference for creating, listing, and restoring Firecracker VM snapshots (checkpoints).

Snapshots capture the full in-memory state of a running computer — CPU state, RAM, and filesystem — and store it durably. Restore a snapshot to spin up an identical computer in seconds.

Base path: `/api/v1/computers/{id}/snapshots`

Snapshots require the computer to be **running**. Creating a snapshot does not stop the computer.

---

## Quick Start
```typescript

const client = new Miosa();

// Create a snapshot
const snap = await client.snapshots.create(computerId, {
  comment: 'before-deploy-v2',
});

// Poll until ready
let status = snap.status;
while (status !== 'ready') {
  await new Promise(r => setTimeout(r, 3000));
  const updated = await client.snapshots.get(computerId, snap.id);
  status = updated.status;
}

// Restore — creates a new computer from the snapshot
const restored = await client.snapshots.restore(computerId, snap.id);
console.log(`Restored computer: ${restored.id}`);
```
```bash
# Create a snapshot
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "before-deploy-v2"}'
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/computers/{id}/snapshots` | Create a snapshot |
| `GET` | `/computers/{id}/snapshots` | List snapshots for a computer |
| `GET` | `/computers/{id}/snapshots/{snap_id}` | Get a snapshot |
| `DELETE` | `/computers/{id}/snapshots/{snap_id}` | Delete a snapshot |
| `POST` | `/computers/{id}/restore/{snap_id}` | Restore from snapshot |
| `GET` | `/computers/{id}/snapshots/{snap_id}/events` | SSE progress stream |

---

## Create a Snapshot

**`POST /api/v1/computers/{id}/snapshots`**

Initiates an asynchronous snapshot. The returned status will be `"creating"`. Poll `GET /snapshots/{snap_id}` or subscribe to SSE events for progress.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comment` | string | No | Human-readable label (max 500 chars) |

### Response — `201 Created`
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "...",
    "tenant_id": "...",
    "comment": "before-deploy-v2",
    "status": "creating",
    "state_size_bytes": null,
    "memory_size_bytes": null,
    "rootfs_size_bytes": null,
    "compressed_size_bytes": null,
    "s3_bucket": null,
    "s3_prefix": null,
    "error": null,
    "created_at": "2026-04-11T00:00:00Z",
    "updated_at": "2026-04-11T00:00:00Z"
  }
}
```

### Status State Machine
```

creating → uploading → ready
any      → failed
ready    → deleted
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `computer not found` | Computer does not exist or wrong tenant |
| 409 | `computer is not running` | Snapshot requires running VM |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "checkpoint-before-risky-op"}'
```

---

## List Snapshots

**`GET /api/v1/computers/{id}/snapshots`**

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "...",
      "comment": "before-deploy-v2",
      "status": "ready",
      "compressed_size_bytes": 524288000,
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get a Snapshot

**`GET /api/v1/computers/{id}/snapshots/{snap_id}`**

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Computer ID |
| `snap_id` | UUID | Snapshot ID |

### Response — `200 OK`

Full snapshot object (same shape as create response).

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Snapshot belongs to a different tenant |
| 404 | `snapshot not found` | Does not exist |
```bash
curl https://api.miosa.ai/api/v1/computers/{id}/snapshots/{snap_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Delete a Snapshot

**`DELETE /api/v1/computers/{id}/snapshots/{snap_id}`**

Soft-deletes the snapshot (transitions to `"deleted"` status). S3 objects are cleaned up asynchronously.

### Response — `200 OK`
```json
{
  "data": {
    "id": "...",
    "status": "deleted"
  }
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `snapshot not found` | Does not exist |
| 409 | `snapshot is not in a deletable state` | Snapshot is being restored |
```bash
curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/snapshots/{snap_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Restore from Snapshot

**`POST /api/v1/computers/{id}/restore/{snap_id}`**

Creates a new computer with the state from the snapshot. The original computer is unchanged.

### Response — `201 Created`
```json
{
  "data": {
    "id": "new-computer-uuid",
    "name": "my-computer-restored",
    "status": "provisioning",
    "size": "small"
  },
  "snapshot": {
    "id": "snap-uuid",
    "status": "restoring"
  }
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `snapshot not found` | Does not exist |
| 409 | `snapshot is not ready` | Snapshot must be in `ready` state |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/restore/{snap_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## SSE Progress Stream

**`GET /api/v1/computers/{id}/snapshots/{snap_id}/events`**

Subscribe to real-time snapshot progress. Requires a short-lived ticket rather than a Bearer token (browsers cannot set Authorization on EventSource connections).

### Event Types

| Event | Description |
|-------|-------------|
| `snapshot_creating` | Firecracker writing memory and VM state to disk |
| `snapshot_uploading` | Compressing and uploading to object storage |
| `snapshot_ready` | Upload complete; snapshot is usable |
| `snapshot_failed` | Unrecoverable error — see `error` field |

---

## Common Recipes

### Automated checkpoint before risky operations
```python
from miosa import Miosa

client = Miosa()

snap = client.snapshots.create(computer_id, comment="pre-migration")
while snap.status not in ("ready", "failed"):
    time.sleep(2)
    snap = client.snapshots.get(computer_id, snap.id)

if snap.status == "failed":
    raise RuntimeError(f"Snapshot failed: {snap.error}")

# Proceed with risky operation knowing you can restore
do_migration(computer_id)
```

### Snapshot-based parallelism (clone a baseline)
```typescript
// Build a baseline environment once, clone it N times for parallel jobs
const baseline = await client.snapshots.create(setupComputerId, {
  comment: 'baseline-env',
});

// Each restore creates an independent computer from the same state
const workers = await Promise.all(
  Array.from({ length: 5 }, () =>
    client.snapshots.restore(setupComputerId, baseline.id)
  )
);
```

---

## See also

- [Computers API](/docs/api-reference/computers/) — computer lifecycle and clone endpoint
- [Events (SSE)](/docs/api-reference/events/) — stream snapshot progress events
- [Error Codes](/docs/api-reference/errors/) — snapshot-specific error codes

---

# Streaming Exec API

URL: https://miosa.ai/docs/api-reference/streaming-exec
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/streaming-exec
Source: src/routes/docs/api-reference/streaming-exec/+page.md
Description: API reference for streaming command output in real-time from MIOSA computers via SSE.

Streaming exec runs a command on a computer and delivers output line-by-line via Server-Sent Events. Use it for long-running builds, installs, or any command where you want incremental output rather than waiting for completion.

Base path: `/api/v1/computers/{id}/exec/stream`

Standard `POST /computers/{id}/exec` waits for the command to finish before returning. Streaming exec is better for commands that run longer than a few seconds or that you want to monitor interactively.

---

## Quick Start
```typescript

const client = new Miosa();

// Stream a long-running build
for await (const event of client.exec.stream(computerId, {
  command: 'pip install torch',
  timeout: 300,
})) {
  if (event.type === 'output') {
    process.stdout.write(event.data.line);
  } else if (event.type === 'exit') {
    console.log(`Exit code: ${event.data.exitCode}`);
    break;
  }
}
```
```bash
# Obtain a streaming ticket first, then connect
TICKET=$(curl -s -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/stream \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "pip install torch", "timeout": 300}' | jq -r .ticket)

curl -N "https://api.miosa.ai/api/v1/computers/{id}/exec/stream/events?ticket=$TICKET" \
  -H "Accept: text/event-stream"
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/computers/{id}/exec/stream` | Start a streaming exec and obtain a ticket |
| `GET` | `/computers/{id}/exec/stream/events` | SSE stream (requires ticket) |
| `POST` | `/computers/{id}/exec` | Non-streaming exec (waits for completion) |
| `POST` | `/computers/{id}/exec/python` | Non-streaming Python exec |

---

## Start Streaming Exec

**`POST /api/v1/computers/{id}/exec/stream`**

Starts the command and returns a short-lived ticket for the SSE stream.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Shell command to execute |
| `timeout` | integer | No | Timeout in seconds (default: 30, max: 300) |
| `shell` | string | No | Shell to use (default: `/bin/bash`) |

### Response — `202 Accepted`
```json
{
  "ticket": "exec_short_lived_token",
  "expires_at": 1712700060,
  "stream_url": "/api/v1/computers/{id}/exec/stream/events?ticket=exec_short_lived_token"
}
```

The ticket expires in 60 seconds — open the EventSource connection immediately.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 409 | `COMPUTER_NOT_RUNNING` | Computer is not running |
| 502 | `AGENT_UNAVAILABLE` | In-VM agent unreachable |
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/stream \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm install", "timeout": 120}'
```

---

## Connect to SSE Stream

**`GET /api/v1/computers/{id}/exec/stream/events?ticket={ticket}`**

### Event Types

| Event | Payload Fields | Description |
|-------|---------------|-------------|
| `output` | `line`, `stream` | A line of stdout or stderr |
| `exit` | `exit_code`, `duration_ms` | Command finished; stream closes after this |
| `timeout` | `timeout_seconds` | Command killed after timeout |
| `error` | `message` | Internal error before command started |

### Event Payload Examples
```

event: output
data: {"line": "Collecting torch\n", "stream": "stdout"}

event: output
data: {"line": "  Downloading torch-2.3.0-...\n", "stream": "stdout"}

event: exit
data: {"exit_code": 0, "duration_ms": 45312}
```

### `stream` Values

| Value | Description |
|-------|-------------|
| `stdout` | Standard output |
| `stderr` | Standard error |
```javascript
// Browser
const es = new EventSource(`/api/v1/computers/${id}/exec/stream/events?ticket=${ticket}`);

es.addEventListener('output', e => {
  const { line, stream } = JSON.parse(e.data);
  console.log(`[${stream}] ${line}`);
});

es.addEventListener('exit', e => {
  const { exit_code } = JSON.parse(e.data);
  console.log(`Exited with code ${exit_code}`);
  es.close();
});

es.addEventListener('error', () => {
  // Connection dropped or ticket expired
  es.close();
});
```

---

## Comparison: Streaming vs Non-Streaming

| Aspect | `POST /exec` | `POST /exec/stream` |
|--------|-------------|---------------------|
| Response timing | After command completes | Immediate (ticket) |
| Output delivery | All at once | Line by line via SSE |
| Max timeout | 300 s | 300 s |
| Best for | Quick commands | Long builds, installs |
| SDK method | `exec.run()` | `exec.stream()` |

---

## Common Recipes

### Monitor a build
```python
for event in client.exec.stream(computer_id, command="make build", timeout=300):
    if event.type == "output":
        print(event.data["line"], end="")
    elif event.type == "exit":
        if event.data["exit_code"] != 0:
            raise RuntimeError(f"Build failed with exit code {event.data['exit_code']}")
        print("Build succeeded")
        break
```

### Capture both streams separately
```typescript
const stdout: string[] = [];
const stderr: string[] = [];

for await (const event of client.exec.stream(computerId, { command: 'myapp 2>&1 | tee /tmp/output.log' })) {
  if (event.type === 'output') {
    if (event.data.stream === 'stdout') stdout.push(event.data.line);
    else stderr.push(event.data.line);
  } else if (event.type === 'exit') {
    break;
  }
}
```

### Timeout handling
```python
try:
    for event in client.exec.stream(computer_id, command="long-task", timeout=60):
        if event.type == "timeout":
            print(f"Command killed after {event.data['timeout_seconds']}s")
            break
        elif event.type == "exit":
            break
except Exception as e:
    print(f"Stream error: {e}")
```

---

# API Reference / Versions

URL: https://miosa.ai/docs/api-reference/versions
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/versions
Source: src/routes/docs/api-reference/versions/+page.md
Description: Immutable deployment version sub-resource. List, get, promote, archive.

A **Deployment Version** is the immutable record of one publish. See [Versions](/docs/deploy/versions/) for the conceptual model.

## Endpoints
```http
GET  /api/v1/deployments/:id/versions
GET  /api/v1/deployments/:id/versions/:version_id
POST /api/v1/deployments/:id/versions/:version_id/promote
```

## List
```http
GET /api/v1/deployments/:id/versions
GET /api/v1/deployments/:id/versions?state=ready
GET /api/v1/deployments/:id/versions?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/deployments/:id/versions?external_workspace_id=clinic_123
GET /api/v1/deployments/:id/versions?limit=50&cursor=...
```

Response:
```json
{
  "data": [
    {
      "id": "ver_...",
      "deployment_id": "dep_...",
      "version_number": 17,
      "kind": "static",
      "state": "ready",
      "artifact_sha256": "a5e6f0c1...",
      "source_sha256": "f1a3b8c2...",
      "promoted_at": "2026-05-14T18:20:00Z",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "660e8400-e29b-41d4-a716-446655440001",
      "external_workspace_id": "clinic_123",
      "external_user_id": "dr-smith-456",
      "created_at": "2026-05-14T18:19:48Z"
    }
  ],
  "next_cursor": "..."
}
```

## Get
```http
GET /api/v1/deployments/:id/versions/:version_id
```

Returns the full version row including `artifact_manifest`, `runtime_image`, `runtime_command`, `runtime_port`, `health_check_path`, `build_log_uri`.

## Promote

Make a specific ready version the active one for the deployment.
```http
POST /api/v1/deployments/:id/versions/:version_id/promote
```

Body: empty, or optionally `{ "environment": "production" }`.

Scopes: `deployments:write`. Requires `Idempotency-Key` for safety on retries.

Promotion is different from publish:
- **Publish** creates a new version from a sandbox source.
- **Promote** points an existing ready version as active in an environment.

Use promote for canary / staged rollouts: publish to a non-production environment first, validate, then promote to production.

## States

| State | Meaning |
|---|---|
| `created` | Row exists, build not started |
| `building` | Build in progress |
| `ready` | Build succeeded, artifact uploaded, promotable |
| `failed` | Build or health check failed |
| `archived` | Promoted-out-of; still bootable for rollback |

State transitions are one-way. Once `ready` or `failed`, a version stays that way.

## Permissions

| Action | Scope |
|---|---|
| List, Get | `deployments:read` |
| Promote | `deployments:write` |

## See also

- [Deployments](/docs/api-reference/deployments/) — parent resource
- [Releases](/docs/api-reference/releases/) — artifact reference
- [Versions](/docs/deploy/versions/) — conceptual model
- [Rollback](/docs/deploy/rollback/) — uses promote internally

---

# Workspaces API

URL: https://miosa.ai/docs/api-reference/workspaces
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/workspaces
Source: src/routes/docs/api-reference/workspaces/+page.md
Description: API reference for creating and managing MIOSA workspaces - the customer/client layer inside an organization.

Workspaces group resources inside an organization. In a white-label platform, a workspace usually represents one downstream customer or client, such as `Dr. Smith Clinic` inside the `ClinicIQ` organization. Projects live inside workspaces, and sandboxes, computers, deployments, databases, storage buckets, volumes, functions, jobs, and domains belong to projects.

Base path: `/api/v1/workspaces`

A **default** workspace is created automatically when you sign up. Resources are assigned to the default workspace and its default project unless you specify workspace/project ownership at creation time.

---

## Quick Start
```typescript

const client = new Miosa(); // reads MIOSA_API_KEY

// Create a workspace for a downstream customer
const ws = await client.workspaces.create({
  name: 'Dr. Smith Clinic',
  slug: 'dr-smith-clinic',
  externalWorkspaceId: 'clinic_123',
});

// Create a computer inside a project in that workspace
const computer = await client.computers.create({
  name: 'clinic-builder',
  templateType: 'miosa-desktop',
  workspaceId: ws.id,
  projectSlug: 'lead-magnet',
  projectName: 'Lead Magnet',
});

// List computers in the workspace
const { data } = await client.workspaces.listComputers(ws.id);
```
```bash
# curl equivalent
curl -X POST https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dr. Smith Clinic", "slug": "dr-smith-clinic", "external_workspace_id": "clinic_123"}'
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/workspaces` | List workspaces for the tenant |
| `POST` | `/workspaces` | Create a workspace |
| `GET` | `/workspaces/{id}` | Get a workspace |
| `PATCH` | `/workspaces/{id}` | Update a workspace |
| `PUT` | `/workspaces/{id}/settings` | Update workspace-level resource limits |
| `GET` | `/workspaces/{id}/preview-domain` | Read the workspace preview domain |
| `PUT` | `/workspaces/{id}/preview-domain` | Set the workspace preview domain |
| `DELETE` | `/workspaces/{id}/preview-domain` | Clear the workspace preview domain |
| `GET` | `/workspaces/{id}/preview-domain/verify` | Check DNS readiness |
| `DELETE` | `/workspaces/{id}` | Delete a workspace |
| `GET` | `/workspaces/{id}/computers` | List computers in a workspace |
| `GET` | `/workspaces/{id}/stats` | Computer counts and resource totals |
| `GET` | `/workspaces/{id}/usage` | Time-series credit and compute usage |
| `GET` | `/workspaces/{id}/projects` | List projects in a workspace |

---

## List Workspaces

**`GET /api/v1/workspaces`**

Returns all workspaces belonging to the authenticated tenant.

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "...",
      "name": "default",
      "slug": "default",
      "external_workspace_id": null,
      "description": null,
      "metadata": {},
      "is_default": true,
      "computer_count": 3,
      "created_at": "2026-04-11T00:00:00Z",
      "updated_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Create a Workspace

**`POST /api/v1/workspaces`**

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Human-readable name (1–120 chars) |
| `slug` | string | No | URL-safe identifier. Auto-derived from `name` if omitted. Pattern: `[a-z0-9][a-z0-9-]{0,79}` |
| `external_workspace_id` | string | No | Your customer/account/workspace ID. Globally unique inside this MIOSA organization. |
| `description` | string | No | Optional description |
| `metadata` | object | No | Caller metadata stored on the workspace. |

### Response — `201 Created`

Full workspace object (same shape as list items above).

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 422 | `has already been taken` | Slug already exists in tenant |
| 422 | `must start with alphanumeric and contain only a-z 0-9 -` | Invalid slug format |
```bash
curl -X POST https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dr. Smith Clinic",
    "slug": "dr-smith-clinic",
    "external_workspace_id": "clinic_123",
    "description": "Client workspace for Dr. Smith Clinic"
  }'
```

---

## Get a Workspace

**`GET /api/v1/workspaces/{id}`**

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Workspace ID |

### Response — `200 OK`

Full workspace object.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Workspace belongs to a different tenant |
| 404 | `workspace not found` | Does not exist |
```bash
curl https://api.miosa.ai/api/v1/workspaces/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Update a Workspace

**`PATCH /api/v1/workspaces/{id}`**

Update mutable workspace fields. Prefer treating the slug as stable once resources and URLs exist.

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New display name |
| `slug` | string | New URL-safe slug. Must remain unique inside the organization. |
| `description` | string | New description (`null` to clear) |
| `external_workspace_id` | string | Your customer/account/workspace ID |
| `metadata` | object | Replacement metadata map |

### Response — `200 OK`

Updated workspace object.

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Wrong tenant |
| 404 | `workspace not found` | Does not exist |
```bash
curl -X PATCH https://api.miosa.ai/api/v1/workspaces/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-us-east"}'
```

---

## Delete a Workspace

**`DELETE /api/v1/workspaces/{id}`**

Deletes an empty workspace. Fails if the workspace contains computers or projects.

### Response — `200 OK`
```json
{ "deleted": true }
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Wrong tenant |
| 404 | `workspace not found` | Does not exist |
| 409 | `workspace has computers` | Remove or move resources first |
```bash
curl -X DELETE https://api.miosa.ai/api/v1/workspaces/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Update Workspace Settings

**`PUT /api/v1/workspaces/{id}/settings`**

Applies resource limits and default preferences for the workspace. These limits cap what any computer inside the workspace can do. Tenant-level limits still apply as a ceiling.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `max_computers` | integer | No | Maximum number of computers allowed in this workspace. `null` = no workspace-level cap (tenant limit applies). |
| `max_computer_size` | string | No | Maximum `size` value a computer in this workspace may be created with: `"small"`, `"medium"`, or `"large"`. |
| `default_computer_size` | string | No | Default `size` applied when creating a computer without an explicit `size`. |
| `default_auto_stop_seconds` | integer | No | Auto-stop idle timeout (seconds) applied to new computers by default. `0` = no auto-stop. |
| `allowed_template_types` | string[] | No | Allowlist of template names that can be used in this workspace. Empty array = all templates allowed. |

### Response — `200 OK`
```json
{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "settings": {
    "max_computers": 10,
    "max_computer_size": "large",
    "default_computer_size": "small",
    "default_auto_stop_seconds": 3600,
    "allowed_template_types": []
  },
  "updated_at": "2026-05-17T10:00:00Z"
}
```

---

## Workspace Preview Domain

**`PUT /api/v1/workspaces/{id}/preview-domain`**

Sets a client/workspace-level base domain for generated URLs. This overrides the organization preview domain for resources in this workspace unless a project has its own preview domain.

```bash
curl -X PUT https://api.miosa.ai/api/v1/workspaces/{id}/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview_domain":"drsmithclinic.com"}'
```

Response:
```json
{
  "scope": "workspace",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "preview_domain": "drsmithclinic.com",
  "effective_domain": "drsmithclinic.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "url_examples": {
    "default_preview": "https://<slug>.drsmithclinic.com",
    "port_preview": "https://3000-<slug>.sandbox.drsmithclinic.com",
    "deployment": "https://<deployment-slug>.drsmithclinic.com"
  }
}
```

Required DNS records:

| Record type | Name | Value |
|---|---|---|
| `CNAME` | `*` | `proxy.miosa.ai` |
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` |

Verify:
```bash
curl https://api.miosa.ai/api/v1/workspaces/{id}/preview-domain/verify \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Clear and inherit from the organization/domain fallback:
```bash
curl -X DELETE https://api.miosa.ai/api/v1/workspaces/{id}/preview-domain \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Wrong tenant |
| 404 | `workspace not found` | Does not exist |
| 422 | `VALIDATION_FAILED` | Unknown size value or invalid limit |
```bash
curl -X PUT https://api.miosa.ai/api/v1/workspaces/{id}/settings \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_computers": 10,
    "max_computer_size": "large",
    "default_auto_stop_seconds": 3600
  }'
```

---

## List Computers in a Workspace

**`GET /api/v1/workspaces/{id}/computers`**

### Response — `200 OK`
```json
{
  "data": [
    {
      "id": "...",
      "name": "runner-1",
      "status": "running",
      "size": "small",
      "template_type": "miosa-desktop",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/workspaces/{id}/computers \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## List Projects in a Workspace

**`GET /api/v1/workspaces/{id}/projects`**

Returns the projects owned by a workspace. Use this for client dashboards before listing the sandboxes, computers, deployments, and databases inside a project.

### Response - `200 OK`
```json
{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "tenant_id": "...",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "external_workspace_id": "clinic_123",
      "external_project_id": "project_789",
      "name": "Lead Magnet",
      "slug": "lead-magnet",
      "description": null,
      "metadata": {},
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:00:00Z"
    }
  ],
  "total": 1
}
```
```bash
curl https://api.miosa.ai/api/v1/workspaces/{id}/projects \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Workspace Stats

**`GET /api/v1/workspaces/{id}/stats`**

Returns a snapshot of computer counts grouped by status and the aggregate resource footprint for the workspace.

### Response — `200 OK`
```json
{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "computers": {
    "total": 5,
    "by_status": {
      "running": 3,
      "stopped": 2,
      "provisioning": 0,
      "error": 0
    }
  },
  "resources": {
    "total_vcpus": 7,
    "total_memory_mb": 28672,
    "total_disk_gb": 160
  },
  "settings": {
    "max_computers": 10,
    "max_computer_size": "large",
    "default_auto_stop_seconds": 3600
  }
}
```
```bash
curl https://api.miosa.ai/api/v1/workspaces/{id}/stats \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Get Workspace Usage

**`GET /api/v1/workspaces/{id}/usage`**

Returns time-series credit consumption and compute-hour totals for the workspace over a given window. Use this for per-workspace cost attribution dashboards.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `window` | string | `"24h"` (default), `"7d"`, `"30d"` |
| `granularity` | string | `"hour"` (default), `"day"` — bucket size for the time-series data |

### Response — `200 OK`
```json
{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "window": "7d",
  "granularity": "day",
  "total_credits_used": 1284,
  "total_compute_hours": 42.5,
  "series": [
    {
      "ts": "2026-05-10T00:00:00Z",
      "credits_used": 198,
      "compute_hours": 6.6
    },
    {
      "ts": "2026-05-11T00:00:00Z",
      "credits_used": 211,
      "compute_hours": 7.0
    }
  ]
}
```

### Errors

| Status | Error | Cause |
|--------|-------|-------|
| 403 | `forbidden` | Wrong tenant |
| 404 | `workspace not found` | Does not exist |
| 422 | `VALIDATION_FAILED` | Unknown `window` or `granularity` value |
```bash
curl "https://api.miosa.ai/api/v1/workspaces/{id}/usage?window=7d&granularity=day" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

---

## Common Recipes

### Move all computers to a new workspace

Computers do not yet support a `move` operation on workspace assignment via `PATCH /computers/{id}`. Use the `POST /computers/{id}/move` endpoint instead:
```bash
curl -X POST https://api.miosa.ai/api/v1/computers/{computer_id}/move \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": "target-workspace-id"}'
```

### Enumerate all workspaces and their sizes
```typescript
const { data: workspaces } = await client.workspaces.list();
for (const ws of workspaces) {
  console.log(`${ws.name}: ${ws.computerCount} computers`);
}
```

### Default workspace ID lookup

If you need the default workspace ID programmatically:
```typescript
const { data } = await client.workspaces.list();
const defaultWs = data.find(ws => ws.isDefault);
console.log(defaultWs.id);
```

---

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 403 | `forbidden` | Workspace belongs to a different tenant |
| 404 | `workspace not found` | Does not exist |
| 409 | `workspace has computers` | Cannot delete a workspace that contains computers |
| 422 | `VALIDATION_FAILED` | Name or slug failed schema validation |

---

## See also

- [Computers API](/docs/api-reference/computers/) — computers are scoped to workspaces
- [Projects API](/docs/api-reference/projects/) — projects live inside workspaces
- [Error Codes](/docs/api-reference/errors/) — `VALIDATION_FAILED` and general errors

---

# Authentication

URL: https://miosa.ai/docs/authentication
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/authentication
Source: src/routes/docs/authentication/+page.md
Description: How to authenticate with the MIOSA API using msk_ API keys or JWT tokens.

# Authentication

Every MIOSA API request carries a single `Authorization: Bearer &lt;token&gt;` header.
The token is either an **API key** (prefix `msk_`) or a **JWT** from `POST /auth/login`.

One key covers the entire platform — computers, desktop, files, exec, CUA agent,
OSA, credits, and (with the right role) admin. No separate keys for AI, no
per-product configuration.

## Credential hierarchy

Diagram:
graph TB
    MSK[msk_live_* workspace key] -->|server-side only| API[MIOSA API calls]
    MSK -->|mints via POST /previews/:id/share| BT[Browser token - scoped + short-lived]
    BT -->|browser only| EP[Specific sandbox endpoint]
    MSK -->|mints via POST /auth/sse-ticket| ST[SSE ticket - single use]
    ST -->|EventSource| SS[SSE stream]

## API Keys

### Key format
```

msk_<role>_<random>
```

| Prefix | Role | Capabilities |
|--------|----------|---------------------------------------------------|
| `msk_u_...` | user | Compute, desktop, files, CUA, OSA, credits |
| `msk_a_...` | admin | Everything above **+** `/api/v1/admin/*` |
| `msk_p_...` | platform | Tenant-wide automation issued by the MIOSA platform |

Role is **orthogonal** to `purpose`, which picks the backend the key can call:

- `purpose: api` — compute, desktop, files, CUA, OSA, credits
- `purpose: optimal` — AI/LLM proxy (`/v1/chat/completions`, `/v1/responses`)

If you need both, create two keys. They share the `msk_` family so SDK
configuration is identical.

### Creating an API key
```bash
curl -X POST https://api.miosa.ai/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production SDK Key",
    "key_type": "user",
    "purpose": "api"
  }'
```
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "msk_u_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "key_prefix": "msk_u_a1b2c3",
    "name": "Production SDK Key",
    "key_type": "user",
    "key_purpose": "api",
    "rate_limit_rpm": 60,
    "status": "active",
    "created_at": "2026-04-17T00:00:00Z"
  }
}
```

The raw key is **only returned once** at creation. Store it securely. If lost,
revoke it and create a new one — the original cannot be recovered.

User-role callers can only mint `user` keys. Admin and platform callers may
mint any `key_type`. To issue admin keys programmatically, use the admin
variant at `POST /admin/api-keys` (operator-internal — not part of the public docs).

### Using an API key

Pass the key in the `Authorization` header:
```bash
curl https://api.miosa.ai/api/v1/computers \
  -H "Authorization: Bearer msk_u_a1b2c3d4e5f6..."
```

All five SDKs read `MIOSA_API_KEY` from the environment by default:

```python
  from miosa import Miosa

  # Explicit key
  client = Miosa(api_key="msk_u_...")

  # Or from environment: export MIOSA_API_KEY="msk_u_..."
  client = Miosa()
```

```ts

  // Explicit key
  const miosa = new Miosa({ apiKey: 'msk_u_...' });
```

```go

  // Explicit key
  client := miosa.NewClient("msk_u_...")

  // Or from environment
  client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))
```

```elixir
  # Explicit key
  client = Miosa.client("msk_u_...")

  # Or from environment
  client = Miosa.client(System.fetch_env!("MIOSA_API_KEY"))
```

```java

  MiosaClient miosa = new MiosaClient("msk_u_...");
```

### Managing keys

| Action | Endpoint |
|--------|----------|
| List your keys | `GET /api/v1/api-keys` |
| Create a key | `POST /api/v1/api-keys` |
| Revoke a key | `DELETE /api/v1/api-keys/{id}` |

Revoking a key flips its status to `revoked`. The change is cached and
enforced within seconds — subsequent requests return `401 Unauthorized`.
Revocation is irreversible; create a new key if you need access restored.

### Admin keys

`msk_a_*` and `msk_p_*` keys unlock everything under `/api/v1/admin/*` —
user management, tenant operations, credit grants, fleet-wide computer
control, Optimal model switching. These are gated behind the same
`RequireAdmin` plug as admin JWTs.

User-role callers hitting an admin endpoint receive `403 Forbidden`.

Admin endpoints are operator-internal and not documented publicly.

## JWT Tokens

JWT tokens are used by the MIOSA web UI and SSE ticket flows. They are issued
on login and carry user identity + tenant context.

### Obtaining a token
```bash
curl -X POST https://api.miosa.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password"}'
```
```json
{
  "token": "eyJhbGciOiJIUzUxMiIs...",
  "refresh_token": "eyJhbGciOiJIUzUxMiIs...",
  "user": { "id": "...", "email": "user@example.com" }
}
```

### Token lifecycle

| Token | Lifetime | Refresh |
|-------|----------|---------|
| Access token | ~1 hour | Use refresh token |
| Refresh token | 7 days | Re-login required |
```bash
curl -X POST https://api.miosa.ai/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzUxMiIs..."}'
```

For programmatic access, use **API keys**. JWTs are designed for browser
sessions and expire frequently.

## SSE streams

Server-Sent Event endpoints (CUA session events) cannot use a standard
`Authorization` header because `EventSource` does not support custom headers.
Instead, mint a one-time ticket first:
```bash
# 1. Ask for a ticket (Bearer-authed — API key or JWT both work)
curl -X POST \
  https://api.miosa.ai/api/v1/computers/{id}/cua/sessions/{session_id}/sse-ticket \
  -H "Authorization: Bearer msk_u_..."

# {"ticket":"sset_abc123","expires_in":3600,"session_id":"..."}

# 2. Open the stream with the ticket as a query param
curl https://api.miosa.ai/api/v1/computers/{id}/cua/sessions/{session_id}/events?ticket=sset_abc123
```

The ticket is single-use and expires after one hour.

## Rate limits

| Scope | Limit | Window |
|-------|-------|--------|
| Developer API (`/api/v1/*`) | 300 requests | Per minute per key |
| Admin API (`/api/v1/admin/*`) | 300 requests | Per minute per key |
| Auth endpoints (`/auth/login`, `/auth/register`, `/auth/refresh`) | 60 requests | Per minute per IP |

When rate limited, the API returns `429 Too Many Requests` with a
`Retry-After` header.

Rate-limit status is surfaced in every response:
```

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1712700060
```

## Error codes

| Status | Code | Meaning |
|--------|------|---------|
| 401 | `UNAUTHORIZED` | Missing / invalid / revoked credential |
| 403 | `FORBIDDEN` | Valid credential but insufficient role |
| 429 | `RATE_LIMITED` | Too many requests |

## Security best practices

1. **Never commit API keys** to version control.
2. **Use environment variables** or a secrets manager.
3. **Rotate keys** on exposure — revoke and create a new one.
4. **Scope by role** — hand out `msk_u_*` keys to most callers; reserve
   `msk_a_*` / `msk_p_*` for operational tooling.
5. **Separate keys for dev and prod** — easier to revoke blast radius.
6. **Restrict by IP** (admin keys) — pass `allowed_ips` when minting via
   `POST /admin/api-keys` to reject traffic from unexpected sources.

---

# Changelog

URL: https://miosa.ai/docs/changelog
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/changelog
Source: src/routes/docs/changelog/+page.md
Description: What's new in MIOSA — shipped features, SDK updates, and platform improvements.

What's new in MIOSA. Updates ship continuously; this page is a human-readable digest grouped by week.

The MIOSA SDKs will live in dedicated public repos for each language — `Miosa-osa/python-sdk`, `Miosa-osa/typescript-sdk`, etc. Mirrored from the monorepo via a CI subtree-split workflow. Direct installs remain unchanged.

---

## May 12 – 18, 2026

### MCP server for AI coding assistants

A native MCP server ships 22 computer-use tools — screenshot, click, type, scroll, drag, key chords, window management, clipboard, cursor, launch, and more — making any MCP-capable AI coding assistant a first-class driver for MIOSA Computers. See [Desktop Control →](/docs/computers/desktop/)

### Desktop double-click, scroll fix, and faster typing

Fixed a scroll timing regression that caused scroll-up actions to stall. Added double-click as a distinct desktop action. Improved keystroke throughput for `type` commands. The Go SDK now ships a full `Computer` type with all 13 desktop actions.

### Python and TypeScript Sandbox SDKs reach full parity

All Sandbox methods — create, exec, stream, snapshot, file I/O, suspend, resume — are now available in Python (sync + async) and TypeScript. The CLI routes sandbox commands through the native API rather than a secondary proxy. See [Sandbox SDK reference →](/docs/develop/sandboxes/)

### Fixed: SDK import errors and agent exports

Resolved broken module imports introduced during SDK consolidation. `ExecResult` field names are now consistent across Python and TypeScript. Agent stub exports are correctly registered in the package index.

---

## May 5 – 11, 2026

### Sandbox architecture: snapshot restore now live

Sandbox snapshot restore is live at ~166ms p50. The platform captures snapshots automatically on suspend and restores them on resume — no cold boot penalty on warm sandboxes. See [Sandboxes →](/docs/develop/sandboxes/)

### Regions and computer embedding APIs

New `GET /api/v1/regions` endpoint returns the current compute region list with capacity metadata. The embed API now returns a scoped, short-lived token for embedding a computer's desktop into your own UI — no iframe proxy required. See [Embedding →](/docs/computers/embedding/)

### Production deploy pipeline hardened

The sandbox-to-deployment pipeline (source snapshot → builder → release → runtime instance) is fully wired in production. Build logs stream in real time. Static sites land on the edge; dynamic apps boot as runtime instances. See [Deploy overview →](/docs/deploy/overview/)

### Unified SDKs replace standalone sandbox package

The standalone sandbox SDK package is deprecated. All sandbox functionality is available under the unified language SDKs (`miosa` for Python, `@miosa/sdk` for TypeScript, and equivalents in Go, Java, Elixir). Migration is a single import change; the API surface is identical.

### Removed
- The separate sandbox CLI path is removed; all CLI sandbox commands route through the main API.
- Legacy agent endpoints (`/computers/:id/cua/*`, `/computers/:id/agent/*`) now return `410 Gone`. Use desktop primitives directly or the MCP server.

---

## Apr 28 – May 4, 2026

### CLI: public install via Homebrew

The MIOSA CLI is now installable via Homebrew:
```sh
brew install miosa-dev/tap/msk
```

The CLI supports `msk computers`, `msk sandboxes`, `msk deploy`, and `msk auth`. A device-flow OAuth login ties the CLI to your workspace in one browser step. See [CLI reference →](/docs/cli/)

### Account security pages

New security section in account settings: active sessions, passkey management, two-factor setup, and connected OAuth providers. Sessions can be revoked individually.

### Admin: email campaign composer

Platform operators can now compose and send targeted email campaigns to workspace segments directly from the admin console.

### Improved: AI engine token tracking

Token usage from the AI engine is now tracked per-computer and surfaced in the usage API. Metered usage accumulates in real time against the workspace's billing period. See [Usage and Billing →](/docs/platform/usage-and-billing/)

### Improved: frontend workspace tabs and GPU pricing

Workspace settings tabs now persist the active tab across navigation. GPU tier pricing is correctly reflected on the computer create form and the pricing page.

### Improved: admin observability and intelligence gateway

Admin dashboard surfaces per-tenant active computer count, sandbox throughput, and deploy queue depth. The intelligence gateway proxy correctly handles streaming responses under load.

---

## Apr 21 – 27, 2026

### Computer tab scrolling fixed

Long-running computers with many open tabs (terminal, preview, files, etc.) now scroll the tab strip horizontally rather than overflowing off-screen.

### Computer create: services panel

The computer create flow now includes a services panel for attaching data services (Postgres, Redis, object storage) at creation time. Environment variables are injected automatically.

### Environment variable persistence

Environment variables set on a computer or sandbox are persisted across stop/start cycles. Variables set via API are visible in the in-computer terminal immediately.

### Warm pool admin controls

Platform operators can configure warm pool size, pre-warm image targets, and drain schedules from the admin console.

---

## Apr 14 – 20, 2026

### OpenComputers resources across all five SDKs

Hosts, jobs, files, tunnels, and inference cluster resources are now available in all five SDKs (Python, TypeScript, Go, Elixir, Java). Async variants included in Python. See [SDK references →](/docs/sdks/python/)

### SDK surface expansion

Ten new resource namespaces added: Sandboxes, Deployments, Versions, Releases, Runtime Instances, Domains, Data Services (Postgres, Redis, Storage), Network Policy, and Credits. Coverage tables are on each SDK page.

### envd: network tunnels

The in-computer daemon now supports exposing internal services as tunnels — useful for previewing dev servers running inside a computer from outside the VM boundary. See [Previews →](/docs/develop/previews/)

---

## Mar 31 – Apr 13, 2026

### Deployments API

The Deployments API is in production: `POST /api/v1/sandboxes/:id/deploy` publishes a sandbox, `GET /api/v1/deployments` lists deployment history, and `POST /api/v1/deployments/:id/rollback` re-points the active version. All operations are available in the SDK and dashboard. See [Deploy →](/docs/deploy/overview/)

### Sandbox, Deploy, and Intelligence dashboards

The dashboard ships three new top-level sections: Sandboxes (live usage, snapshot list), Deploy (deployment history, build logs, rollback), and Intelligence (AI engine usage, cost trends).

### API drift CI gate

A new CI check compares the server's declared API surface against all five SDK clients on every pull request. Contract mismatches — missing endpoints, changed field names, type drift — fail the build before they reach production.

### Docs site launched

The MIOSA docs site launched with the unified API key format (`msk_*`), Mermaid diagram rendering, six-language SDK tabs, and full-text search.

---

## Mar 2 – 29, 2026

### Compute platform in production

The compute engine and platform API are deployed to production. The provisioning flow is hardened with retry logic, crash guards, and correct error propagation. OAuth state mismatch now redirects to login rather than surfacing a raw error.

### Computer rename complete

"Instance" is renamed to "Computer" across the API, dashboard, SDKs, and documentation. Existing API clients using `/instances/*` continue to work via redirect; new code should use `/computers/*`. See [Computers →](/docs/computers/overview/)

### Computer: `/enter` endpoint

`POST /api/v1/computers/:id/enter` returns a scoped session token for direct desktop access. Used by the embed flow and the CLI `msk computers enter` command.

### 26 app templates with tier system

The computer create flow ships 26 starting templates (landing page, SaaS scaffold, data dashboard, agent workspace, and more) organized by tier: free, pro, and enterprise. The template picker is a split-panel modal with live previews.

### Security hardening

Sixteen security fixes: secret redaction from configure responses, XSS prevention on user-controlled fields, timer leak fixes, provisioning crash guard, and tenant slug collision prevention. Internal auth tokens are no longer included in API responses to unprivileged callers.

### Command Center

The Command Center UI is live — manage AI agent sessions across computers, track cost by session, and view real-time agent status. Backend scheduling and cost accounting routes are wired.

---

## Feb 2 – Mar 1, 2026

### Platform foundation shipped

Stripe billing, audit logging, email notifications, promo codes, and OAuth providers are in production. Redis session persistence ensures computer state survives backend restarts.

### Go backend fully retired

The last Go backend service is archived. The entire stack now runs on Elixir. Dead proxy code and legacy stubs are removed.

### Documentation architecture

Internal technical documentation organized across all five service packages (703 files), covering architecture decisions, API contracts, deployment procedures, and runbooks.

---

## Jan 5 – Feb 1, 2026

### Platform foundation

Auth, billing groundwork, and initial security audit complete. 81 known issues triaged; 27 legacy backend issues closed.

---

# CLI Reference

URL: https://miosa.ai/docs/cli
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cli
Source: src/routes/docs/cli/+page.md
Description: Complete reference for the MIOSA CLI — manage computers, sandboxes, deployments, data services, and AI agents from your terminal.

The `miosa` CLI (`@miosa/cli`) is the command-line entry point for MIOSA. It manages computers, sandboxes, deployments, data services, and AI agents — all from your terminal.

  Commands marked **[planned]** are not yet shipped. All others are live in `@miosa/cli@0.2.0`.

## Install

```bash
npm install -g @miosa/cli
```

```bash
pnpm add -g @miosa/cli
```

```bash
brew install miosa-ai/tap/miosa
```

```bash
curl -fsSL https://install.miosa.ai | sh
```

Installs to `~/.local/bin` (non-root) or `/usr/local/bin` (root). Override with `INSTALL_DIR=/usr/local/bin`.

Verify the install:
```bash
miosa --version
```

## Configuration

Config is stored at `~/.miosa/config.toml`:
```toml
api_url = "https://api.miosa.ai/api/v1"
api_key = "msk_..."
```

**Precedence:** CLI flag `--api-key` → `MIOSA_API_KEY` env var → config file → interactive prompt.

| Environment variable | Description |
|---|---|
| `MIOSA_API_KEY` | API key (overrides config file) |
| `MIOSA_BASE_URL` | Custom API endpoint |
| `MIOSA_DEBUG=1` | Enable verbose debug output |

---

## Command Reference

### Getting Started

#### `miosa login [--api-key key]`

Authenticate with your MIOSA API key. Saves the key to `~/.miosa/config.toml`.

Get an API key from [miosa.ai/settings/api-keys](https://miosa.ai/settings/api-keys).

```bash
miosa login
miosa login --api-key msk_yourkey
echo "msk_yourkey" | miosa login   # CI/non-TTY
```

#### `miosa logout`

Remove the stored API key from `~/.miosa/config.toml`.

#### `miosa whoami`

Print the currently authenticated user, tenant, and plan.

```bash
miosa whoami
```

#### `miosa status`

Show auth state, endpoint, tenant, plan, credit balance, and active resource counts.

```bash
miosa status
```

#### `miosa doctor`

Run environment diagnostics — checks auth, API reachability, CLI version, and shell integration.

```bash
miosa doctor
```

#### `miosa config [get|set|unset] [key] [value]`

Read or write values in `~/.miosa/config.toml`.

```bash
miosa config get api_url
miosa config set api_url https://your-instance.ai/api/v1
miosa config unset api_url
```

#### `miosa up`

Start the local development environment. Equivalent to running `miosa dev` with sensible defaults — watches for changes, forwards tunnels, and tails logs.

```bash
miosa up
miosa up --port 3000
```

---

### Computers

#### `miosa computer create [--image img] [--name name] [--size size]`

Provision a new cloud computer.

```bash
miosa computer create
miosa computer create --name dev-box --image ubuntu-22.04 --size medium
miosa computer create --image debian-12 --size large --json
```

| Flag | Description |
|---|---|
| `--name &lt;name&gt;` | Human-readable name |
| `--image &lt;image&gt;` | OS image slug (default: `ubuntu-22.04`) |
| `--size &lt;size&gt;` | `small`, `medium`, `large` (default: `medium`) |
| `--json` | Output as JSON |

#### `miosa computer list [--json]`

List all computers with their state, image, and last-seen time.

```bash
miosa computer list
miosa computer list --json | jq '.[].name'
```

#### `miosa computer get &lt;name-or-id&gt; [--json]`

Show details for a specific computer including live telemetry.

```bash
miosa computer get dev-box
miosa computer get abc12345 --json
```

#### `miosa computer delete &lt;name-or-id&gt; [-f]`

Delete a computer. Prompts for confirmation unless `-f`.

```bash
miosa computer delete dev-box
miosa computer delete abc12345 -f
```

#### `miosa computer start &lt;name-or-id&gt;`

Start a stopped computer.

```bash
miosa computer start dev-box
```

#### `miosa computer stop &lt;name-or-id&gt;`

Stop a running computer.

```bash
miosa computer stop dev-box
```

#### `miosa computer screenshot &lt;name-or-id&gt; [--out file]`

Capture a screenshot of the computer's desktop and save it locally.

```bash
miosa computer screenshot dev-box
miosa computer screenshot dev-box --out screen.png
```

#### `miosa computer apps &lt;name-or-id&gt;`

List running applications on the computer's desktop.

```bash
miosa computer apps dev-box
```

#### `miosa computer open &lt;name-or-id&gt;`

Open the computer's desktop stream in your browser.

```bash
miosa computer open dev-box
```

#### `miosa computer exec &lt;name-or-id&gt; &lt;cmd&gt; [args...]`

Run a command on the computer non-interactively. Streams stdout/stderr and exits with the remote exit code.

```bash
miosa computer exec dev-box npm test
miosa computer exec dev-box ls -- -la /tmp
miosa computer exec dev-box make build --cwd /project --timeout 10m
miosa computer exec dev-box server.js --env NODE_ENV=production --env PORT=8080
```

| Flag | Description |
|---|---|
| `--cwd &lt;dir&gt;` | Working directory on the computer |
| `--env KEY=VAL` | Environment variable (repeatable) |
| `--timeout &lt;duration&gt;` | e.g. `30s`, `2m`, `1h` (default: `5m`) |

#### `miosa computer files &lt;name-or-id&gt; &lt;path&gt;`

List files at a path on the computer.

```bash
miosa computer files dev-box /home/user
miosa computer files dev-box /tmp -la
```

---

### Interactive

#### `miosa shell &lt;name-or-id&gt; [--cmd "..."]`

Open an interactive PTY terminal on a computer. Exits with the remote shell's exit code.

```bash
miosa shell dev-box
miosa shell dev-box --cmd "htop"
```

#### `miosa watch &lt;name-or-id&gt;`

Stream live telemetry and events from a computer.

```bash
miosa watch dev-box
```

#### `miosa agent start &lt;name-or-id&gt; "&lt;task&gt;"`

Dispatch an AI agent task on a computer. Streams thoughts, tool calls, and results in real time.

```bash
miosa agent start dev-box "run the test suite and fix any failures"
miosa agent start dev-box "update all npm dependencies" --steps 20
miosa agent start dev-box "profile the API and find bottlenecks" --timeout 600000
```

| Flag | Description |
|---|---|
| `--model &lt;model&gt;` | Model override (e.g. `qwen3:32b`) |
| `--steps &lt;n&gt;` | Max agent steps (default: `10`) |
| `--timeout &lt;ms&gt;` | Timeout in milliseconds (default: `300000`) |
| `--tools &lt;list&gt;` | Comma-separated tool list (default: `exec,fs`) |

#### `miosa agent ls &lt;name-or-id&gt;`

List all agent sessions on a computer.

```bash
miosa agent ls dev-box
miosa agent ls dev-box --json
```

#### `miosa agent get &lt;name-or-id&gt; &lt;session-id&gt;`

Show details and current state for an agent session.

```bash
miosa agent get dev-box sess_abc123
```

#### `miosa agent task &lt;name-or-id&gt; &lt;session-id&gt; "&lt;task&gt;"`

Send an additional task to a running agent session.

```bash
miosa agent task dev-box sess_abc123 "also update the README"
```

#### `miosa agent stop &lt;name-or-id&gt; &lt;session-id&gt;`

Stop a running agent session.

```bash
miosa agent stop dev-box sess_abc123
```

#### `miosa agent history &lt;name-or-id&gt; &lt;session-id&gt;`

Print the full message history for an agent session.

```bash
miosa agent history dev-box sess_abc123
miosa agent history dev-box sess_abc123 --json
```

---

### Sandboxes

#### `miosa sandbox create [--image img] [--name name]`

Create a new sandbox.

```bash
miosa sandbox create
miosa sandbox create --name my-sandbox --image debian-12-sandbox-v8
```

| Flag | Description |
|---|---|
| `--name &lt;name&gt;` | Human-readable name |
| `--image &lt;image&gt;` | Sandbox image slug (default: `debian-12-sandbox-v8`) |
| `--json` | Output as JSON |

#### `miosa sandbox list [--json]`

List all sandboxes with their state and image.

```bash
miosa sandbox list
miosa sandbox list --json | jq '.[].id'
```

#### `miosa sandbox exec &lt;id&gt; &lt;cmd&gt; [args...]`

Execute a command inside a sandbox. Streams stdout/stderr and returns the exit code.

```bash
miosa sandbox exec sb_abc123 python main.py
miosa sandbox exec sb_abc123 npm test --timeout 5m
```

#### `miosa sandbox run &lt;id&gt; "&lt;code&gt;"`

Run a code snippet directly inside a sandbox.

```bash
miosa sandbox run sb_abc123 "print('hello')"
miosa sandbox run sb_abc123 "import sys; print(sys.version)"
```

#### `miosa sandbox write-file &lt;id&gt; &lt;remote-path&gt; &lt;local-file&gt;`

Write a local file into the sandbox filesystem.

```bash
miosa sandbox write-file sb_abc123 /app/main.py ./main.py
miosa sandbox write-file sb_abc123 /app/config.json ./config.json
```

#### `miosa sandbox read-file &lt;id&gt; &lt;remote-path&gt;`

Read a file from the sandbox filesystem and print it to stdout.

```bash
miosa sandbox read-file sb_abc123 /app/output.txt
miosa sandbox read-file sb_abc123 /var/log/app.log > local.log
```

#### `miosa sandbox upload &lt;id&gt; &lt;local-path&gt; &lt;remote-path&gt;`

Upload a file or directory to the sandbox.

```bash
miosa sandbox upload sb_abc123 ./dist /app/dist
miosa sandbox upload sb_abc123 ./data.csv /tmp/data.csv
```

#### `miosa sandbox download &lt;id&gt; &lt;remote-path&gt; [local-path]`

Download a file or directory from the sandbox.

```bash
miosa sandbox download sb_abc123 /app/output.json ./output.json
miosa sandbox download sb_abc123 /tmp/results ./results/
```

#### `miosa sandbox logs &lt;id&gt; [--follow]`

Stream logs from a sandbox.

```bash
miosa sandbox logs sb_abc123
miosa sandbox logs sb_abc123 --follow
```

---

### Deploy

#### `miosa deploy [--name name] [--env ENV=VAL]`

Deploy the current directory. Detects the framework automatically.

```bash
miosa deploy
miosa deploy --name my-app
miosa deploy --env NODE_ENV=production --env PORT=8080
miosa deploy --region us-east
```

| Flag | Description |
|---|---|
| `--name &lt;name&gt;` | Deployment name (defaults to directory name) |
| `--env KEY=VAL` | Environment variable (repeatable) |
| `--region &lt;region&gt;` | Target region |
| `--json` | Output as JSON |

#### `miosa deployments list [--json]`

List all deployments.

```bash
miosa deployments list
miosa deployments list --json | jq '.[].name'
```

#### `miosa deployments get &lt;name-or-id&gt;`

Show details for a deployment.

```bash
miosa deployments get my-app
```

#### `miosa deployments logs &lt;name-or-id&gt; [--follow]`

Stream logs for a deployment.

```bash
miosa deployments logs my-app
miosa deployments logs my-app --follow
```

#### `miosa deployments restart &lt;name-or-id&gt;`

Restart a deployment.

```bash
miosa deployments restart my-app
```

#### `miosa services list`

List all services attached to deployments.

```bash
miosa services list
```

#### `miosa domains list`

List all custom domains.

```bash
miosa domains list
```

#### `miosa domains add &lt;deployment&gt; &lt;domain&gt;`

Attach a custom domain to a deployment.

```bash
miosa domains add my-app app.example.com
```

#### `miosa domains remove &lt;deployment&gt; &lt;domain&gt;`

Remove a custom domain.

```bash
miosa domains remove my-app app.example.com
```

---

### Data

#### `miosa databases list`

List all managed databases.

```bash
miosa databases list
miosa databases list --json
```

#### `miosa databases create [--name name] [--engine engine]`

Provision a managed database.

```bash
miosa databases create --name app-db --engine postgres
miosa databases create --name cache --engine redis
```

| Flag | Description |
|---|---|
| `--name &lt;name&gt;` | Database name |
| `--engine &lt;engine&gt;` | `postgres` or `redis` |

#### `miosa databases get &lt;name-or-id&gt;`

Show connection details and status for a database.

```bash
miosa databases get app-db
```

#### `miosa storage list`

List all object storage buckets.

```bash
miosa storage list
```

#### `miosa storage create &lt;name&gt;`

Create a new storage bucket.

```bash
miosa storage create my-bucket
```

#### `miosa volumes list`

List all persistent volumes.

```bash
miosa volumes list
```

#### `miosa volumes create &lt;name&gt; [--size size]`

Create a persistent volume.

```bash
miosa volumes create app-data --size 10gb
```

---

### Platform

#### `miosa functions list`

List all serverless functions.

```bash
miosa functions list
```

#### `miosa functions deploy &lt;path&gt;`

Deploy a function from a local file or directory.

```bash
miosa functions deploy ./functions/handler.ts
```

#### `miosa cron list`

List all scheduled cron jobs.

```bash
miosa cron list
```

#### `miosa cron create "&lt;schedule&gt;" "&lt;cmd&gt;"`

Create a cron job using a standard cron expression.

```bash
miosa cron create "0 * * * *" "miosa sandbox exec sb_abc123 python report.py"
```

#### `miosa webhooks list`

List all registered webhooks.

```bash
miosa webhooks list
```

#### `miosa webhooks create --url &lt;url&gt; --events &lt;events&gt;`

Register a new webhook.

```bash
miosa webhooks create --url https://example.com/hook --events computer.started,computer.stopped
```

#### `miosa checkpoints list &lt;name-or-id&gt;`

List checkpoints (snapshots) for a computer.

```bash
miosa checkpoints list dev-box
```

#### `miosa snapshot &lt;name-or-id&gt; [--name name]`

Create a snapshot of a computer or sandbox.

```bash
miosa snapshot dev-box
miosa snapshot dev-box --name before-upgrade
```

#### `miosa network-policy list`

List network policies.

```bash
miosa network-policy list
```

#### `miosa network-policy create --name &lt;name&gt; --rule &lt;rule&gt;`

Create a network policy rule.

```bash
miosa network-policy create --name allow-http --rule "allow:80,443"
```

#### `miosa api-keys list`

List all API keys for the current tenant.

```bash
miosa api-keys list
miosa api-keys list --json
```

#### `miosa api-keys create [--name name] [--scopes scopes]`

Create a new API key.

```bash
miosa api-keys create --name ci-key --scopes computers:read,sandboxes:write
```

#### `miosa api-keys revoke &lt;id&gt;`

Revoke an API key.

```bash
miosa api-keys revoke key_abc123
```

---

### Workflow

#### `miosa dev [--port n]`

Start a local development session with hot reload, tunnel forwarding, and log tailing.

```bash
miosa dev
miosa dev --port 3000
```

#### `miosa run &lt;script&gt;`

Run a script defined in `miosa.json` or `package.json`.

```bash
miosa run build
miosa run test
```

#### `miosa link [name-or-id]`

Link the current directory to a MIOSA computer or deployment. Writes a `.miosa` config file.

```bash
miosa link
miosa link dev-box
```

#### `miosa pull &lt;name-or-id&gt; [path]`

Pull files from a computer or deployment into the current directory.

```bash
miosa pull dev-box /app/dist
miosa pull my-deploy .
```

#### `miosa tunnel open &lt;name-or-id&gt; --port &lt;n&gt;`

Expose a computer port publicly via a MIOSA tunnel.

```bash
miosa tunnel open dev-box --port 3000
miosa tunnel open dev-box --port 8080 --name my-app --watch
```

| Flag | Description |
|---|---|
| `--port &lt;n&gt;` | Port to expose (required) |
| `--name &lt;slug&gt;` | Optional tunnel name |
| `--watch` | Stay open and stream live events |

#### `miosa tunnel list &lt;name-or-id&gt;`

List active tunnels on a computer.

#### `miosa tunnel close &lt;name-or-id&gt; &lt;slug&gt;`

Revoke a tunnel.

#### `miosa mcp serve [--port n]`

Start a local MCP (Model Context Protocol) server that exposes MIOSA resources to AI tools.

```bash
miosa mcp serve
miosa mcp serve --port 8765
```

#### `miosa cp &lt;src&gt; &lt;dst&gt;`

Copy files between local and remote. Use `host:/path` notation for remote paths.

```bash
# Upload
miosa cp ./app.tar.gz dev-box:/tmp/
miosa cp -r ./dist dev-box:/var/www/html/

# Download
miosa cp dev-box:/var/log/app.log ./
miosa cp dev-box:/home/user/report.pdf ~/Downloads/
```

**Flags:** `-r` / `--recursive` for directories.

---

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | User error (bad arguments, resource not found, etc.) |
| `2` | Network error |
| `3` | Authentication / authorization error |
| `4` | Server error |

---

## Troubleshooting

**"No API key configured"** — Run `miosa login`.

**"Computer not found"** — Check `miosa computer list` for the correct name or ID.

**"Insufficient credits"** — Top up at [miosa.ai/billing](https://miosa.ai/billing).

**Network errors** — Check your connection. Enable debug output:
```bash
MIOSA_DEBUG=1 miosa computer list
```

**Custom endpoint (self-hosted)**:
```bash
MIOSA_BASE_URL=https://your-instance.ai miosa computer list
```

---

# BYOC / OpenComputers

URL: https://miosa.ai/docs/computers/byoc
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/computers/byoc
Source: src/routes/docs/computers/byoc/+page.md
Description: Register your own hardware (Mac, Linux, Windows). One command, your machine becomes a MIOSA computer. Apache 2.0.

**OpenComputers** is MIOSA's bring-your-own-compute path. Install the agent on your own hardware — laptops, desktops, mini-PCs, even Raspberry Pi for light workloads — and it registers with MIOSA over an outbound WebSocket. Your machine becomes a MIOSA computer that you (or your AI agents) can drive through the same API as cloud computers.

Apache 2.0. Local-first scheduling — work runs on your hardware when there's capacity; cloud overflow when there isn't.

## Why BYOC

- **Already own the hardware.** No reason to pay for cloud capacity for workloads you have machines for.
- **Local LLMs, local models.** GPU on your machine, MIOSA orchestrates the work.
- **Data residency.** Work runs on your hardware, not in our datacenter.
- **Cloud overflow.** Scale beyond your local fleet when needed; MIOSA places overflow on its cloud.
- **Same API.** Your agent code doesn't care if a job runs on `miosa-host-01` (cloud) or `dad-mac-mini` (your home network).

## Install the agent (one command)
```bash
# On the host machine
curl -fsSL https://miosa.ai/install | sh
```

The installer:
1. Detects your OS (macOS / Linux / Windows; WSL2 supported).
2. Downloads the OSA agent binary.
3. Prompts for a registration token (from your MIOSA dashboard).
4. Starts the agent as a system service (`launchd` / `systemd` / `Windows Service`).

The agent maintains an outbound WebSocket to MIOSA — no inbound ports, no public IP. NAT-friendly.

## Three modes

| Mode | What's exposed | Use case |
|---|---|---|
| **Direct** | The host machine itself is one Computer | Use your laptop as a computer for a single agent |
| **VM dispatch** | The agent creates Firecracker microVMs on the host; each is a Computer | Run multiple parallel agents on one beefy machine |
| **Slicing** | One physical machine partitioned into N independent desktop sessions | Multi-tenant workstation; pre-K12 / kiosk fleet |

Most setups use VM dispatch — gives you process isolation, snapshots, and lifecycle the same way cloud computers work.

## Use a BYOC computer
```typescript
// List your hosts
const hosts = await miosa.openComputers.hosts.list()

// Create a computer on a specific host
const computer = await miosa.computers.create({
  name: "local-agent",
  templateType: "miosa-desktop",
  hostId: hosts[0].id,  // optional; scheduler picks if omitted
})

// From here, identical API as a cloud computer
await computer.desktop.screenshot()
```

The scheduler honors local-first placement by default — if you have available capacity on a BYOC host, jobs land there. Override via explicit `hostId` or set scheduling preferences per workspace.

## Tunnels

When you need direct browser access to a port running inside the host machine (a local dev server, a vendor admin UI, your home Home Assistant), open a MIOSA tunnel:
```typescript
const tunnel = await miosa.openComputers.tunnels.create(hostId, {
  port: 8123,
  name: "home-assistant",
})

console.log(tunnel.public_url)
// → https://home-assistant.your-workspace.tunnels.miosa.app
```

The tunnel is authenticated server-side (MIOSA workspace), proxied through MIOSA's edge, and emerges on your host via the outbound WebSocket. Same security properties as Preview — short-lived tokens for browser-facing access, no public IP needed on your host.

## Resource control

You control what your host shares with MIOSA:
```yaml
# ~/.miosa/agent.yaml
resources:
  max_cpu_percent: 50      # cap MIOSA workloads at 50% of CPU
  max_ram_mb: 8192         # 8 GB ceiling
  max_disk_gb: 100
  schedule:
    - {days: [Mon-Fri], hours: "09:00-17:00", paused: true}  # don't share during work hours
```

The agent reports available capacity to the scheduler in real time. Workloads are gracefully drained off when you go below limits.

## Health and reliability

Hosts emit heartbeats every 30s. After ~2 minutes of missed heartbeats, the scheduler marks the host offline and stops placing new work on it. In-flight work either completes (if the host comes back) or is rescheduled to other hosts.

For production-critical workloads, run multiple BYOC hosts and let MIOSA spread work across them.

## Security

- The agent runs as a regular user (recommended), not root. Computers are Firecracker microVMs the agent spawns; they cannot escape to the host machine.
- The outbound WebSocket is authenticated by a host-specific key tied to your tenant. Compromising one host doesn't expose other hosts in your fleet.
- The agent is open source (Apache 2.0) — auditable.

## Pricing

- **OpenComputers agent: free.** Apache 2.0, run as many hosts as you want.
- **MIOSA scheduling / control plane: per-host fee.** Plans range from free (a few personal hosts) to enterprise (hundreds of hosts, fleet management UI).

See [Pricing](https://miosa.ai/pricing) for details.

## See also

- [Computers / Overview](/docs/computers/overview/) — once registered, BYOC hosts run computers like cloud hosts
- [Desktop Control](/docs/computers/desktop/) — drive any computer, BYOC or cloud
- [API Reference: OpenComputers](/docs/api-reference/open-computers/) — register / list / manage hosts
- [GitHub](https://github.com/Miosa-osa/miosa) — agent source

---

# Desktop Control

URL: https://miosa.ai/docs/computers/desktop
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/computers/desktop
Source: src/routes/docs/computers/desktop/+page.md
Description: 28 methods for driving a Computer's desktop — screenshot, click, type, scroll, drag, keyboard, clipboard, windows, shell, and more.

Once you have a [Computer](/docs/computers/overview/), drive its desktop with these methods. Suitable for AI agents (computer-use models, custom RPA loops) and for direct programmatic control.

## All 28 methods

| Group | Method | Purpose |
|---|---|---|
| **Screen** | `screenshot()` | Capture full desktop as PNG bytes |
| | `screenshot_base64()` | Same, base64-encoded — ready to pass to an LLM vision API |
| **Click** | `click(x, y)` | Generic click — defaults to left button |
| | `left_click(x, y)` | Left-button click at coordinates |
| | `right_click(x, y)` | Right-button click (context menu) |
| | `double_click(x, y)` | Double-click at coordinates |
| **Mouse** | `move_cursor(x, y)` | Move cursor without clicking |
| | `mouse_down(x, y)` | Press and hold the mouse button |
| | `mouse_up(x, y)` | Release a held mouse button |
| | `drag(from_x, from_y, to_x, to_y)` | Click-drag between two coordinates |
| **Keyboard** | `type(text)` | Type a string at the current focus |
| | `key(key)` | Press a single key (e.g. `"Return"`, `"Escape"`) |
| | `hotkey(*keys)` | Simultaneous key combo (e.g. `"ctrl", "c"`) |
| | `key_down(key)` | Press and hold a key |
| | `key_up(key)` | Release a held key |
| **Scroll** | `scroll(direction, clicks)` | Scroll `up`/`down`/`left`/`right` by N notches |
| | `scroll_up(clicks)` | Convenience — scroll up |
| | `scroll_down(clicks)` | Convenience — scroll down |
| | `scroll_left(clicks)` | Convenience — scroll left |
| | `scroll_right(clicks)` | Convenience — scroll right |
| **Clipboard** | `get_clipboard()` | Read the current clipboard text |
| | `set_clipboard(text)` | Write text to the clipboard |
| **Screen info** | `get_screen_size()` | Desktop resolution `{width, height}` |
| | `get_cursor_position()` | Current cursor `{x, y}` in normalized coords |
| **Windows** | `windows()` | List open windows with IDs, titles, positions |
| | `launch(app)` | Open an installed application by name |
| | `focus_window(id)` | Bring a window to the foreground |
| | `get_window_size(id)` | Read a window's `{width, height}` |
| | `set_window_size(id, w, h)` | Resize a window |
| | `get_window_position(id)` | Read a window's `{x, y}` |
| | `set_window_position(id, x, y)` | Move a window |
| | `maximize_window(id)` | Maximize a window |
| | `minimize_window(id)` | Minimize a window to the taskbar |
| | `close_window(id)` | Close a window |
| **Environment** | `get_desktop_environment()` | Detect DE name and version (e.g. `xfce4`) |
| | `set_wallpaper(path)` | Set the desktop background from a file path |
| | `get_accessibility_tree()` | AT-SPI element tree for structured agent perception |
| **Shell** | `bash(cmd)` | Execute a shell command inside the VM |
| | `python(code)` | Execute a Python snippet inside the VM |
| | `write_file(path, content)` | Write content to a file path inside the VM |
| | `read_file(path)` | Read a file path inside the VM |

## Coordinate system

Computers accept and report coordinates in **normalized 0-1000 space**. (0, 0) is top-left, (1000, 1000) is bottom-right, regardless of the actual display resolution.

```python
# Click the visual center of the screen on any display size
computer.left_click(500, 500)
```

When you capture a screenshot, MIOSA scales it to a fixed 1024-wide thumbnail by default (`smartResize`). Your agent reasons about coordinates in that normalized space; MIOSA translates to actual display pixels before sending the event to the VM.

## The control loop
Diagram:
sequenceDiagram
    participant A as Agent / SDK
    participant API as Computer API
    participant envd as envd (port 49983)
    participant X as X11 desktop

    A->>API: computer.screenshot()
    API->>envd: capture frame
    envd->>X: XGetImage
    X-->>envd: pixel data
    envd-->>API: PNG bytes
    API-->>A: bytes

    A->>API: computer.left_click(500, 300)
    API->>envd: inject click event
    envd->>X: XSendEvent (ButtonPress)
    X-->>envd: ack
    envd-->>API: ok
    API-->>A: None

---

## Screen

### `screenshot()`

Capture the full desktop as PNG bytes.

```python
png_bytes = computer.screenshot()
# Write to disk
with open("screen.png", "wb") as f:
    f.write(png_bytes)
```

Screenshots are PNG. Average 150–300 KB for a 1024-wide thumbnail.

### `screenshot_base64()`

Same as `screenshot()`, but returns a base64-encoded string. Use this when feeding the image directly to an LLM vision API.

```python
b64 = computer.screenshot_base64()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {"type": "base64", "media_type": "image/png", "data": b64},
            },
            {"type": "text", "text": "What is on screen? Where should I click to open the browser?"},
        ],
    }],
)
```

---

## Click

### `click(x, y)`

Generic click at coordinates. Defaults to left button.

```python
computer.click(640, 480)
```

### `left_click(x, y)`

Explicit left-button click.

```python
computer.left_click(640, 480)
```

### `right_click(x, y)`

Right-button click — opens context menus.

```python
computer.right_click(640, 480)
```

### `double_click(x, y)`

Double-click — opens files, selects words.

```python
computer.double_click(100, 200)
```

---

## Mouse

### `move_cursor(x, y)`

Reposition the cursor without triggering a click. Useful before `mouse_down` / `mouse_up` sequences or for hover interactions.

```python
computer.move_cursor(500, 400)
```

### `mouse_down(x, y)` / `mouse_up(x, y)`

Low-level press and release. Use these when `drag` is not granular enough — for example, to hover mid-drag or to implement a long-press interaction.

```python
computer.mouse_down(200, 200)
computer.move_cursor(400, 400)   # move while held
computer.mouse_up(400, 400)
```

### `drag(from_x, from_y, to_x, to_y)`

Click-drag between two points with smooth interpolation. Use for sliders, drag-to-select, re-ordering list items.

```python
computer.drag(200, 200, 600, 400)
```

---

## Keyboard

### `type(text)`

Type a string as if at a keyboard. Does NOT interpret special key names — use `key()` for those.

```python
computer.type("hello, world")
```

### `key(key)`

Press a single key or chord.

```python
computer.key("Return")
computer.key("Escape")
computer.key("ctrl+a")    # select all
computer.key("alt+F4")    # close window
```

Chords use `+` as the separator. Key names follow the X11 keysym convention: `Return`, `Tab`, `BackSpace`, `Delete`, `Home`, `End`, `Page_Up`, `Page_Down`, `Up`, `Down`, `Left`, `Right`, `F1`–`F12`, `super`, `ctrl`, `alt`, `shift`.

### `hotkey(*keys)`

Send multiple keys simultaneously — pass each key as a separate argument.

```python
computer.hotkey("ctrl", "c")    # copy
computer.hotkey("ctrl", "v")    # paste
computer.hotkey("ctrl", "z")    # undo
computer.hotkey("ctrl", "shift", "t")  # reopen tab
```

### `key_down(key)` / `key_up(key)`

Low-level key press and release. Use when you need to hold a modifier while performing other actions.

```python
computer.key_down("shift")
computer.left_click(800, 200)   # shift-click to extend selection
computer.key_up("shift")
```

---

## Scroll

### `scroll(direction, clicks)`

Scroll the mouse wheel. `direction` is one of `"up"`, `"down"`, `"left"`, `"right"`. `clicks` is the number of notches.

```python
computer.scroll("down", clicks=3)
computer.scroll("up", clicks=5)
computer.scroll("right", clicks=2)
```

### Convenience scrolls

```python
computer.scroll_up(clicks=3)
computer.scroll_down(clicks=3)
computer.scroll_left(clicks=2)
computer.scroll_right(clicks=2)
```

`clicks` defaults to `1` for all convenience methods.

---

## Clipboard

### `get_clipboard()`

Read the current clipboard text content.

```python
text = computer.get_clipboard()
print(text)
```

### `set_clipboard(text)`

Write text to the clipboard. After this call, `Ctrl+V` inside the VM will paste the text.

```python
computer.set_clipboard("some text to paste")
computer.hotkey("ctrl", "v")
```

---

## Screen info

### `get_screen_size()`

Returns the desktop resolution as a dict.

```python
size = computer.get_screen_size()
print(size)   # {"width": 1920, "height": 1080}
```

### `get_cursor_position()`

Returns the current cursor position in normalized 0-1000 coordinates.

```python
pos = computer.get_cursor_position()
print(pos)    # {"x": 512, "y": 300}
```

---

## Windows

### `windows()`

List all open windows. Returns a list of dicts with `id`, `title`, `x`, `y`, `width`, `height`, and `focused`.

```python
wins = computer.windows()
for w in wins:
    print(w["id"], w["title"], w["focused"])
```

### `launch(app)`

Open an installed application by name. Available apps depend on the template; `miosa-desktop` ships with Firefox, xterm, Thunar (file manager), and Mousepad (text editor).

```python
computer.launch("firefox")
computer.launch("xterm")
computer.launch("thunar")   # file manager
```

### `focus_window(id)` / `get/set_window_size(id, ...)` / `get/set_window_position(id, ...)` / `maximize_window(id)` / `minimize_window(id)` / `close_window(id)`

Full window management via window ID returned by `windows()`.

```python
wins = computer.windows()
w = wins[0]

# Bring to foreground
computer.focus_window(w["id"])

# Read geometry
size = computer.get_window_size(w["id"])
pos  = computer.get_window_position(w["id"])

# Set geometry
computer.set_window_size(w["id"], 1280, 800)
computer.set_window_position(w["id"], 100, 50)

# State changes
computer.maximize_window(w["id"])
computer.minimize_window(w["id"])
computer.close_window(w["id"])
```

---

## Environment

### `get_desktop_environment()`

Returns the active desktop environment name and version.

```python
de = computer.get_desktop_environment()
print(de)   # {"name": "xfce4", "version": "4.18"}
```

### `set_wallpaper(path)`

Set the desktop background image from a path inside the VM. Combine with `write_file` to push a custom image first.

```python
# Push wallpaper then apply it
computer.write_file("/tmp/bg.png", open("bg.png", "rb").read())
computer.set_wallpaper("/tmp/bg.png")
```

Use `set_wallpaper` together with `write_file` to apply per-tenant branding automatically after computer creation. The wallpaper is stored in the VM's filesystem and persists across stop/start cycles.

### `get_accessibility_tree()`

Returns the AT-SPI accessibility tree as a structured dict. Use this for agent perception when coordinates alone are insufficient — for example, to extract button labels, form field names, or reading order without OCR.

```python
tree = computer.get_accessibility_tree()
# tree is a nested dict of accessible elements
# {"role": "frame", "name": "Firefox", "children": [...]}
```

---

## Shell

These methods execute code inside the VM directly — no GUI interaction required.

### `bash(cmd)`

Execute a shell command. Returns stdout as a string.

```python
output = computer.bash("ls /home/user/Desktop")
print(output)

# Install a package
computer.bash("sudo apt-get install -y curl")

# Launch Firefox in background (so the call returns immediately)
computer.bash("firefox &")
```

### `python(code)`

Execute a Python snippet inside the VM. Returns stdout.

```python
result = computer.python("print(1 + 1)")
print(result)   # "2"

# Multi-line
code = """

data = {"status": "ok"}
print(json.dumps(data))
"""
output = computer.python(code)
```

### `write_file(path, content)`

Write a file into the VM's filesystem. `content` can be a string or bytes.

```python
computer.write_file("/home/user/script.py", "print('hello')")
computer.bash("python3 /home/user/script.py")
```

### `read_file(path)`

Read a file from the VM's filesystem. Returns the content as a string.

```python
content = computer.read_file("/home/user/.bashrc")
print(content)
```

---

## Agent reasoning loop

At the application level, an agent drives the computer through a perception-action cycle:

Diagram:
sequenceDiagram
    participant AG as Agent
    participant CM as Computer

    AG->>CM: screenshot_base64()
    CM-->>AG: PNG (base64)
    AG->>AG: reason — what to do next?
    AG->>CM: left_click(x, y)
    CM-->>AG: ok
    AG->>CM: type(text)
    CM-->>AG: ok
    AG->>CM: screenshot_base64()
    CM-->>AG: PNG (base64)
    AG->>AG: task complete?

## Full agent loop example

```python

from miosa import Miosa

miosa_client  = Miosa(api_key=os.environ["MIOSA_API_KEY"])
claude_client = anthropic.Anthropic()

computer = miosa_client.computers.create(
    name="browser-agent",
    template="miosa-desktop",
    size="small",
)
computer.start()

# Open the browser
computer.launch("firefox")

# Agent loop
for _ in range(10):
    b64 = computer.screenshot_base64()

    response = claude_client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": b64}},
                {"type": "text", "text": "Navigate to miosa.ai and take a screenshot of the homepage."},
            ],
        }],
    )

    # Parse action from response and dispatch
    text = response.content[0].text
    if "left_click" in text:
        # extract x, y from model output and act
        computer.left_click(500, 500)
    elif "type" in text:
        computer.type("https://miosa.ai\n")

computer.stop()
```

---

## Latency reference

Desktop methods run synchronously over authenticated HTTP RPC. Typical round-trip from MIOSA edge:

| Method type | Typical latency |
|---|---|
| Click, key, scroll, type | 30–80 ms |
| Screenshot | 100–300 ms (compression-bound) |
| Window list | 50–100 ms |
| `bash()` / `python()` | 50 ms + command execution time |

For high-frequency agent loops, prefer `bash()` for multi-step operations over many individual GUI calls.

---

## Authentication

All desktop methods require the same workspace API key as every other MIOSA resource. Call them server-side. For browser-side direct control (computer-use models running in the browser), mint a scoped token — see [Browser Tokens](/docs/platform/browser-tokens/).

---

## See also


    Pick a template, size, and workspace. Create and start a computer.
    [Open →](/docs/computers/overview/)


    Show the live desktop in a browser iframe using short-lived stream tokens.
    [Open →](/docs/computers/embedding/)


    Wire format for all 28 methods — request/response shapes, error codes, rate limits.
    [Open →](/docs/api-reference/desktop/)

---

# Embedding & Streaming

URL: https://miosa.ai/docs/computers/embedding
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/computers/embedding
Source: src/routes/docs/computers/embedding/+page.md
Description: Embed a live Computer desktop in your own UI via KasmVNC. Pixel streaming, input forwarding.

To show a live desktop session in your end-user's browser — for "watch the AI work" UI, manual takeover, or kiosk-style apps — embed MIOSA's KasmVNC stream.

## The flow
```

1. Your backend asks MIOSA for a terminal ticket for a running computer
2. MIOSA returns a short-lived signed URL pointing at the stream gateway
3. Your frontend renders an iframe with that URL
4. The user sees the live desktop; keyboard/mouse input is forwarded into the VM
```

## Mint a ticket

```typescript
const ticket = await computer.terminalTicket()
console.log(ticket.url)        // signed stream URL
console.log(ticket.expires_at) // ISO timestamp
```

```bash
curl -X POST https://api.miosa.ai/api/v1/computers/$CID/terminal-ticket \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Response:
```json
{
  "token": "miosa_term_...",
  "url": "https://stream.miosa.app/computer/cmp_xxx?ticket=miosa_term_...",
  "expires_at": "2026-05-14T19:30:00Z"
}
```

`url` is what you embed. `token` is also returned in case you need to construct your own URL (custom stream proxy, etc.).

## Embed

```jsx
<iframe
  src={streamUrl}
  sandbox="allow-same-origin allow-scripts allow-forms"
  className="w-full h-[600px] border-0 rounded-lg"
  allow="clipboard-read; clipboard-write"
/>
```

```html
<iframe
  src="https://stream.miosa.app/computer/cmp_xxx?ticket=miosa_term_..."
  sandbox="allow-same-origin allow-scripts allow-forms"
  style="width:100%; height:600px; border:0;"
  allow="clipboard-read; clipboard-write">
</iframe>
```

KasmVNC handles pixel streaming + input forwarding inside the iframe. The user clicks / types in the iframe and those events go to the desktop.

## What's streamed

- **Pixels** — encoded video; KasmVNC defaults to a lossy codec tuned for desktop content.
- **Cursor position** — overlay rendered client-side.
- **Audio** — optional, off by default. Pass `?audio=1` if your app needs it.
- **Clipboard** — bidirectional, gated by the iframe's `allow="clipboard-read; clipboard-write"`.

## Read-only mode

For "user watches the agent" UI where the end-user shouldn't interact with the desktop:
```typescript
const ticket = await computer.terminalTicket({ readOnly: true })
```

Input events from the iframe are dropped at the stream gateway. Useful for compliance-sensitive flows where only the AI agent should touch the screen.

## Bandwidth

Default codec / bitrate is tuned for typical desktop content (~500 Kbps - 2 Mbps). For high-motion content (video playback inside the VM), the codec adapts but expect higher bitrate. The stream gateway is geo-routed to the user's nearest region for lower latency.

## Lifetime

Tickets are short-lived (default 1 hour, max 24 hours; configurable per plan). When a ticket expires the stream disconnects; your frontend should watch `expires_at` and re-mint before that.

Multiple tickets per computer are fine. Multiple browsers can watch the same desktop simultaneously — they all see the same pixels.

## Custom domains / branded streaming

White-label customers can configure `stream.&lt;your-domain&gt;` to front MIOSA's stream gateway, so end users see your brand in the iframe URL. Same DNS / TLS flow as [Deployment Domains](/docs/deploy/domains/), different target. Contact support to set up.

## CSP

The stream gateway emits `Content-Security-Policy` allowing the stream to be embedded from approved origins:

- Default: `*.miosa.app`, `*.miosa.ai`, `localhost:4000`.
- For white-label: add your platform origin via tenant config.

If your iframe doesn't render, check the parent page's CSP isn't blocking the iframe and that the stream gateway CSP includes your origin.

## Audit

Each ticket issuance emits an audit event with:

- The computer ID
- The token prefix
- Issuing API key
- External attribution

If a ticket is leaked, you can revoke all outstanding tickets for a computer:
```http
DELETE /api/v1/computers/$CID/terminal-tickets
```

## See also

- [Overview](/docs/computers/overview/) — what you're embedding
- [Desktop Control](/docs/computers/desktop/) — programmatic control of the same desktop
- [Browser Tokens](/docs/platform/browser-tokens/) — analogous pattern for sandbox previews

---

# Computers (Desktop)

URL: https://miosa.ai/docs/computers/overview
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/computers/overview
Source: src/routes/docs/computers/overview/+page.md
Description: Full Linux desktops in the cloud — Xfce, Firefox, terminal — controlled via 28 Python SDK methods including screenshot, click, type, scroll, clipboard, windows, shell, and more.

A **Computer** is a Firecracker microVM running a full Linux desktop (Xfce). Use it when you need a real GUI environment: browser automation, computer-use AI agents, RPA, or screenshot-driven testing.

For code execution, dev servers, and most AI agent build loops, [Sandboxes](/docs/develop/sandboxes/) are cheaper and faster. Choose based on whether your workload needs a rendered desktop.

## When to use Computer vs Sandbox

| Use case | Pick |
|---|---|
| Run untrusted code, dev server, `npm install` | **Sandbox** |
| Computer-use agent, GUI automation | **Computer** |
| Browser automation that needs a real rendered DOM | **Computer** |
| AI-agent build loop (code-gen, hot reload, preview) | **Sandbox** |
| Screenshot-based UI testing | **Computer** |
| Headless Playwright / Selenium | **Sandbox** (cheaper) |
| Controlling desktop apps (Figma, Slack, etc.) | **Computer** |

## What is in the box

- **Xfce desktop** with Firefox and common Linux apps pre-installed.
- **Terminal** — `bash`, `python`, standard CLI toolchain.
- **Persistent storage** — files survive stop/start cycles via snapshot restore.
- **VNC + WebSocket streaming** — embed the desktop live in a browser via MIOSA's pixel-stream protocol.
- **OSA agent** — pre-installed, disabled by default. Activate it for autonomous in-VM AI task execution.

## Quick example

```python

client = miosa.Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Create and start a desktop computer
computer = client.computers.create(name="agent-1", template="miosa-desktop", size="small")
computer.start()

# Capture the screen, interact with it
png_bytes = computer.screenshot()
computer.left_click(640, 480)
computer.double_click(100, 200)
computer.type("hello world")
computer.key("Return")
computer.scroll("down", clicks=3)
computer.hotkey("ctrl", "c")
computer.bash("firefox &")
```

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

// Create and start a desktop computer
const computer = await miosa.computers.create({
  name: "agent-1",
  templateType: "miosa-desktop",
  size: "small",
})
await computer.start()

// Capture the screen, interact with it
const png = await computer.screenshot()
await computer.leftClick(640, 480)
await computer.doubleClick(100, 200)
await computer.type("hello world")
await computer.key("Return")
await computer.scroll({ direction: "down", clicks: 3 })
await computer.hotkey("ctrl", "c")
await computer.bash("firefox &")
```

## Desktop action reference

All 28 methods available on a running computer:

| Group | Method | Description |
|---|---|---|
| **Screen** | `screenshot()` | Capture full desktop as PNG bytes |
| | `screenshot_base64()` | Same, base64-encoded — ready for LLM vision APIs |
| **Click** | `click(x, y)` | Generic click (defaults to left button) |
| | `left_click(x, y)` | Left-button click |
| | `right_click(x, y)` | Right-button click (context menu) |
| | `double_click(x, y)` | Double-click |
| **Mouse** | `move_cursor(x, y)` | Move cursor without clicking |
| | `mouse_down(x, y)` | Press and hold the mouse button |
| | `mouse_up(x, y)` | Release a held mouse button |
| | `drag(from_x, from_y, to_x, to_y)` | Click-drag between two coordinates |
| **Keyboard** | `type(text)` | Type a string at the current focus |
| | `key(key)` | Send a single key (e.g. `"Return"`, `"ctrl+a"`) |
| | `hotkey(*keys)` | Simultaneous key combo (e.g. `"ctrl", "c"`) |
| | `key_down(key)` | Press and hold a key |
| | `key_up(key)` | Release a held key |
| **Scroll** | `scroll(direction, clicks)` | Scroll `up`/`down`/`left`/`right` |
| | `scroll_up/down/left/right(clicks)` | Convenience scroll methods |
| **Clipboard** | `get_clipboard()` | Read clipboard text |
| | `set_clipboard(text)` | Write text to clipboard |
| **Screen info** | `get_screen_size()` | Desktop resolution `{width, height}` |
| | `get_cursor_position()` | Current cursor `{x, y}` in normalized coords |
| **Windows** | `windows()` | List open windows with IDs, titles, positions |
| | `launch(app)` | Open an installed app by name |
| | `focus_window(id)` | Bring a window to the foreground |
| | `get/set_window_size(id, ...)` | Read or set window dimensions |
| | `get/set_window_position(id, ...)` | Read or set window position |
| | `maximize/minimize/close_window(id)` | Change window state |
| **Environment** | `get_desktop_environment()` | DE name and version (e.g. `xfce4`) |
| | `set_wallpaper(path)` | Set desktop background from a VM file path |
| | `get_accessibility_tree()` | AT-SPI element tree for structured agent perception |
| **Shell** | `bash(cmd)` | Execute a shell command inside the VM |
| | `python(code)` | Execute a Python snippet inside the VM |
| | `write_file(path, content)` | Write a file into the VM's filesystem |
| | `read_file(path)` | Read a file from the VM's filesystem |

See [Desktop Control](/docs/computers/desktop/) for full examples, parameter details, and coordinate system documentation.

## Workspace-scoped creation

Computers can be created inside a named workspace so that resources are isolated and billed separately. Pass `external_workspace_id` to attribute the computer to a tenant in your platform.

```python

client = miosa.Miosa(api_key=os.environ["MIOSA_API_KEY"])

computer = client.computers.create(
    name="agent-1",
    template="miosa-desktop",
    size="small",
    external_workspace_id="acme-corp",      # your tenant identifier
    metadata={"agent_run": "run-2026-05-17"},
)
computer.start()
```

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

const computer = await miosa.computers.create({
  name: "agent-1",
  templateType: "miosa-desktop",
  size: "small",
  externalWorkspaceId: "acme-corp",
  metadata: { agentRun: "run-2026-05-17" },
})
await computer.start()
```

`external_workspace_id` is a free-form string you control — use your own tenant/org identifier. Usage is tracked per workspace in the billing dashboard so you can attribute compute costs to individual customers.

## White-label desktops

Computers support per-tenant desktop branding. After starting a computer, push a wallpaper and apply it with two SDK calls. The wallpaper persists across stop/start cycles because it is stored in the VM's snapshotted filesystem.

```python

client   = miosa.Miosa(api_key=os.environ["MIOSA_API_KEY"])
computer = client.computers.create(
    name="acme-agent",
    template="miosa-desktop",
    size="small",
    external_workspace_id="acme-corp",
)
computer.start()

# Push the tenant wallpaper from your server's filesystem
computer.write_file("/tmp/acme-wallpaper.png", open("assets/acme-bg.png", "rb").read())
computer.set_wallpaper("/tmp/acme-wallpaper.png")

# Optionally verify the DE
de = computer.get_desktop_environment()
print(de)   # {"name": "xfce4", "version": "4.18"}
```

```typescript

const miosa    = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })
const computer = await miosa.computers.create({
  name: "acme-agent",
  templateType: "miosa-desktop",
  size: "small",
  externalWorkspaceId: "acme-corp",
})
await computer.start()

// Push and apply the tenant wallpaper
const bg = fs.readFileSync("assets/acme-bg.png")
await computer.writeFile("/tmp/acme-wallpaper.png", bg)
await computer.setWallpaper("/tmp/acme-wallpaper.png")
```

For production deployments, bake the wallpaper directly into a custom template snapshot so every new computer boots with the correct branding — no post-boot setup required. See the Templates documentation for details.

## How it fits together
Diagram:
graph LR
    SDK["Python / TypeScript SDK"] -->|REST| API["MIOSA API"]
    API --> VM["Firecracker VM\n(Xfce desktop)"]
    VM --> envd["envd agent\n(port 49983)"]
    envd -->|X11 input| Desktop["Desktop session"]
    envd -->|PNG frame| Stream["Pixel stream"]
    Stream -->|WebSocket| Browser["Browser iframe"]

Your code talks to the MIOSA API. MIOSA routes actions to `envd` running inside the VM. `envd` drives the X11 session and returns screenshots or action confirmations. For embedded views, MIOSA streams the desktop over WebSocket to a browser iframe.

## Embed the desktop in a browser

Mint a stream token from your backend, then pass the URL to a browser iframe:

```python
token = computer.stream_token()
# token["url"] → short-lived WebSocket stream URL
# Pass this URL to your frontend; do not embed your API key.
```

```typescript
const token = await computer.streamToken()
// token.url → short-lived WebSocket stream URL
// <iframe src={token.url} sandbox="allow-same-origin allow-scripts" />
```

See [Embedding & Streaming](/docs/computers/embedding/) for the full pattern including authentication, iframe policy, and expiry handling.

## Lifecycle
```

create → provisioning → running ⇆ stopped → deleted
```

| State | Description |
|---|---|
| `provisioning` | Firecracker is booting the rootfs |
| `running` | Desktop is up, accepting API actions |
| `stopped` | Snapshotted; file state preserved; restartable |
| `deleted` | Permanent — not reversible |

Stopping a computer pauses billing (or charges at the stopped rate, depending on your plan). Restarting resumes from the snapshot.

## Sizing

| Size | vCPU | RAM | Disk | Typical use |
|---|---|---|---|---|
| `small` | 2 | 4 GB | 20 GB | Single agent, basic browsing |
| `medium` | 4 | 8 GB | 50 GB | Heavier desktop apps, faster page loads |
| `large` | 8 | 16 GB | 100 GB | Multi-app, large-context AI workloads |

GPU support for accelerated desktop and GPU-aware in-VM agents is plan-dependent.

Computers ship with the OSA agent installed but disabled by default. Activate it to give your computer an in-VM AI assistant that can run multi-step desktop tasks autonomously. OSA runs locally inside the computer — see the OSA documentation for details.

## Next


    Full action reference: screenshot, click, type, key, scroll, drag, hotkey, windows, accessibility tree, and more.
    [Open →](/docs/computers/desktop/)


    Embed the live pixel stream in your own UI using short-lived stream tokens.
    [Open →](/docs/computers/embedding/)


    Bring your own hardware (Mac, Linux, Windows). One command registers your machine as a MIOSA computer.
    [Open →](/docs/computers/byoc/)

---

# Core Concepts

URL: https://miosa.ai/docs/concepts
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/concepts
Source: src/routes/docs/concepts/+page.md
Description: The canonical architecture reference for MIOSA — six concrete primitives, how they compose into deployments, data services, desktop Computers, and the white-label tenancy model.

# Core Concepts

MIOSA is a cloud platform for building, previewing, and deploying applications — primarily by AI agents, but equally usable by developers directly. Every operation maps to one of the six primitive resource types below. Everything else is composition.

If you read only one sentence: **Sandbox → Builder → Release → Version → Deployment → Domain.** That is the full publish pipeline.

---

## Physical base

MIOSA runs on bare-metal compute hosts. Each host runs [Firecracker](https://firecracker-microvm.github.io/), a hypervisor that starts microVMs in approximately 150 ms. Every workload — sandbox, builder, runtime instance, computer — is one of these microVMs. The product names below describe what the VM does, not how it is implemented.

You never interact with Firecracker directly.

---

## The six concrete things

### Sandbox

A **Sandbox** is a mutable Firecracker microVM where an agent or developer builds an app. It boots from a MIOSA sandbox image (for example, `miosa-sandbox`) and ships with a full development environment: Node, Python, git, package managers, and a terminal.

Key properties:

- **Mutable and stateful.** Files in `/workspace` persist across exec calls until the sandbox is destroyed or auto-suspended.
- **Exec surface.** Call `exec` to run any shell command — `npm install`, `python app.py`, `git clone` — and get stdout/stderr back.
- **File I/O.** Read and write files at arbitrary paths. Agents use this to generate code, configs, and assets.
- **Preview tunnels.** Open any port inside the sandbox to the public internet via a Preview URL (see below).
- **Snapshots.** Freeze the full VM state, fork from it, or restore it. Enables fast branching and rollback during development.
- **Auto-suspend.** Idle sandboxes suspend after a configurable timeout to save compute. Resume is near-instant from snapshot.

A Sandbox is **not production**. Production traffic never routes to a sandbox. The sandbox is where you build the thing that will become production.

[Sandboxes reference →](/docs/develop/sandboxes/)

### Preview

A **Preview** is a temporary public URL that tunnels to a port inside a running sandbox.
```

https://abc12345.preview.miosa.app
```

When you create a preview, you specify the sandbox port (typically 3000 for a dev server). MIOSA's edge proxy maps that hostname to the sandbox's internal IP and port. As files change inside the sandbox and the dev server hot-reloads, the preview updates live.

Key properties:

- **Mutable.** The preview reflects the live state of the sandbox at every request.
- **Ephemeral.** The preview URL dies when the sandbox is destroyed or suspended.
- **Share tokens.** For embedding previews in your own product's UI, your backend mints a short-lived share token. The token is safe to put in a browser `&lt;iframe&gt;` — it grants time-limited preview access without exposing the workspace API key.

[Previews reference →](/docs/develop/previews/)

### Builder

A **Builder** is a Firecracker microVM that runs for exactly one publish job. It boots from the dedicated `miosa-builder` template, pulls an immutable source snapshot from the sandbox at publish time, runs the build pipeline, uploads the result, and exits.

Three build modes:

| Mode | Trigger | Output |
|------|---------|--------|
| Static packager | `/workspace` has only static files | Tarball served from MIOSA's edge |
| Railpack auto-detect | Node/Python/Ruby/Go project detected | Dynamic rootfs booted as Runtime Instances |
| Dockerfile | `Dockerfile` present in `/workspace` | Dynamic rootfs booted as Runtime Instances |

The Builder is internal. You never address it directly. It exists so production builds are reproducible (source is frozen at publish time, not the live mutable sandbox) and so your sandbox keeps running while the build executes.

### Release

A **Release** is the immutable artifact produced by a Builder run. It is sha256-keyed and stored in object storage. The same release can be deployed to any number of regions, booted N times, and referenced by multiple versions — the content never changes.

Two shapes:

- **Static release** — a tarball of files (`index.html`, `app.js`, assets). MIOSA's edge serves them directly. No Runtime Instances required.
- **Dynamic release** — a rootfs / OCI image. Booted as Runtime Instances in production.

[Releases reference →](/docs/deploy/releases/)

### Runtime Instance

A **Runtime Instance** is a Firecracker microVM running a dynamic release in production. It boots from the release rootfs (not from the sandbox image), serves real traffic, and is managed by a scheduler and reconciler.

Key properties:

- **Scheduler placement.** Instances are placed on fleet hosts by a scheduler that watches CPU, RAM, and region capacity.
- **Horizontal scaling.** Multiple instances can serve a single version simultaneously.
- **Health checks.** The reconciler replaces instances that fail health checks without manual intervention.
- **Isolation.** Each instance runs in its own microVM, fully isolated from other tenants.

Static deployments have no Runtime Instances — files are served from the edge directly.

[Runtime Instances reference →](/docs/deploy/runtime-instances/)

### Domain

A **Domain** is a DNS hostname routed to a deployment's active version. Three tiers:

- `my-app.miosa.app` — MIOSA-managed subdomain, instant, no DNS change needed.
- `app.yourcustomer.com` — custom domain your customer brings; MIOSA auto-provisions a TLS certificate via Let's Encrypt.
- Internal routing domains for multi-region or canary setups.

Changing the domain mapping does not rebuild the app — it updates routing only. This is how rollback works: repoint the domain at an older ready version.

[Domains reference →](/docs/deploy/domains/)

---

## Deployments, Versions, and the publish pipeline

A **Deployment** is the stable product object — the thing the world thinks of as "the live app." It holds an `active_version_id`. Publishing creates a new **Version**, which references a **Release**. Promoting a version updates `active_version_id`; rollback resets it.
Diagram:
flowchart LR
  S[Sandbox] -->|publish| B[Builder]
  B -->|builds| R[Release]
  R -->|referenced by| V[Version]
  V -->|active for| D[Deployment]
  Dom[Domain] -->|routes to| D
  D -->|spawns| RI[Runtime Instances]

Full object hierarchy:
Diagram:
graph TD
  Proj["Project"]
  Dep["Deployment<br/>smile-dental"]
  V17["Version 17<br/>(active)"]
  V16["Version 16<br/>(archived)"]
  V15["Version 15<br/>(archived)"]
  Rel["Release sha:abc"]
  RI["Runtime Instances"]
  D1["smiledental.miosa.app"]
  D2["smiledental.test"]
  Proj --> Dep
  Dep -->|active_version_id| V17
  Dep --> V16
  Dep --> V15
  V17 --> Rel
  Rel --> RI
  Dep --> D1
  Dep --> D2

Rollback is Version 16 → `active_version_id`. Runtime Instances for Version 17 drain and exit; Version 16 instances start. Domain routing never changes — the domain still points at the same Deployment.

[Deploy overview →](/docs/deploy/overview/)

---

## Data services

Sandboxes and Runtime Instances are ephemeral. **Data Services** are not. MIOSA provisions and operates them outside the version lifecycle — destroying a sandbox or publishing a new version does not affect them.

| Service | What it is |
|---------|-----------|
| Managed Postgres | Fully managed PostgreSQL database. Schema migrations are yours to run; MIOSA provides the connection string. |
| Managed Redis | Persistent Redis cluster for caching, queues, pub/sub. |
| Object Storage | S3-compatible bucket. Useful for uploads, assets, generated files. |
| Volumes | Block storage mounted into Runtime Instances. Persists across restarts. |
| Auth | JWT-based signup/login as a service. One env var gives your project a full auth system. |

Both the sandbox and runtime instances receive credentials as environment variables at boot:
```

DATABASE_URL=postgresql://user:pass@host/dbname
REDIS_URL=redis://host:6379
STORAGE_BUCKET=miosa-ws123-uploads
AUTH_URL=https://auth.miosa.app/proj_abc
AUTH_JWT_SECRET=...
```

Destroying a sandbox does not destroy its database. Publishing a new version does not run migrations — MIOSA gives you the connection string; you run `db:migrate` in your deploy hook.

Managed Postgres and Auth are part of the platform Phase 6–8 rollout. The doc surface is published now so you can plan integration; some endpoints are still being wired in production.

[Data overview →](/docs/data/overview/)

---

## Computers (desktop product)

**Computers** are full Linux desktop VMs running in the cloud with screenshot, click, type, and keyboard APIs. They are a separate product surface from Sandboxes — different lifecycle, different use cases.

| | Sandbox | Computer |
|---|---|---|
| Primary use | Code execution, file I/O, dev servers, agent tool-use | Desktop GUI, browser automation, computer-use agents |
| Display | None (headless) | X11 + VNC |
| Accessibility tree | No | Yes |
| Lifecycle | Short-to-medium lived, auto-suspend | Session-oriented |
| Templates | `miosa-sandbox`, `miosa-node`, etc. | `miosa-desktop` |

Use Sandboxes for building apps. Use Computers when your agent or workflow needs a real screen.

You can also bring your own hardware (Mac, Linux, Windows) and register it as a Computer host via BYOC.

[Computers overview →](/docs/computers/overview/)

---

## White-label tenancy

MIOSA is designed for platforms — you build a product on top of MIOSA, and your customers never know MIOSA exists.

The tenancy model:

- **One MIOSA organization per customer platform.** A platform account has one organization slug and server-side `msk_*` keys.
- **Workspaces and projects for downstream customers.** Use MIOSA workspaces for clients and projects for the apps, sites, documents, and workflows they create.
- **External attribution for your IDs.** Pass `external_workspace_id`, `external_user_id`, and `external_project_id` when you need your database IDs on usage, audit, and list filters.
- **Server-side key, never in the browser.** For browser-side access (embedding a preview, opening a terminal), your backend mints a short-lived scoped token. The `msk_*` key stays server-side.
Diagram:
graph TD
  Plat["Your Platform"]
  Org["MIOSA Organization<br/>one slug · one bill"]
  WS["Workspace<br/>Dr. Smith Clinic"]
  Proj["Project<br/>Lead Magnet"]
  Sbx["Sandbox"]
  Dep["Deployment"]
  Plat --> Org
  Org --> WS
  WS --> Proj
  Proj --> Sbx
  Proj --> Dep

Filters are always organization-scoped server-side. You cannot cross organizations by passing different workspace, project, or external IDs.

[Platform / White-label overview →](/docs/platform/overview/)

---

## Three naming layers

One thing trips up every new reader: "Computer" has a specific meaning in MIOSA.

| Layer | Term | Meaning |
|-------|------|---------|
| Brand | **MIOSA** | The wordmark and platform. |
| Resource | **Computer** | The desktop GUI product. Not a generic synonym for "VM." |
| AI agent | **OSA / Optimal** | The in-VM AI agent runtime. Optional; installable inside a Sandbox or Computer. |

Sandboxes are not Computers. Runtime Instances are not Computers. Computers are Computers. When you encounter older docs or code that uses "Computer" generically, substitute "Sandbox" or "Runtime Instance" based on context.

---

## What's next


    Five-minute hands-on tour. Create a sandbox, write code, publish to a live URL.
    [Start →](/docs/quickstart/)


    Deep-dive on Sandboxes, file I/O, exec, previews, and the dev loop.
    [Develop →](/docs/develop/sandboxes/)


    Builder, Release, Runtime Instance, Domains — the full publish pipeline.
    [Deploy →](/docs/deploy/overview/)


    White-label tenancy, browser tokens, attribution, and API keys.
    [Platform →](/docs/platform/overview/)

---

# Cookbook

URL: https://miosa.ai/docs/cookbook
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook
Source: src/routes/docs/cookbook/+page.md
Description: End-to-end recipes — copy-paste-runnable walkthroughs that showcase the MIOSA platform.

# Cookbook

Practical, end-to-end walkthroughs. Each recipe starts from a blank terminal and ends with something running. Pick the one closest to your use case and adapt from there.

---


    Your AI agent receives a prompt, writes code into a sandbox, runs the build, exposes a preview URL, then publishes to production. End deliverable: a deployed Next.js app from a single prompt.


    Run a long Python script in a sandbox and stream stdout to your UI in real time via SSE. Includes backpressure handling. End deliverable: a code-execution console-style UI snippet.


    Embed MIOSA into your SaaS. Tag every sandbox with your own workspace and user IDs, query usage per tenant, and issue browser tokens so your customers interact directly with their sandbox without seeing your API key.


    Checkpoint a long-running task, fork into multiple branches, compare outcomes, and restore to a known-good state on failure.


    Boot a Computer (full Linux desktop), screenshot a website, click a button, fill a form, take another screenshot. Implements the screenshot → action → screenshot loop with your own LLM.


---

## Before you start

All recipes share the same prerequisites:

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- Node 22+ **or** Python 3.11+ installed locally
- The MIOSA SDK installed for your language:

```bash
# Python
pip install miosa

# TypeScript / Node
npm install @miosa/sdk
```

Set the key in your environment once — every recipe reads it from there:

```bash
export MIOSA_API_KEY="msk_live_..."
```

---

# Agent builds an app

URL: https://miosa.ai/docs/cookbook/agent-builds-app
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/agent-builds-app
Source: src/routes/docs/cookbook/agent-builds-app/+page.md
Description: Your AI agent receives a prompt, writes code into a sandbox, builds it, and publishes a deployed Next.js app — all from a single prompt.

# Agent builds an app

~10 min Python TypeScript

> **Goal**: Wire an LLM agent to MIOSA so it can write code, build it inside a sandbox, open a live preview, then publish to a production deployment — all from a single user prompt.
>
> **What you'll use**: Sandboxes, Previews, Deployments

## What you'll build

A function `build_and_deploy(prompt)` that hands a prompt to an LLM, streams generated code into a sandbox, runs `npm run build`, surfaces a preview URL, then publishes an immutable production release. The user sees a live URL in under 60 seconds.

The pattern is the same whether you use Anthropic, OpenAI, or any other model — MIOSA is the execution layer, your agent loop is the thinking layer.

## Prerequisites

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- An Anthropic API key (or substitute your preferred provider)
- Node 22+ or Python 3.11+

## Step 1 — Install and configure

```bash
pip install miosa anthropic
export MIOSA_API_KEY="msk_live_..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

```bash
npm install @miosa/sdk @anthropic-ai/sdk
export MIOSA_API_KEY="msk_live_..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

## Step 2 — Boot a sandbox

Create a Next.js sandbox. The template already has Node, pnpm, and a Next.js scaffold — no `npx create-next-app` needed.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

sbx = client.sandboxes.create(
    template_id="nextjs",
    timeout_sec=600,
)
print(f"Sandbox ready: {sbx.id}")
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const sbx = await client.sandboxes.create({
  templateId: 'nextjs',
  timeoutSec: 600,
});
console.log('Sandbox ready:', sbx.id);
```

## Step 3 — Ask the LLM to generate code

Call the model with a system prompt that instructs it to produce a complete `app/page.tsx` file. Keep it deterministic by setting `temperature=0`.

```python

ai = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def generate_page(prompt: str) -> str:
    msg = ai.messages.create(
        model="claude-opus-4-5",
        max_tokens=4096,
        system=(
            "You are a Next.js developer. "
            "Respond with ONLY the complete content of app/page.tsx. "
            "No explanation, no markdown fences, just valid TypeScript."
        ),
        messages=[{"role": "user", "content": prompt}],
    )
    return msg.content[0].text

user_prompt = "Build a landing page for a dog-walking app with a hero, feature list, and CTA."
page_code = generate_page(user_prompt)
```

```typescript

const ai = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

async function generatePage(prompt: string): Promise<string> {
  const msg = await ai.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 4096,
    system:
      'You are a Next.js developer. ' +
      'Respond with ONLY the complete content of app/page.tsx. ' +
      'No explanation, no markdown fences, just valid TypeScript.',
    messages: [{ role: 'user', content: prompt }],
  });
  const block = msg.content[0];
  return block.type === 'text' ? block.text : '';
}

const userPrompt = 'Build a landing page for a dog-walking app with a hero, feature list, and CTA.';
const pageCode = await generatePage(userPrompt);
```

## Step 4 — Write the file and build

Write the generated code into the sandbox filesystem, install any new dependencies, and run the build. Stream exec output so you can surface progress to the user in real time.

```python
# Write the agent-generated file
sbx.files.write("/workspace/app/page.tsx", page_code)

# Install dependencies (idempotent — next.js template already ran pnpm install)
install = sbx.exec("pnpm install", cwd="/workspace")
if install.exit_code != 0:
    raise RuntimeError(f"pnpm install failed:\n{install.stderr}")

# Build
build = sbx.exec("pnpm run build", cwd="/workspace")
if build.exit_code != 0:
    # Feed the error back to the agent for a self-correction turn
    correction_prompt = (
        f"The build failed with this error:\n{build.stderr}\n\n"
        "Return a corrected app/page.tsx that fixes the error."
    )
    page_code = generate_page(correction_prompt)
    sbx.files.write("/workspace/app/page.tsx", page_code)
    build = sbx.exec("pnpm run build", cwd="/workspace")
    if build.exit_code != 0:
        raise RuntimeError("Build failed after self-correction attempt.")

print("Build succeeded.")
```

```typescript
// Write the agent-generated file
await sbx.files.write('/workspace/app/page.tsx', pageCode);

// Install dependencies
const install = await sbx.exec('pnpm install', { cwd: '/workspace' });
if (install.exitCode !== 0) {
  throw new Error(`pnpm install failed:\n${install.stderr}`);
}

// Build
let build = await sbx.exec('pnpm run build', { cwd: '/workspace' });
if (build.exitCode !== 0) {
  // Self-correction turn
  const correctionPrompt =
    `The build failed with this error:\n${build.stderr}\n\n` +
    'Return a corrected app/page.tsx that fixes the error.';
  pageCode = await generatePage(correctionPrompt);
  await sbx.files.write('/workspace/app/page.tsx', pageCode);
  build = await sbx.exec('pnpm run build', { cwd: '/workspace' });
  if (build.exitCode !== 0) {
    throw new Error('Build failed after self-correction attempt.');
  }
}

console.log('Build succeeded.');
```

The self-correction pattern above is a one-turn fix loop. Production agents typically run 3–5 correction turns before surfacing an error to the user.

## Step 5 — Open a preview

Start the Next.js dev server, then expose port 3000 as a public URL your user can open immediately.

```python
# Start dev server (detached — runs in background inside the sandbox)
sbx.exec("pnpm run start --port 3000", cwd="/workspace", background=True)

# Expose port 3000
preview = sbx.previews.create(port=3000)
print(f"Live preview: {preview['url']}")
```

```typescript
// Start the production server (detached)
await sbx.exec('pnpm run start --port 3000', { cwd: '/workspace', background: true });

// Expose port 3000
const preview = await sbx.previews.create({ port: 3000 });
console.log('Live preview:', preview.url);
```

## Step 6 — Publish to production

When the user confirms, publish the sandbox to a permanent production deployment. The deployment is immutable — the sandbox can be destroyed after this.

```python
deployment = client.deployments.publish(
    source_sandbox_id=sbx.id,
    name="dogwalk-landing",
)

# Wait for the deployment to become live

while deployment.status not in ("live", "failed"):
    time.sleep(2)
    deployment = client.deployments.get(deployment.id)

if deployment.status == "failed":
    raise RuntimeError(f"Deployment failed: {deployment.error}")

print(f"Production URL: {deployment.url}")

# Clean up the sandbox — no longer needed
sbx.delete()
```

```typescript
let deployment = await client.deployments.publish({
  sourceSandboxId: sbx.id,
  name: 'dogwalk-landing',
});

// Wait for live
while (deployment.status !== 'live' && deployment.status !== 'failed') {
  await new Promise(r => setTimeout(r, 2000));
  deployment = await client.deployments.get(deployment.id);
}

if (deployment.status === 'failed') {
  throw new Error(`Deployment failed: ${deployment.error}`);
}

console.log('Production URL:', deployment.url);

// Clean up
await sbx.delete();
```

## Full script

```python
#!/usr/bin/env python3
"""agent_builds_app.py — full end-to-end recipe"""

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
ai = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def generate_page(prompt: str) -> str:
    msg = ai.messages.create(
        model="claude-opus-4-5",
        max_tokens=4096,
        system=(
            "You are a Next.js developer. Respond with ONLY the complete "
            "content of app/page.tsx. No explanation, no markdown fences."
        ),
        messages=[{"role": "user", "content": prompt}],
    )
    return msg.content[0].text

def build_and_deploy(user_prompt: str) -> str:
    sbx = client.sandboxes.create(template_id="nextjs", timeout_sec=600)

    page_code = generate_page(user_prompt)
    sbx.files.write("/workspace/app/page.tsx", page_code)

    sbx.exec("pnpm install", cwd="/workspace")
    build = sbx.exec("pnpm run build", cwd="/workspace")

    if build.exit_code != 0:
        page_code = generate_page(
            f"Fix this Next.js build error and return corrected app/page.tsx:\n{build.stderr}"
        )
        sbx.files.write("/workspace/app/page.tsx", page_code)
        build = sbx.exec("pnpm run build", cwd="/workspace")
        if build.exit_code != 0:
            sbx.delete()
            raise RuntimeError("Build failed after correction.")

    sbx.exec("pnpm run start --port 3000", cwd="/workspace", background=True)
    preview = sbx.previews.create(port=3000)
    print(f"Preview: {preview['url']}")

    deployment = client.deployments.publish(
        source_sandbox_id=sbx.id,
        name="agent-built-app",
    )
    while deployment.status not in ("live", "failed"):
        time.sleep(2)
        deployment = client.deployments.get(deployment.id)

    sbx.delete()

    if deployment.status == "failed":
        raise RuntimeError(f"Deployment failed: {deployment.error}")

    return deployment.url

if __name__ == "__main__":
    url = build_and_deploy(
        "Build a landing page for a dog-walking app with a hero, feature list, and CTA."
    )
    print(f"\nProduction URL: {url}")
```

```typescript
// agent-builds-app.ts — full end-to-end recipe

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const ai = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

async function generatePage(prompt: string): Promise<string> {
  const msg = await ai.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 4096,
    system:
      'You are a Next.js developer. Respond with ONLY the complete content ' +
      'of app/page.tsx. No explanation, no markdown fences.',
    messages: [{ role: 'user', content: prompt }],
  });
  const block = msg.content[0];
  return block.type === 'text' ? block.text : '';
}

async function buildAndDeploy(userPrompt: string): Promise<string> {
  const sbx = await client.sandboxes.create({ templateId: 'nextjs', timeoutSec: 600 });

  let pageCode = await generatePage(userPrompt);
  await sbx.files.write('/workspace/app/page.tsx', pageCode);

  await sbx.exec('pnpm install', { cwd: '/workspace' });
  let build = await sbx.exec('pnpm run build', { cwd: '/workspace' });

  if (build.exitCode !== 0) {
    pageCode = await generatePage(
      `Fix this Next.js build error and return corrected app/page.tsx:\n${build.stderr}`,
    );
    await sbx.files.write('/workspace/app/page.tsx', pageCode);
    build = await sbx.exec('pnpm run build', { cwd: '/workspace' });
    if (build.exitCode !== 0) {
      await sbx.delete();
      throw new Error('Build failed after correction.');
    }
  }

  await sbx.exec('pnpm run start --port 3000', { cwd: '/workspace', background: true });
  const preview = await sbx.previews.create({ port: 3000 });
  console.log('Preview:', preview.url);

  let deployment = await client.deployments.publish({
    sourceSandboxId: sbx.id,
    name: 'agent-built-app',
  });

  while (deployment.status !== 'live' && deployment.status !== 'failed') {
    await new Promise(r => setTimeout(r, 2000));
    deployment = await client.deployments.get(deployment.id);
  }

  await sbx.delete();

  if (deployment.status === 'failed') {
    throw new Error(`Deployment failed: ${deployment.error}`);
  }

  return deployment.url;
}

const url = await buildAndDeploy(
  'Build a landing page for a dog-walking app with a hero, feature list, and CTA.',
);
console.log('\nProduction URL:', url);
```

## What you learned

- Sandboxes boot in ~150 ms from a warm template — fast enough to create one per user request.
- The LLM and the sandbox are completely decoupled. Swap any model without touching the execution logic.
- A single self-correction turn catches most build errors automatically.
- `deployments.publish` produces an immutable release; the sandbox can be destroyed immediately after.
- `background: true` on exec keeps long-running processes alive without blocking your driver script.

## Next


    Stream exec stdout to your UI in real time instead of waiting for a result.


    Checkpoint before risky steps and fork into parallel branches to compare outcomes.


    Full guide on wiring agents to MIOSA, including multi-turn state and approval workflows.

---

# Browser agent

URL: https://miosa.ai/docs/cookbook/browser-agent
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/browser-agent
Source: src/routes/docs/cookbook/browser-agent/+page.md
Description: Boot a full Linux desktop Computer, screenshot a website, click a button, fill a form, take another screenshot — the complete screenshot → action → screenshot loop with your own LLM.

# Browser agent

~12 min Python TypeScript

> **Goal**: Boot a MIOSA Computer (full Linux desktop VM), open a browser inside it, and run an LLM-driven action loop that screenshots the screen, decides what to do next, and executes the action — all from your own code.
>
> **What you'll use**: Computers, Desktop API (screenshot / click / type / key)

## What you'll build

A `BrowserAgent` class that:
1. Boots a Computer with a full desktop.
2. Opens a URL in Chromium.
3. Enters a screenshot → LLM → action loop.
4. Stops when the LLM signals completion.

The LLM is your choice — the code below uses Anthropic Claude's vision API but the pattern is model-agnostic.

## Prerequisites

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- An Anthropic API key (or substitute your preferred vision-capable model)
- Node 22+ or Python 3.11+

## Step 1 — Install and configure

```bash
pip install miosa anthropic
export MIOSA_API_KEY="msk_live_..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

```bash
npm install @miosa/sdk @anthropic-ai/sdk
export MIOSA_API_KEY="msk_live_..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

## Step 2 — Boot a Computer

Computers take ~10 seconds to boot (full desktop VM, not a microVM). Create one, start it, then wait for it to reach `running`.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

print("Booting Computer...")
computer = client.computers.create(template="ubuntu-desktop")
computer.start()

# Wait for running
while computer.status != "running":
    if computer.status == "error":
        raise RuntimeError(f"Computer failed to boot: {computer.metadata.get('last_error')}")
    time.sleep(2)
    computer = client.computers.get(computer.id)

print(f"Computer running: {computer.id}")
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

console.log('Booting Computer...');
let computer = await client.computers.create({ template: 'ubuntu-desktop' });
await computer.start();

// Wait for running
while (computer.status !== 'running') {
  if (computer.status === 'error') {
    throw new Error(`Computer failed to boot: ${computer.metadata?.lastError}`);
  }
  await new Promise(r => setTimeout(r, 2000));
  computer = await client.computers.get(computer.id);
}

console.log('Computer running:', computer.id);
```

## Step 3 — Take a screenshot

The desktop starts at the Linux login screen or a default desktop. Take the first screenshot to see what you are working with.

```python

# screenshot() returns a PNG as bytes
png = computer.screenshot()

# Save for inspection (optional)
with open("/tmp/screenshot_0.png", "wb") as f:
    f.write(png)

# Encode for the LLM
png_b64 = base64.b64encode(png).decode()
print(f"Screenshot captured ({len(png)} bytes)")
```

```typescript

// screenshot() returns a Buffer (PNG)
const png = await computer.screenshot();

// Save for inspection (optional)
writeFileSync('/tmp/screenshot_0.png', png);

// Encode for the LLM
const pngB64 = png.toString('base64');
console.log(`Screenshot captured (${png.length} bytes)`);
```

## Step 4 — Open a URL in the browser

Use `exec` to launch Chromium with the target URL. The desktop VM has Chromium pre-installed.

```python
# Launch Chromium pointing to the target site
computer.exec(
    "chromium-browser --no-sandbox --start-maximized https://example.com",
    background=True,
)

# Wait for the browser to load
time.sleep(3)

# Take a screenshot to confirm the page loaded
png = computer.screenshot()
with open("/tmp/screenshot_1.png", "wb") as f:
    f.write(png)
png_b64 = base64.b64encode(png).decode()
```

```typescript
// Launch Chromium
await computer.exec(
  'chromium-browser --no-sandbox --start-maximized https://example.com',
  { background: true },
);

// Wait for browser to load
await new Promise(r => setTimeout(r, 3000));

// Screenshot the loaded page
const png = await computer.screenshot();
writeFileSync('/tmp/screenshot_1.png', png);
const pngB64 = png.toString('base64');
```

## Step 5 — Build the action loop

Ask the LLM what to do next, then execute the returned action on the computer. Repeat until the model signals `done`.

The system prompt below instructs the model to return a JSON action object — a minimal tool-call format that does not require function calling support.

```python

ai = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM_PROMPT = """\
You control a desktop browser. You receive a screenshot and a task.
Respond with ONLY a JSON object — no explanation, no markdown fences.

Action format:
  {"type": "click", "x": <int 0-1000>, "y": <int 0-1000>}
  {"type": "type", "text": "<string>"}
  {"type": "key", "combo": "<key combo>"}     e.g. "ctrl+a", "enter", "tab"
  {"type": "scroll", "x": <int>, "y": <int>, "direction": "up"|"down"}
  {"type": "screenshot"}                       take a fresh screenshot without acting
  {"type": "done", "result": "<summary>"}      task complete

Coordinates are 0-1000 on both axes regardless of screen resolution.
"""

def next_action(task: str, png_b64: str, history: list) -> dict:
    messages = history + [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "base64", "media_type": "image/png", "data": png_b64},
                },
                {"type": "text", "text": f"Task: {task}"},
            ],
        }
    ]
    msg = ai.messages.create(
        model="claude-opus-4-5",
        max_tokens=256,
        system=SYSTEM_PROMPT,
        messages=messages,
    )
    text = msg.content[0].text.strip()
    return json.loads(text)
```

```typescript

const ai = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const SYSTEM_PROMPT = `
You control a desktop browser. You receive a screenshot and a task.
Respond with ONLY a JSON object — no explanation, no markdown fences.

Action format:
  {"type": "click", "x": <int 0-1000>, "y": <int 0-1000>}
  {"type": "type", "text": "<string>"}
  {"type": "key", "combo": "<key combo>"}
  {"type": "scroll", "x": <int>, "y": <int>, "direction": "up"|"down"}
  {"type": "screenshot"}
  {"type": "done", "result": "<summary>"}

Coordinates are 0-1000 on both axes regardless of screen resolution.
`.trim();

type AgentHistory = Anthropic.MessageParam[];

async function nextAction(
  task: string,
  pngB64: string,
  history: AgentHistory,
): Promise<Record<string, unknown>> {
  const messages: AgentHistory = [
    ...history,
    {
      role: 'user',
      content: [
        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: pngB64 } },
        { type: 'text', text: `Task: ${task}` },
      ],
    },
  ];
  const msg = await ai.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 256,
    system: SYSTEM_PROMPT,
    messages,
  });
  const block = msg.content[0];
  const text = block.type === 'text' ? block.text.trim() : '{}';
  return JSON.parse(text);
}
```

## Step 6 — Execute actions on the Computer

Translate the LLM's JSON output into Computer API calls. MIOSA coordinates are 0–1000 on both axes regardless of the actual screen resolution.

```python
def execute_action(computer, action: dict) -> bytes | None:
    """Execute an action and return the next screenshot (or None for done)."""
    t = action["type"]

    if t == "click":
        computer.left_click(action["x"], action["y"])
    elif t == "type":
        computer.type_text(action["text"])
    elif t == "key":
        computer.key(action["combo"])
    elif t == "scroll":
        computer.scroll(action["x"], action["y"], action["direction"])
    elif t == "screenshot":
        pass  # fall through to capture below
    elif t == "done":
        return None

    time.sleep(0.5)  # let the UI settle
    return computer.screenshot()
```

```typescript
async function executeAction(
  computer: Computer,
  action: Record<string, unknown>,
): Promise {
  const { type: t } = action;

  if (t === 'click') {
    await computer.leftClick(action.x as number, action.y as number);
  } else if (t === 'type') {
    await computer.typeText(action.text as string);
  } else if (t === 'key') {
    await computer.key(action.combo as string);
  } else if (t === 'scroll') {
    await computer.scroll(
      action.x as number,
      action.y as number,
      action.direction as 'up' | 'down',
    );
  } else if (t === 'screenshot') {
    // fall through to screenshot below
  } else if (t === 'done') {
    return null;
  }

  await new Promise(r => setTimeout(r, 500)); // let UI settle
  return computer.screenshot();
}
```

## Step 7 — Run the full agent loop

Combine the pieces into a loop capped at `max_turns` to prevent runaway execution.

```python
TASK = "Find the 'More information...' link on example.com, click it, then report the URL you land on."
MAX_TURNS = 20

history = []
current_png = png  # screenshot from Step 4
current_png_b64 = png_b64

for turn in range(1, MAX_TURNS + 1):
    print(f"\n--- Turn {turn} ---")
    action = next_action(TASK, current_png_b64, history)
    print(f"Action: {action}")

    # Append to history so the model sees its own prior decisions
    history.append({
        "role": "assistant",
        "content": [{"type": "text", "text": json.dumps(action)}],
    })

    if action["type"] == "done":
        print(f"\nDone: {action.get('result')}")
        break

    next_png = execute_action(computer, action)
    if next_png is None:
        break

    current_png = next_png
    current_png_b64 = base64.b64encode(current_png).decode()

    # Save each turn for debugging
    with open(f"/tmp/screenshot_{turn}.png", "wb") as f:
        f.write(current_png)
else:
    print(f"Reached max turns ({MAX_TURNS}) without completion.")

# Clean up
computer.stop()
```

```typescript
const TASK =
  "Find the 'More information...' link on example.com, click it, then report the URL you land on.";
const MAX_TURNS = 20;

const history: AgentHistory = [];
let currentPng = png; // from Step 4
let currentPngB64 = pngB64;

for (let turn = 1; turn <= MAX_TURNS; turn++) {
  console.log(`\n--- Turn ${turn} ---`);
  const action = await nextAction(TASK, currentPngB64, history);
  console.log('Action:', action);

  history.push({
    role: 'assistant',
    content: [{ type: 'text', text: JSON.stringify(action) }],
  });

  if (action.type === 'done') {
    console.log('\nDone:', action.result);
    break;
  }

  const nextPng = await executeAction(computer, action);
  if (nextPng === null) break;

  currentPng = nextPng;
  currentPngB64 = currentPng.toString('base64');

  writeFileSync(`/tmp/screenshot_${turn}.png`, currentPng);

  if (turn === MAX_TURNS) {
    console.log(`Reached max turns (${MAX_TURNS}) without completion.`);
  }
}

await computer.stop();
```

## Full script (Python)

```python
#!/usr/bin/env python3
"""browser_agent.py — complete screenshot → action → screenshot loop"""

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
ai = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM_PROMPT = """\
You control a desktop browser. You receive a screenshot and a task.
Respond with ONLY a JSON object — no explanation, no markdown fences.
Actions: click(x,y) | type(text) | key(combo) | scroll(x,y,direction) | screenshot | done(result)
Coordinates are 0-1000 on both axes.
"""

def next_action(task, png_b64, history):
    messages = history + [{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": png_b64}},
            {"type": "text", "text": f"Task: {task}"},
        ],
    }]
    msg = ai.messages.create(model="claude-opus-4-5", max_tokens=256, system=SYSTEM_PROMPT, messages=messages)
    return json.loads(msg.content[0].text.strip())

def execute(computer, action):
    t = action["type"]
    if t == "click":     computer.left_click(action["x"], action["y"])
    elif t == "type":    computer.type_text(action["text"])
    elif t == "key":     computer.key(action["combo"])
    elif t == "scroll":  computer.scroll(action["x"], action["y"], action["direction"])
    elif t == "done":    return None
    time.sleep(0.5)
    return computer.screenshot()

def run(task: str, url: str, max_turns: int = 20) -> str:
    computer = client.computers.create(template="ubuntu-desktop")
    computer.start()
    while computer.status != "running":
        time.sleep(2)
        computer = client.computers.get(computer.id)

    computer.exec(f"chromium-browser --no-sandbox --start-maximized {url}", background=True)
    time.sleep(3)

    png = computer.screenshot()
    png_b64 = base64.b64encode(png).decode()
    history = []

    try:
        for turn in range(1, max_turns + 1):
            action = next_action(task, png_b64, history)
            print(f"Turn {turn}: {action}")
            history.append({"role": "assistant", "content": [{"type": "text", "text": json.dumps(action)}]})
            if action["type"] == "done":
                return action.get("result", "")
            nxt = execute(computer, action)
            if nxt is None:
                return ""
            png_b64 = base64.b64encode(nxt).decode()
        return f"Stopped after {max_turns} turns."
    finally:
        computer.stop()

if __name__ == "__main__":
    result = run(
        task="Find the 'More information...' link, click it, report the landing URL.",
        url="https://example.com",
    )
    print(f"\nResult: {result}")
```

Coordinates are always 0–1000 regardless of actual screen resolution. MIOSA's desktop API normalizes all input to this coordinate space. Tell the LLM the same constraint in the system prompt so it does not produce pixel-perfect coordinates from the screenshot dimensions.

## Tips for reliable browser agents

- **Add `time.sleep(0.5)` after every action.** Browsers animate and reflow. Acting on a screenshot taken 0 ms after a click often shows the pre-click state.
- **Save every screenshot.** The debug loop is: screenshot N shows the state the model reasoned about to produce action N. When an agent gets stuck, inspect the saved screenshots.
- **Cap `max_turns` tightly (10–25).** A runaway agent loop can exhaust credits fast. Set the ceiling and surface the incomplete-task status cleanly.
- **Use `computer.key("ctrl+r")` to reload.** If the page looks broken, a reload is often cheaper than restarting the Computer.
- **Snapshot after login.** If the task requires authenticating, snapshot immediately after the login succeeds. Restore from the snapshot for subsequent tasks to skip the login every time.

## What you learned

- `client.computers.create` + `computer.start()` boots a full Linux desktop VM.
- `computer.screenshot()` returns raw PNG bytes at any point.
- `computer.left_click(x, y)`, `computer.type_text(text)`, `computer.key(combo)`, and `computer.scroll(x, y, direction)` are the four action primitives.
- Coordinates are 0–1000 normalized — tell your LLM the same range.
- The agent loop is yours: MIOSA executes actions, your code decides what to do next.

## Next


    Full Computer lifecycle, sizing, templates, and the difference between Computers and Sandboxes.


    Complete method signatures for screenshot, click, type, key, and scroll.


    Multi-turn state management, approval workflows, and best practices for agent loops.

---

# Multi-tenant SaaS

URL: https://miosa.ai/docs/cookbook/multi-tenant-saas
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/multi-tenant-saas
Source: src/routes/docs/cookbook/multi-tenant-saas/+page.md
Description: Embed MIOSA into your SaaS — tag sandboxes per tenant, query usage per workspace, and issue browser tokens so customers interact directly with their sandboxes.

# Multi-tenant SaaS

~12 min Python TypeScript

> **Goal**: Embed MIOSA into a multi-tenant product. Every sandbox is tagged with your own workspace and user IDs. Usage rolls up per tenant for billing. End-users interact with their sandboxes directly from the browser without ever seeing your API key.
>
> **What you'll use**: Sandboxes, External Attribution, Browser Tokens, Usage API

## What you'll build

An embedded sandbox experience inside your SaaS:

1. Your backend creates sandboxes tagged to the right customer.
2. Each tenant's usage is queryable for chargeback.
3. Your customer's browser gets a short-lived token to embed a live preview — no `msk_*` key anywhere client-side.

## Prerequisites

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- Node 22+ or Python 3.11+

## Step 1 — Install and configure

```bash
pip install miosa
export MIOSA_API_KEY="msk_live_..."
```

```bash
npm install @miosa/sdk
export MIOSA_API_KEY="msk_live_..."
```

## Step 2 — Tag every sandbox with your IDs

Pass `external_workspace_id`, `external_user_id`, and `external_project_id` on every `sandboxes.create` call. MIOSA stores these on the resource row and propagates them to every usage record, audit event, and derived resource (previews, deployments) automatically.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def create_sandbox_for_user(workspace_id: str, user_id: str, project_id: str):
    """Called from your request handler when a tenant starts a new sandbox."""
    sbx = client.sandboxes.create(
        template_id="miosa-sandbox",
        timeout_sec=3600,
        external_workspace_id=workspace_id,
        external_user_id=user_id,
        external_project_id=project_id,
    )
    return sbx

# Example: workspace "acme-corp", user "jane-doe", project "q3-dashboard"
sbx = create_sandbox_for_user("acme-corp", "jane-doe", "q3-dashboard")
print(f"Created sandbox {sbx.id} for acme-corp / jane-doe")
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

async function createSandboxForUser(
  workspaceId: string,
  userId: string,
  projectId: string,
) {
  const sbx = await client.sandboxes.create({
    templateId: 'miosa-sandbox',
    timeoutSec: 3600,
    externalWorkspaceId: workspaceId,
    externalUserId: userId,
    externalProjectId: projectId,
  });
  return sbx;
}

// Example
const sbx = await createSandboxForUser('acme-corp', 'jane-doe', 'q3-dashboard');
console.log(`Created sandbox ${sbx.id} for acme-corp / jane-doe`);
```

Use whatever ID format your platform already has — UUIDs, slugs, integer strings. MIOSA stores them as text and never validates the format beyond a 255-character length limit.

## Step 3 — List sandboxes per tenant

Filter the sandbox list by your own IDs to show a customer only their resources, or to enumerate all sandboxes for an account before billing.

```python
# All sandboxes for a workspace
acme_sandboxes = client.sandboxes.list(external_workspace_id="acme-corp")

for sbx in acme_sandboxes:
    print(f"  {sbx.id}  user={sbx.external_user_id}  status={sbx.status}")

# Narrow to a single user
jane_sandboxes = client.sandboxes.list(
    external_workspace_id="acme-corp",
    external_user_id="jane-doe",
)
```

```typescript
// All sandboxes for a workspace
const acmeSandboxes = await client.sandboxes.list({
  externalWorkspaceId: 'acme-corp',
});

for (const sbx of acmeSandboxes) {
  console.log(`  ${sbx.id}  user=${sbx.externalUserId}  status=${sbx.status}`);
}

// Narrow to a single user
const janeSandboxes = await client.sandboxes.list({
  externalWorkspaceId: 'acme-corp',
  externalUserId: 'jane-doe',
});
```

## Step 4 — Query usage per tenant

Pull a usage report grouped by `external_workspace_id` at the end of each billing period. Use this to generate invoices or display a cost dashboard inside your product.

```python
# Monthly rollup — grouped by workspace
usage = client.usage.report(
    period={"start": "2026-05-01", "end": "2026-06-01"},
    group_by=["external_workspace_id"],
)

for row in usage:
    print(f"  {row['external_workspace_id']}: ${row['total_usd']:.4f}")

# Drill into a single workspace by user
acme_by_user = client.usage.report(
    period={"start": "2026-05-01", "end": "2026-06-01"},
    external_workspace_id="acme-corp",
    group_by=["external_user_id"],
)

for row in acme_by_user:
    print(f"  user={row['external_user_id']}: ${row['total_usd']:.4f}")
```

```typescript
// Monthly rollup — grouped by workspace
const usage = await client.usage.report({
  period: { start: '2026-05-01', end: '2026-06-01' },
  groupBy: ['external_workspace_id'],
});

for (const row of usage) {
  console.log(`  ${row.externalWorkspaceId}: $${row.totalUsd.toFixed(4)}`);
}

// Drill into a single workspace by user
const acmeByUser = await client.usage.report({
  period: { start: '2026-05-01', end: '2026-06-01' },
  externalWorkspaceId: 'acme-corp',
  groupBy: ['external_user_id'],
});

for (const row of acmeByUser) {
  console.log(`  user=${row.externalUserId}: $${row.totalUsd.toFixed(4)}`);
}
```

## Step 5 — Issue browser tokens for direct access

Your customer's browser needs to embed a live preview. You cannot put `msk_*` in the frontend. Instead, your backend mints a short-lived share token and returns it to the client.

**Backend — mint the token:**

```python
from fastapi import FastAPI, Depends, HTTPException
from miosa import Miosa

app = FastAPI()
client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def get_current_user(request) -> dict:
    # Your existing auth logic — returns { workspace_id, user_id }
    ...

@app.get("/api/sandboxes/{sandbox_id}/preview-token")
async def get_preview_token(sandbox_id: str, user=Depends(get_current_user)):
    # Verify the sandbox belongs to this user's workspace
    sbx = client.sandboxes.get(sandbox_id)
    if sbx.external_workspace_id != user["workspace_id"]:
        raise HTTPException(403, "Forbidden")

    # Ensure a preview is running
    previews = client.sandboxes.previews.list(sandbox_id)
    if not previews:
        preview = client.sandboxes.previews.create(sandbox_id, port=3000)
    else:
        preview = previews[0]

    # Mint a 1-hour share token
    share = client.sandboxes.previews.share(
        sandbox_id,
        preview.id,
        expires_in_sec=3600,
    )

    return {"share_url": share.share_url, "expires_at": share.data["share_token_expires_at"]}
```

```typescript

const app = express();
const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

// Assumes req.user is populated by your auth middleware
app.get('/api/sandboxes/:sandboxId/preview-token', async (req, res) => {
  const { sandboxId } = req.params;
  const { workspaceId } = (req as any).user;

  // Ownership check
  const sbx = await client.sandboxes.get(sandboxId);
  if (sbx.externalWorkspaceId !== workspaceId) {
    res.status(403).json({ error: 'Forbidden' });
    return;
  }

  // Ensure a preview exists
  const previews = await client.sandboxes.previews.list(sandboxId);
  const preview =
    previews.length > 0
      ? previews[0]
      : await client.sandboxes.previews.create(sandboxId, { port: 3000 });

  // Mint a 1-hour share token
  const share = await client.sandboxes.previews.share(sandboxId, preview.id, {
    expiresInSec: 3600,
  });

  res.json({ shareUrl: share.shareUrl, expiresAt: share.data.shareTokenExpiresAt });
});
```

**Frontend — embed the preview:**

```html
<!-- Fetch the token from your backend, then embed the iframe -->

<iframe
  id="preview-frame"
  sandbox="allow-same-origin allow-scripts allow-forms"
  style="width: 100%; height: 600px; border: 0;"
></iframe>
```

Never put `msk_*` in a `<script>` tag, environment variable exposed to the browser, or localStorage. The share token is the only credential that should reach the browser, and it grants access to exactly one preview for one hour.

## Step 6 — Full integration wiring

Here is the complete server-side flow for a new-user onboarding request:

```python
from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def onboard_new_project(workspace_id: str, user_id: str, project_id: str) -> dict:
    """Called when a customer creates a new project in your SaaS."""

    # 1. Boot a tagged sandbox
    sbx = client.sandboxes.create(
        template_id="miosa-sandbox",
        timeout_sec=3600,
        external_workspace_id=workspace_id,
        external_user_id=user_id,
        external_project_id=project_id,
    )

    # 2. Write an initial project scaffold
    sbx.files.write(
        "/workspace/README.md",
        f"# Project: {project_id}\nWorkspace: {workspace_id}\n",
    )

    # 3. Start the dev server
    sbx.exec("python3 -m http.server 3000", cwd="/workspace", background=True)

    # 4. Create a preview
    preview = client.sandboxes.previews.create(sbx.id, port=3000)

    # 5. Mint a browser token
    share = client.sandboxes.previews.share(sbx.id, preview.id, expires_in_sec=3600)

    return {
        "sandbox_id": sbx.id,
        "preview_share_url": share.share_url,
        "expires_at": share.data["share_token_expires_at"],
    }
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

async function onboardNewProject(
  workspaceId: string,
  userId: string,
  projectId: string,
): Promise<{ sandboxId: string; previewShareUrl: string; expiresAt: string }> {
  // 1. Boot a tagged sandbox
  const sbx = await client.sandboxes.create({
    templateId: 'miosa-sandbox',
    timeoutSec: 3600,
    externalWorkspaceId: workspaceId,
    externalUserId: userId,
    externalProjectId: projectId,
  });

  // 2. Write an initial scaffold
  await sbx.files.write(
    '/workspace/README.md',
    `# Project: ${projectId}\nWorkspace: ${workspaceId}\n`,
  );

  // 3. Start dev server (detached)
  await sbx.exec('python3 -m http.server 3000', { cwd: '/workspace', background: true });

  // 4. Create a preview
  const preview = await client.sandboxes.previews.create(sbx.id, { port: 3000 });

  // 5. Mint a browser token
  const share = await client.sandboxes.previews.share(sbx.id, preview.id, {
    expiresInSec: 3600,
  });

  return {
    sandboxId: sbx.id,
    previewShareUrl: share.shareUrl,
    expiresAt: share.data.shareTokenExpiresAt,
  };
}
```

## What you learned

- Three external ID fields (`external_workspace_id`, `external_user_id`, `external_project_id`) let you group every MIOSA resource by your own identifiers without any server-side MIOSA configuration.
- Usage reports group by the same IDs — direct input to your chargeback logic.
- Share tokens are resource-scoped, expirable, and the only credentials that should reach a browser. The `msk_*` key stays on the backend at all times.
- Attribution is inherited: a deployment published from a tagged sandbox carries the same external IDs automatically.

## Next


    Full reference for the three external ID fields, filtering, inheritance rules, and storage.


    Token formats, lifetimes, revocation, and CSP embedding configuration.


    Usage record schema, chargeback rollup queries, and the billing API.

---

# Snapshot & fork

URL: https://miosa.ai/docs/cookbook/snapshot-and-fork
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/snapshot-and-fork
Source: src/routes/docs/cookbook/snapshot-and-fork/+page.md
Description: Checkpoint a long-running task, fork into multiple branches to compare outcomes, and restore to a known-good state on failure.

# Snapshot & fork

~10 min Python TypeScript

> **Goal**: Use snapshots to checkpoint a sandbox at a stable state, fork into N independent branches to run experiments in parallel, then restore from the checkpoint if any branch produces a bad outcome.
>
> **What you'll use**: Sandboxes, Snapshots

## What you'll build

A reusable fork-and-compare pattern:

```
sandbox (baseline built) → snapshot_A
      ├── restore → branch-1 (try approach X) → compare
      ├── restore → branch-2 (try approach Y) → compare
      └── restore → branch-3 (try approach Z) → compare
                                                     └── pick winner, destroy losers
```

The same pattern applies to: A/B testing AI agent strategies, running parallel database migrations, comparing LLM prompt variants, and safe-guarding long operations behind a checkpoint.

## Prerequisites

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- Node 22+ or Python 3.11+

## Step 1 — Install and configure

```bash
pip install miosa
export MIOSA_API_KEY="msk_live_..."
```

```bash
npm install @miosa/sdk
export MIOSA_API_KEY="msk_live_..."
```

## Step 2 — Build a baseline and checkpoint it

Run all the expensive setup work once — dependency installs, model downloads, dataset loading — then snapshot the sandbox so every branch starts from the same state without repeating the cost.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Create a sandbox and run the common setup steps
sbx = client.sandboxes.create(template_id="miosa-sandbox", timeout_sec=1800)

print("Running common setup...")
sbx.exec("pip install pandas scikit-learn", cwd="/workspace")

# Write a shared dataset
sbx.files.write("/workspace/data.csv", "a,b,label\n1,2,0\n3,4,1\n5,6,0\n7,8,1\n")

build = sbx.exec(
    "python3 -c 'import pandas as pd; df = pd.read_csv(\"/workspace/data.csv\"); print(df.shape)'",
)
print(f"Dataset shape: {build.stdout.strip()}")

# Checkpoint — creates a snapshot without stopping the sandbox
snap_id = sbx.snapshot(comment="baseline-after-setup")

# Poll until ready
while True:
    snap = client.snapshots.get(sbx.id, snap_id)
    if snap.status == "ready":
        print(f"Checkpoint ready: {snap_id}")
        break
    if snap.status == "failed":
        raise RuntimeError(f"Snapshot failed: {snap.error}")
    time.sleep(2)
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

// Create a sandbox and run common setup
const sbx = await client.sandboxes.create({
  templateId: 'miosa-sandbox',
  timeoutSec: 1800,
});

console.log('Running common setup...');
await sbx.exec('pip install pandas scikit-learn', { cwd: '/workspace' });

await sbx.files.write(
  '/workspace/data.csv',
  'a,b,label\n1,2,0\n3,4,1\n5,6,0\n7,8,1\n',
);

const shape = await sbx.exec(
  'python3 -c \'import pandas as pd; df = pd.read_csv("/workspace/data.csv"); print(df.shape)\'',
);
console.log('Dataset shape:', shape.stdout.trim());

// Checkpoint
const snapId = await sbx.snapshot({ comment: 'baseline-after-setup' });

// Poll until ready
let snap = await client.snapshots.get(sbx.id, snapId);
while (snap.status !== 'ready') {
  if (snap.status === 'failed') throw new Error(`Snapshot failed: ${snap.error}`);
  await new Promise(r => setTimeout(r, 2000));
  snap = await client.snapshots.get(sbx.id, snapId);
}
console.log('Checkpoint ready:', snapId);
```

## Step 3 — Fork into branches

Restore the snapshot once per branch. Each restore creates an independent sandbox with the same filesystem and process state as the checkpoint — no shared memory, no interference.

```python
APPROACHES = [
    ("logistic-regression", "from sklearn.linear_model import LogisticRegression; model = LogisticRegression()"),
    ("decision-tree",       "from sklearn.tree import DecisionTreeClassifier; model = DecisionTreeClassifier()"),
    ("random-forest",       "from sklearn.ensemble import RandomForestClassifier; model = RandomForestClassifier()"),
]

branches = {}

for name, model_code in APPROACHES:
    # Each restore returns a new independent sandbox
    branch = client.snapshots.restore(sbx.id, snap_id)
    branches[name] = branch
    print(f"Branch '{name}' starting: {branch.id}")

# Wait for all branches to finish provisioning
for name, branch in branches.items():
    while branch.status == "provisioning":
        time.sleep(1)
        branch = client.sandboxes.get(branch.id)
        branches[name] = branch
    print(f"Branch '{name}' running: {branch.id}")
```

```typescript
const approaches = [
  {
    name: 'logistic-regression',
    code: 'from sklearn.linear_model import LogisticRegression; model = LogisticRegression()',
  },
  {
    name: 'decision-tree',
    code: 'from sklearn.tree import DecisionTreeClassifier; model = DecisionTreeClassifier()',
  },
  {
    name: 'random-forest',
    code: 'from sklearn.ensemble import RandomForestClassifier; model = RandomForestClassifier()',
  },
];

// Restore N branches in parallel
const branches = await Promise.all(
  approaches.map(async ({ name, code }) => {
    const branch = await client.snapshots.restore(sbx.id, snapId);
    console.log(`Branch '${name}' starting: ${branch.id}`);
    return { name, code, branch };
  }),
);

// Wait for all to finish provisioning
const running = await Promise.all(
  branches.map(async ({ name, code, branch }) => {
    let b = branch;
    while (b.status === 'provisioning') {
      await new Promise(r => setTimeout(r, 1000));
      b = await client.sandboxes.get(b.id);
    }
    console.log(`Branch '${name}' running: ${b.id}`);
    return { name, code, branch: b };
  }),
);
```

## Step 4 — Run each branch and collect results

Execute the experiment on each branch independently and capture the outcome metric.

```python
TRAIN_SCRIPT = """\

from sklearn.model_selection import cross_val_score

{model_code}
df = pd.read_csv("/workspace/data.csv")
X, y = df[["a","b"]], df["label"]
scores = cross_val_score(model, X, y, cv=2)
print(json.dumps({{"mean_accuracy": float(scores.mean()), "std": float(scores.std())}}))
"""

results = {}

for name, branch in branches.items():
    _, model_code = next(a for a in APPROACHES if a[0] == name)
    script = TRAIN_SCRIPT.format(model_code=model_code)
    branch.files.write("/workspace/train.py", script)

    result = branch.exec("python3 /workspace/train.py")
    if result.exit_code == 0:

        metrics = json.loads(result.stdout.strip())
        results[name] = metrics
        print(f"  {name}: accuracy={metrics['mean_accuracy']:.3f} ± {metrics['std']:.3f}")
    else:
        results[name] = {"error": result.stderr}
        print(f"  {name}: FAILED — {result.stderr[:120]}")
```

```typescript
const trainScript = (modelCode: string) => `

from sklearn.model_selection import cross_val_score

${modelCode}
df = pd.read_csv("/workspace/data.csv")
X, y = df[["a","b"]], df["label"]
scores = cross_val_score(model, X, y, cv=2)
print(json.dumps({"mean_accuracy": float(scores.mean()), "std": float(scores.std())}))
`;

const results = await Promise.all(
  running.map(async ({ name, code, branch }) => {
    await branch.files.write('/workspace/train.py', trainScript(code));
    const result = await branch.exec('python3 /workspace/train.py');

    if (result.exitCode === 0) {
      const metrics = JSON.parse(result.stdout.trim());
      console.log(`  ${name}: accuracy=${metrics.mean_accuracy.toFixed(3)} ± ${metrics.std.toFixed(3)}`);
      return { name, metrics, branch };
    } else {
      console.log(`  ${name}: FAILED — ${result.stderr.substring(0, 120)}`);
      return { name, metrics: null, branch };
    }
  }),
);
```

## Step 5 — Pick the winner and clean up

Compare outcomes, keep the best branch, and destroy the rest. If every branch failed, restore from the checkpoint and try a different strategy.

```python
# Find the best outcome
successful = {
    name: data for name, data in results.items()
    if "error" not in data
}

if not successful:
    print("All branches failed — restoring from checkpoint for retry.")
    recovery = client.snapshots.restore(sbx.id, snap_id)
    # Inspect recovery sandbox, adjust strategy, re-run...
else:
    winner_name = max(successful, key=lambda n: successful[n]["mean_accuracy"])
    print(f"\nWinner: {winner_name} (accuracy={successful[winner_name]['mean_accuracy']:.3f})")

    # Destroy losing branches
    for name, branch in branches.items():
        if name != winner_name:
            branch.delete()
            print(f"Destroyed branch: {name}")

    # Destroy the original baseline sandbox too (snapshot is the durable artifact)
    sbx.delete()
    print(f"Kept winner sandbox: {branches[winner_name].id}")
```

```typescript
const successful = results.filter(r => r.metrics !== null);

if (successful.length === 0) {
  console.log('All branches failed — restoring from checkpoint for retry.');
  const recovery = await client.snapshots.restore(sbx.id, snapId);
  // Inspect recovery sandbox, adjust strategy, re-run...
} else {
  const winner = successful.reduce((best, r) =>
    r.metrics!.mean_accuracy > best.metrics!.mean_accuracy ? r : best,
  );
  console.log(`\nWinner: ${winner.name} (accuracy=${winner.metrics!.mean_accuracy.toFixed(3)})`);

  // Destroy losing branches
  await Promise.all(
    results
      .filter(r => r.name !== winner.name)
      .map(r => r.branch.delete()),
  );

  // Keep winner, destroy baseline
  await sbx.delete();
  console.log(`Kept winner sandbox: ${winner.branch.id}`);
}
```

## Restore to a known-good state on failure

If production goes wrong during a risky operation, restore from a pre-operation snapshot:

```python
def run_with_checkpoint(sbx, operation_fn):
    """Run a risky operation with automatic rollback on failure."""

    # Checkpoint before the operation
    snap_id = sbx.snapshot(comment="pre-operation-checkpoint")
    while True:
        snap = client.snapshots.get(sbx.id, snap_id)
        if snap.status == "ready":
            break
        if snap.status == "failed":
            raise RuntimeError("Failed to create checkpoint.")
        time.sleep(2)

    try:
        result = operation_fn(sbx)
        return result
    except Exception as exc:
        print(f"Operation failed: {exc}. Restoring from checkpoint...")
        recovery = client.snapshots.restore(sbx.id, snap_id)
        return {"error": str(exc), "recovery_sandbox_id": recovery.id}
```

```typescript
async function runWithCheckpoint(
  sbx: Sandbox,
  operationFn: (sbx: Sandbox) => Promise,
): Promise {
  // Checkpoint before the operation
  const snapId = await sbx.snapshot({ comment: 'pre-operation-checkpoint' });
  let snap = await client.snapshots.get(sbx.id, snapId);
  while (snap.status !== 'ready') {
    if (snap.status === 'failed') throw new Error('Failed to create checkpoint.');
    await new Promise(r => setTimeout(r, 2000));
    snap = await client.snapshots.get(sbx.id, snapId);
  }

  try {
    return await operationFn(sbx);
  } catch (err) {
    console.log(`Operation failed: ${err}. Restoring from checkpoint...`);
    const recovery = await client.snapshots.restore(sbx.id, snapId);
    return { error: String(err), recoverySandboxId: recovery.id };
  }
}
```

`snapshots.restore` always creates a new sandbox — the original sandbox is unchanged. This makes restore non-destructive: you can inspect the original, inspect the restored copy, and pick the one that looks healthy.

## Snapshot lifecycle

| State | Meaning |
|---|---|
| `creating` | Firecracker writing memory and filesystem state |
| `uploading` | Compressing and uploading to object storage |
| `ready` | Available for restore |
| `failed` | Unrecoverable error — inspect `snap.error` |
| `deleted` | Soft-deleted — object storage cleaned up asynchronously |

Snapshots persist until you explicitly delete them. They do not expire.

## What you learned

- `sbx.snapshot()` captures in-memory state without stopping the sandbox. The sandbox keeps running while the snapshot uploads.
- `client.snapshots.restore(sandbox_id, snap_id)` creates an independent sandbox from the checkpoint. N restores = N independent sandboxes.
- Parallel restores let you run experiments without the per-experiment setup cost.
- Snapshots are the rollback primitive: checkpoint before risk, restore on failure.

## Next


    Full endpoint reference, SSE progress events, and status state machine.


    Use snapshots mid-agent-loop to protect against runaway builds.


    Sandbox lifecycle, sizing, templates, and timeout behavior.

---

# Streaming code execution

URL: https://miosa.ai/docs/cookbook/streaming-code-execution
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/streaming-code-execution
Source: src/routes/docs/cookbook/streaming-code-execution/+page.md
Description: Run a long Python script in a sandbox and stream stdout to your UI in real time via SSE, with backpressure handling.

# Streaming code execution

~8 min Python TypeScript

> **Goal**: Run a long-running script inside a sandbox and stream every stdout line to your frontend UI in real time — no polling, no buffering the full output.
>
> **What you'll use**: Sandboxes, SSE events, exec streaming

## What you'll build

A minimal code-execution console: your backend creates a sandbox, runs a script, and pipes the sandbox SSE event stream back to the browser. The browser displays each line as it arrives. Looks like this in the terminal:

```
[00:01] Starting data pipeline...
[00:03] Loaded 50,000 rows
[00:05] Processing batch 1/10...
[00:09] Processing batch 2/10...
...
[01:12] Done. Output written to /workspace/output.csv
```

## Prerequisites

- A MIOSA workspace API key (`msk_live_*`) — see [API Keys](/docs/platform/api-keys/)
- Node 22+ or Python 3.11+

## Step 1 — Install and configure

```bash
pip install miosa
export MIOSA_API_KEY="msk_live_..."
```

```bash
npm install @miosa/sdk
export MIOSA_API_KEY="msk_live_..."
```

## Step 2 — Write a long-running script into the sandbox

Create a sandbox and write the script you want to execute. The script here simulates a ten-batch data pipeline with a sleep between batches.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

sbx = client.sandboxes.create(template_id="miosa-sandbox", timeout_sec=300)

script = """\

BATCHES = 10
print("Starting data pipeline...", flush=True)
time.sleep(1)

for i in range(1, BATCHES + 1):
    print(f"Processing batch {i}/{BATCHES}...", flush=True)
    # simulate work
    time.sleep(0.8)

print("Done. Output written to /workspace/output.csv", flush=True)
"""

sbx.files.write("/workspace/pipeline.py", script)
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const sbx = await client.sandboxes.create({
  templateId: 'miosa-sandbox',
  timeoutSec: 300,
});

const script = `

BATCHES = 10
print("Starting data pipeline...", flush=True)
time.sleep(1)

for i in range(1, BATCHES + 1):
    print(f"Processing batch {i}/{BATCHES}...", flush=True)
    time.sleep(0.8)

print("Done. Output written to /workspace/output.csv", flush=True)
`;

await sbx.files.write('/workspace/pipeline.py', script);
```

## Step 3 — Stream exec output

Use `exec` with `stream=True` (Python) or the async iterable exec API (TypeScript) to receive lines as they arrive rather than waiting for the process to exit.

```python

def ts() -> str:
    return datetime.datetime.now().strftime("%M:%S")

# stream=True yields ExecEvent objects as lines arrive
for event in sbx.exec("python3 /workspace/pipeline.py", stream=True):
    if event.type == "stdout":
        print(f"[{ts()}] {event.line}")
    elif event.type == "stderr":
        print(f"[{ts()}] ERR: {event.line}", file=sys.stderr)
    elif event.type == "exit":
        print(f"Process exited with code {event.exit_code}")
        break
```

```typescript
const now = () => new Date().toISOString().substring(14, 19);

// execStream returns an async iterable of exec events
for await (const event of sbx.execStream('python3 /workspace/pipeline.py')) {
  if (event.type === 'stdout') {
    process.stdout.write(`[${now()}] ${event.line}\n`);
  } else if (event.type === 'stderr') {
    process.stderr.write(`[${now()}] ERR: ${event.line}\n`);
  } else if (event.type === 'exit') {
    console.log(`Process exited with code ${event.exitCode}`);
    break;
  }
}
```

## Step 4 — Forward the stream to a browser via SSE

In a real application your backend runs the sandbox exec and forwards each line to the browser over an HTTP SSE response. Below is the pattern for both a Python ASGI server (FastAPI) and a Node HTTP handler.

```python
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from miosa import Miosa

app = FastAPI()
client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

@app.post("/run")
async def run_script(body: dict):
    """
    Accepts { "script": "..." } in the request body.
    Returns an SSE stream of execution events.
    """
    sbx = client.sandboxes.create(template_id="miosa-sandbox", timeout_sec=120)
    sbx.files.write("/workspace/script.py", body["script"])

    def event_generator():
        try:
            for event in sbx.exec("python3 /workspace/script.py", stream=True):
                if event.type == "stdout":
                    payload = json.dumps({"type": "stdout", "line": event.line})
                    yield f"data: {payload}\n\n"
                elif event.type == "stderr":
                    payload = json.dumps({"type": "stderr", "line": event.line})
                    yield f"data: {payload}\n\n"
                elif event.type == "exit":
                    payload = json.dumps({"type": "exit", "code": event.exit_code})
                    yield f"data: {payload}\n\n"
                    break
        finally:
            sbx.delete()

    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",  # disable nginx buffering
        },
    )
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const server = http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/run') {
    res.writeHead(404).end();
    return;
  }

  // Read request body
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  const { script } = JSON.parse(Buffer.concat(chunks).toString());

  // SSE headers — must be set before any write
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'X-Accel-Buffering': 'no',
    Connection: 'keep-alive',
  });

  const sbx = await client.sandboxes.create({
    templateId: 'miosa-sandbox',
    timeoutSec: 120,
  });

  try {
    await sbx.files.write('/workspace/script.py', script);

    for await (const event of sbx.execStream('python3 /workspace/script.py')) {
      const payload = JSON.stringify(event);
      res.write(`data: ${payload}\n\n`);

      if (event.type === 'exit') break;
    }
  } finally {
    res.end();
    await sbx.delete();
  }
});

server.listen(3000, () => console.log('Listening on http://localhost:3000'));
```

Set `X-Accel-Buffering: no` when running behind nginx. Without it, nginx buffers the SSE response and the browser receives events in chunks rather than one by one.

## Step 5 — Consume in the browser

A minimal browser snippet that connects to the SSE endpoint and appends each line to a `<pre>` element:

```html
<!doctype html>
<html>
  <body>
    <button id="run">Run pipeline</button>
    <pre id="output" style="background:#111;color:#0f0;padding:1rem;min-height:200px"></pre>

  </body>
</html>
```

`EventSource` only supports GET requests. If you need to pass a script body, use a two-step flow: POST `/run` to create a job and get back a `job_id`, then `GET /run/:job_id/stream` over EventSource.

## Backpressure

The MIOSA SSE stream pushes events as they arrive. If your client (browser tab, UI component) is slow, the network layer buffers them. For most exec workloads this is fine.

For very high-throughput scripts (millions of log lines), apply backpressure explicitly:

```python

# Rate-limit to 200 lines/sec to avoid overwhelming a browser client
MAX_LINES_PER_SEC = 200
bucket = MAX_LINES_PER_SEC

for event in sbx.exec("python3 /workspace/heavy.py", stream=True):
    if event.type == "stdout":
        if bucket <= 0:
            # Drop or summarize — never block the generator
            continue
        bucket -= 1
        yield f"data: {json.dumps({'line': event.line})}\n\n"
    elif event.type == "exit":
        break
```

```typescript
let bucket = 200; // refill every second
const refill = setInterval(() => { bucket = 200; }, 1000);

try {
  for await (const event of sbx.execStream('python3 /workspace/heavy.py')) {
    if (event.type === 'stdout') {
      if (bucket > 0) {
        bucket--;
        res.write(`data: ${JSON.stringify({ line: event.line })}\n\n`);
      }
      // else: drop the line — client is keeping up with summaries
    } else if (event.type === 'exit') {
      break;
    }
  }
} finally {
  clearInterval(refill);
}
```

## What you learned

- `exec` with streaming yields events as the process runs — no waiting for exit.
- `stdout`, `stderr`, and `exit` are the three event types to handle.
- SSE responses need `X-Accel-Buffering: no` behind nginx to avoid buffering.
- For high-throughput output, a token-bucket rate limiter protects the browser client.

## Next


    Wire a streaming exec into an LLM agent loop that self-corrects on build errors.


    Full catalog of exec, sandbox lifecycle, and deployment event types.


    Complete reference for exec options, working directories, environment variables, and timeouts.

---

# Auth-as-a-Service

URL: https://miosa.ai/docs/data/auth
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/auth
Source: src/routes/docs/data/auth/+page.md
Description: Per-project user signup, login, and JWT issuance. AUTH_URL and AUTH_JWT_SECRET injected at boot.

Per-project end-user authentication (signup, login, JWT verification, password reset, OAuth) is planned. This page documents the steady-state target. The backend strategy is being decided; the API surface here is what your generated apps will call when it ships.

Auth is the second piece of the MIOSA managed-data experience. When a project is created, MIOSA provisions a per-project auth service. The app gets two env vars:
```

AUTH_URL=https://auth.miosa.app/proj_xxx
AUTH_JWT_SECRET=<random 64-char hex>
```

The generated app uses them like this:
```typescript
// Sign up a new end user
const res = await fetch(`${process.env.AUTH_URL}/signup`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password }),
})
const { access_token, user } = await res.json()

// Verify a JWT in the app's own API

const claims = jwt.verify(token, process.env.AUTH_JWT_SECRET!)
const userId = claims.sub
```

That's the agent-on-day-zero experience: agent writes a signup flow on day zero, never has to ask the user to configure auth.

## What's offered

| Feature | Status |
|---|---|
| Email + password signup / login | Planned |
| Magic links | Planned |
| OAuth providers (Google, GitHub) | Planned |
| Password reset | Planned |
| Email verification | Planned |
| JWT access + refresh tokens | Planned |
| MFA / TOTP | Coming soon |
| Passkeys / WebAuthn | Coming soon |
| Enterprise SSO (SAML, OIDC) | Coming soon |

## Endpoints
```http
POST   {AUTH_URL}/signup
POST   {AUTH_URL}/token         (login)
POST   {AUTH_URL}/refresh
POST   {AUTH_URL}/logout
POST   {AUTH_URL}/reset
GET    {AUTH_URL}/user          (current user, requires Bearer)
PATCH  {AUTH_URL}/user
```

## End users are not MIOSA users

Important distinction:

- **MIOSA platform user** = the developer / platform builder. Authenticates with `msk_*` API keys or JWT sessions issued by MIOSA. Has access to the MIOSA dashboard.
- **End user of a generated app** = the visitor to an app YOUR PLATFORM built (e.g. Dr. Smith logging into a dental clinic site). Authenticates against the per-project `AUTH_URL`. Has no MIOSA account.

These are completely separate auth systems. The same email can be a MIOSA platform user AND an end user of someone's app; they're different records, with different password hashes.

## Per-project isolation

Each project gets its own user table. Users from `proj_smile_dental` cannot log into `proj_smile_clinic`. The JWT secret is per-project; you cannot use one project's token to authenticate against another.

This makes the "user signs up to the dental clinic site" pattern safe even when the same MIOSA tenant hosts thousands of independent end-user apps.

## Row-level security (Postgres pattern)

When combined with managed [Postgres](/docs/data/postgres/), the auth JWT carries the user ID (`sub` claim). Your runtime code uses it for row-level filtering:
```typescript
const claims = jwt.verify(token, process.env.AUTH_JWT_SECRET!)

const appointments = await pool.query(
  "SELECT * FROM appointments WHERE patient_id = $1",
  [claims.sub]
)
```

Or use Postgres RLS policies if your Postgres has them enabled:
```sql
ALTER TABLE appointments ENABLE ROW LEVEL SECURITY;
CREATE POLICY appointment_owner ON appointments
  USING (patient_id = current_setting('jwt.claims.sub')::uuid);
```

## Custom domains for auth

If you want the auth URLs to be branded (`auth.smiledental.test` instead of `auth.miosa.app`), add a custom domain to the project's auth service. Same flow as [Deployment Domains](/docs/deploy/domains/), different target.

## Bring your own auth?

Yes. Skip the managed auth, set your own `AUTH_URL` and `AUTH_JWT_SECRET` to point at Clerk / Auth0 / your own service. MIOSA's runtime injects whatever you set.

## Python SDK

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Get current project-auth status and config
status = miosa.project_auth.status()
print(status)  # {"enabled": false, ...}

# Enable project auth (with optional config kwargs)
miosa.project_auth.enable(
    allow_signups=True,
    providers=["email"],
)

# Update config after enabling
miosa.project_auth.update(allow_signups=False)

# Disable when no longer needed
miosa.project_auth.disable()
```

## See also

- [Overview](/docs/data/overview/) — the broader data plane
- [Postgres](/docs/data/postgres/) — pairs naturally with auth for RLS
- [Platform / Browser Tokens](/docs/platform/browser-tokens/) — for MIOSA-level browser access; distinct from your app's end-user auth

---

# Data

URL: https://miosa.ai/docs/data/overview
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/overview
Source: src/routes/docs/data/overview/+page.md
Description: Managed Postgres, Redis, object storage, auth, and volumes — provisioned per project, injected as env vars.

MIOSA Data services give your sandboxes and production runtime instances access to persistent storage without any external account setup. When you attach a data service to a project, MIOSA provisions the resource and injects its credentials at boot — your code reads `process.env.DATABASE_URL` and connects. That is the entire integration.

## Phase status

Data services are rolling out across several platform phases:

| Service | Status |
|---|---|
| Managed Postgres | Beta — API available, full env-var injection being wired |
| Object Storage | Beta |
| Managed Redis | Beta |
| Auth (per-project user auth) | Planned |
| Volumes (block storage) | Planned |

Templates for Postgres and Redis work today. The "credentials just appear" MIOSA managed-data experience is being completed. Per-page callouts indicate what is live.

## Mental model

Each service fills a different role. Pick the right one for your data shape:

| Service | Use when you need | Persistence |
|---|---|---|
| **Postgres** | Relational data, joins, transactions, migrations | Durable — survives deploys and sandbox destruction |
| **Storage** | File uploads, generated assets, binary blobs | Durable — content-addressed object store |
| **Redis** | Cache, sessions, pub/sub, rate limiting | Durable (AOF/RDB) but treated as cache-class |
| **Auth** | Per-project user signup, login, and JWT issuance | Durable — user records outlive any VM |
| **Volumes** | Large or fast filesystem state that does not fit in Postgres | Attached to one runtime instance at a time |

## Data persists past your VMs

Sandboxes are ephemeral. Runtime instances are ephemeral. Data is not.

Destroying a sandbox removes the VM — the connected Postgres database is untouched. Publishing a new version does not migrate your schema. Rolling back a deployment does not roll back your database. Data services are managed independently of the compute that connects to them.

This is intentional. It is also why production stays available during deploys: the new version connects to the same database the old version was using.

## How credentials are injected

MIOSA injects different credentials based on the environment the runtime instance boots into:
```

production runtime  →  DATABASE_URL = postgres://prod-db...
staging runtime     →  DATABASE_URL = postgres://staging-db...
```

You ship one environment variable name; MIOSA resolves the right value. See [Environments](/docs/deploy/environments/).

## Quick example

```python

from miosa import Miosa

miosa = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Create a managed Postgres database
db = miosa.databases.create(
    engine="postgres",
    engine_version="15",
    name="my-app-db",
)

print(db["id"])          # db_...
print(db["status"])      # provisioning | ready

# Fetch connection credentials once ready
creds = miosa.databases.credentials(db["id"])
print(creds["url"])      # postgresql://user:pass@host:5432/dbname
```

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

// Create a managed Postgres database
const db = await miosa.databases.create({
  engine: "postgres",
  engineVersion: "15",
  name: "my-app-db",
})

console.log(db.id)       // db_...
console.log(db.status)   // provisioning | ready

// Fetch connection credentials once ready
const creds = await miosa.databases.credentials(db.id)
console.log(creds.url)   // postgresql://user:pass@host:5432/dbname
```

```bash
# Create a managed Postgres database
curl -X POST https://api.miosa.ai/v1/databases \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"postgres","engine_version":"15","name":"my-app-db"}'

# Get credentials
curl https://api.miosa.ai/v1/databases/$DATABASE_ID/credentials \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

## How data services attach
Diagram:
graph TB
    DEP[Deployment / Sandbox]
    DEP -->|DATABASE_URL injected| PG[(Postgres)]
    DEP -->|REDIS_URL injected| RD[(Redis)]
    DEP -->|STORAGE_BUCKET + keys injected| ST[(Object Storage)]
    DEP -->|AUTH_URL + AUTH_JWT_SECRET injected| AU[Auth Service]

## How it fits together
```

Project
  ├── Sandbox (ephemeral compute)
  │     └── DATABASE_URL injected at boot ──────────────────┐
  │                                                          ▼
  └── Data Services (durable)                         Managed Postgres
        ├── Postgres  ←─────────────────────────────── same DB, always
        ├── Storage   ←── STORAGE_BUCKET env var
        ├── Redis     ←── REDIS_URL env var
        └── Auth      ←── AUTH_URL + AUTH_JWT_SECRET env vars
```

Your application code is unaware of the infrastructure. It reads standard environment variables, opens connections, and runs. MIOSA operates everything underneath.

## Next


    Managed Postgres per project. PgBouncer pooling, automated backups, and connection string injection.


    Object storage buckets per project. Signed-URL uploads and downloads — no MIOSA key in the browser.


    Managed Redis per project. Cache, session store, and pub/sub.


    Per-project user signup, login, and JWT. `AUTH_URL` and `AUTH_JWT_SECRET` injected at boot.


    Persistent block storage attached to a runtime instance. For state that does not fit in Postgres.

---

# Postgres

URL: https://miosa.ai/docs/data/postgres
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/postgres
Source: src/routes/docs/data/postgres/+page.md
Description: Managed Postgres per project. PgBouncer-pooled, automatically backed up, injected as DATABASE_URL.

Managed Postgres lifecycle (provision-per-project, PgBouncer routing, backup orchestration, env injection) is in active development. Today, sandboxes can have a linked database, and the `miosa-sandbox` template exists for self-managed sandbox-Postgres. This page documents the steady-state target. Treat the API examples as targets, not currently shipping endpoints unless stated.

## Provision

When a project is created with `data: { postgres: true }`, MIOSA provisions a logical database in a managed Postgres cluster, generates credentials, and injects them as env vars.

Diagram:
graph LR
    PC[Project create] -->|data.postgres=true| MP[MIOSA provisioner]
    MP --> PG[(Managed Postgres cluster)]
    PG -->|credentials generated| ENV[DATABASE_URL env var]
    ENV --> SB[Sandbox]
    ENV --> RI[Runtime Instance]

```typescript
const project = await miosa.projects.create({
  name: "Smile Dental",
  data: { postgres: true },
})

// Sandboxes and runtime instances under this project boot with:
// DATABASE_URL = postgresql://user:pass@host:port/proj_xxx
```

You can also add Postgres to an existing project:
```typescript
await miosa.projects.dataServices.create(projectId, {
  type: "postgres",
  size: "small",  // small | medium | large
})
```

## Connection pooling

MIOSA routes `DATABASE_URL` through PgBouncer in transaction-pooling mode by default. This means:

- Each runtime instance opens 5-10 connections to PgBouncer.
- PgBouncer multiplexes them over a much smaller pool of real Postgres connections.
- You can have 100s of runtime instances without exhausting Postgres's `max_connections`.

Transaction-pooling caveat: you can't use session-level features like `LISTEN`/`NOTIFY`, prepared statements, or `SET LOCAL`. If you need those, request a session-pooler URL via `DATABASE_URL_SESSION` (coming soon).

## Schema management is yours

MIOSA doesn't run migrations for you. The recommended workflow:

1. Use your framework's migration tool (Prisma, Drizzle, Ecto, Alembic, etc.).
### 2. Run migrations as part of your build / startup, or as a separate one-off via:

```typescript
await sandbox.exec({ cmd: "npx", args: ["prisma", "migrate", "deploy"] })
```

3. Make migrations backward-compatible (expand → migrate → contract). This keeps rollback working — see [Rollback](/docs/deploy/rollback/).

## Backups

MIOSA runs continuous WAL archiving plus daily base backups, both to durable replicated object storage. Retention defaults:

- Point-in-time recovery: 7 days
- Base backups: 30 days

Restore is a support request today; self-serve UI is coming soon.

## Sandboxed development with the same DB

When you create a sandbox under a project that has Postgres, the sandbox also gets `DATABASE_URL` — pointing at the same managed database. Two options:

1. **Shared dev DB.** Sandboxes and production both point at the production database. Fast iteration, risk of dev work affecting prod data.
2. **Per-environment DB.** Production gets one DB, staging/dev get another. Configured via [Environments](/docs/deploy/environments/).

Default is (2) once per-environment isolation lands. Until then, sandboxes share the production DB; use schema namespacing or be careful with destructive queries.

## Connecting from a sandbox
```typescript
await sandbox.exec({
  cmd: "psql",
  args: [process.env.DATABASE_URL, "-c", "SELECT 1"],
})
```

The sandbox's `DATABASE_URL` is the same shape the runtime would see in production. Whatever code works in the sandbox works in the deployment.

## Limits

| Tier | Storage | Connections (PgBouncer) | Memory |
|---|---|---|---|
| small | 1 GB | 100 | 512 MB |
| medium | 10 GB | 200 | 2 GB |
| large | 100 GB | 500 | 8 GB |

Storage scales automatically. Connection limits and memory are tunable per plan.

## Costs

Postgres pricing is in two parts:

- **Compute** — per-hour while the DB is running (always-on by default for production; can be paused for sandboxed dev DBs).
- **Storage** — GB-month for data plus WAL.

See [Usage & Billing](/docs/platform/usage-and-billing/). Per-database metering carries [attribution](/docs/platform/attribution/), so platforms can charge back per end-customer.

## Bring your own Postgres?

If you'd rather use an external Postgres, just set `DATABASE_URL` as an env var on the deployment and skip the managed offering:
```typescript
await miosa.deployments.env.set(deploymentId, {
  environment: "production",
  vars: { DATABASE_URL: "postgresql://...your-external-db..." },
})
```

MIOSA's runtime injects whatever you set. The managed Postgres is convenience; bringing your own is supported.

## Python SDK

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Provision a managed database
db = miosa.databases.create(
    name="smile-dental-db",
    engine="postgres",
    size="small",
)
print(db["id"])  # db_...

# Get connection credentials
creds = miosa.databases.credentials(db["id"])
print(creds["url"])  # postgresql://user:pass@host:port/dbname

# Lifecycle operations
miosa.databases.stop(db["id"])
miosa.databases.start(db["id"])
miosa.databases.restart(db["id"])

# Stream logs (returns a generator of SSE events)
for event in miosa.databases.stream_logs(db["id"]):
    print(event)

# Teardown
miosa.databases.delete(db["id"])
```

## See also

- [Overview](/docs/data/overview/) — the broader data plane
- [Environments](/docs/deploy/environments/) — per-env credentials
- [Rollback](/docs/deploy/rollback/) — why backward-compatible migrations matter

---

# Redis / Cache

URL: https://miosa.ai/docs/data/redis
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/redis
Source: src/routes/docs/data/redis/+page.md
Description: Managed Redis per project for caching, sessions, and pub/sub.

Managed Redis lifecycle is in active development. The `miosa-sandbox` template exists for sandbox-Redis today; project-level managed Redis with per-environment credentials is being wired.

## What you get

Per project: a managed Redis instance, with credentials injected as `REDIS_URL`:
```

REDIS_URL=redis://default:pass@host:port/0
```

Standard Redis clients work without modification:
```typescript

const redis = createClient({ url: process.env.REDIS_URL })
await redis.connect()

await redis.set("user:123:last-seen", new Date().toISOString())
const value = await redis.get("user:123:last-seen")
```

## Use cases

- **Cache** — short-lived computed results.
- **Sessions** — express-session / Phoenix sessions / similar.
- **Pub/sub** — agent coordination, real-time fan-out.
- **Rate limiting** — atomic INCR + TTL.
- **Job queues** — Bull, BullMQ, Sidekiq, Oban-light alternatives.

For full job-queue workloads at scale, MIOSA has a [Background Jobs](/docs/deploy/runtime-instances/) primitive that's a better fit than rolling your own on Redis.

## Provision
```typescript
await miosa.projects.dataServices.create(projectId, {
  type: "redis",
  size: "small",  // small | medium | large
})
```

## Limits

| Tier | Memory | Connections | Persistence |
|---|---|---|---|
| small | 256 MB | 1000 | None (cache only) |
| medium | 2 GB | 5000 | RDB snapshots, 24h |
| large | 8 GB | 10000 | RDB + AOF |

The `small` tier treats Redis as ephemeral — appropriate for cache, not for sessions you want to survive a restart. Bump to `medium` for session storage.

## Pub/sub considerations

If you're using Redis pub/sub for cross-runtime coordination, multiple runtime instances of the same service can all subscribe — MIOSA does not deduplicate or proxy pub/sub. For higher-volume real-time fan-out, consider SSE through MIOSA's [Events](/docs/api-reference/events/) or a dedicated message broker.

## Bring your own Redis?

Yes. Set `REDIS_URL` as an env var to whatever external Redis you prefer (Upstash, AWS ElastiCache, your own).

## See also

- [Overview](/docs/data/overview/) — the broader data plane
- [Runtime Instances](/docs/deploy/runtime-instances/) — for background-job workloads

---

# Storage / Buckets

URL: https://miosa.ai/docs/data/storage
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/storage
Source: src/routes/docs/data/storage/+page.md
Description: Per-project object storage with signed-URL uploads and downloads.

Managed bucket lifecycle (provision-per-project, signed-URL endpoints, attribution-aware metering) is in active development. MIOSA uses object storage internally for deployment artifacts and snapshots; customer-facing bucket APIs are being wired.

## What you get

Per project: an S3-compatible bucket, accessed through MIOSA endpoints. Credentials injected as env vars:
```

STORAGE_BUCKET=miosa-proj_xxx-uploads
STORAGE_ENDPOINT=https://storage.miosa.app
STORAGE_KEY_ID=...
STORAGE_KEY_SECRET=...
```

Your code uses the standard S3 client libraries:
```typescript

const s3 = new S3Client({
  endpoint: process.env.STORAGE_ENDPOINT,
  credentials: {
    accessKeyId: process.env.STORAGE_KEY_ID!,
    secretAccessKey: process.env.STORAGE_KEY_SECRET!,
  },
  region: "us-east-1",
})

await s3.send(new PutObjectCommand({
  Bucket: process.env.STORAGE_BUCKET,
  Key: "uploads/foo.png",
  Body: pngBuffer,
}))
```

## Signed URLs for browser uploads

Don't proxy file uploads through your runtime. Mint a signed URL server-side; the browser uploads directly to storage:
```typescript
// Server
const url = await miosa.storage.signedUrl({
  bucket: process.env.STORAGE_BUCKET!,
  key: `users/${userId}/avatar.png`,
  operation: "put",
  expiresInSec: 300,
  contentType: "image/png",
})
return { uploadUrl: url }
```
```typescript
// Browser
await fetch(uploadUrl, {
  method: "PUT",
  body: file,
  headers: { "Content-Type": "image/png" },
})
```

Same pattern for downloads (`operation: "get"`). Signed URLs are scoped (single key, single operation, short expiry) — no risk of leaking bucket-wide credentials to a browser.

## Public vs private

Each object can be private (default; access only via signed URL) or public (served from a `*.storage.miosa.app` URL). Public objects can also be fronted by a custom domain via your project's [Domain](/docs/deploy/domains/) settings.

## Bandwidth and storage costs

Two billable dimensions:

- **Storage** — GB-month for stored bytes.
- **Egress** — GB out from MIOSA to the public internet. Storage-to-runtime within MIOSA is free.

[Attribution](/docs/platform/attribution/) is carried on every event for chargeback.

## Limits

| Limit | Default | Tunable |
|---|---|---|
| Storage per project | 1 GB | Yes (plan-dependent) |
| Max object size | 5 GB | Up to 100 GB for multipart |
| List keys per call | 1000 | Standard S3 pagination |

## Sandboxes can use the bucket too

The same env vars are injected into sandboxes for dev / testing. Upload from inside a sandbox:
```typescript
await sandbox.exec({
  cmd: "aws",
  args: ["s3", "cp", "/workspace/build.tar.gz", `s3://${process.env.STORAGE_BUCKET}/builds/`],
  env: {
    AWS_ACCESS_KEY_ID: process.env.STORAGE_KEY_ID,
    AWS_SECRET_ACCESS_KEY: process.env.STORAGE_KEY_SECRET,
    AWS_ENDPOINT_URL: process.env.STORAGE_ENDPOINT,
  },
})
```

## Bring your own bucket?

Yes. Set the env vars to point at an external S3-compatible bucket (real AWS, Backblaze B2, R2, etc.). MIOSA injects whatever you set.

## Python SDK

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Create a bucket
bucket = miosa.storage.create_bucket("my-uploads", public=False)
bucket_id = bucket["id"]

# Upload bytes
with open("report.pdf", "rb") as f:
    miosa.storage.put_object(bucket_id, "reports/report.pdf", f.read(),
                             content_type="application/pdf")

# Mint a presigned URL for browser upload (PUT)
presigned = miosa.storage.presign(
    bucket_id,
    key="avatars/user-123.png",
    operation="put",
    expires_in_sec=300,
    content_type="image/png",
)
print(presigned["url"])

# Mint a presigned URL for browser download (GET)
download = miosa.storage.presign(
    bucket_id,
    key="reports/report.pdf",
    operation="get",
    expires_in_sec=3600,
)
print(download["url"])

# List objects with a prefix
objects = miosa.storage.list_objects(bucket_id, prefix="reports/")
for obj in objects:
    print(obj["key"], obj["size"])

# Delete a bucket
miosa.storage.delete_bucket(bucket_id)
```

## See also

- [Overview](/docs/data/overview/) — the broader data plane
- [Environments](/docs/deploy/environments/) — per-env bucket names

---

# Volumes

URL: https://miosa.ai/docs/data/volumes
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/data/volumes
Source: src/routes/docs/data/volumes/+page.md
Description: Persistent block storage attached to a runtime instance. State that doesn't fit in Postgres.

Volumes are planned. Most workloads should use [Postgres](/docs/data/postgres/) or [Storage](/docs/data/storage/) instead; volumes are for the narrow set of cases where neither fits.

A **Volume** is a persistent block device attached to a runtime instance. Survives instance restarts and version promotions. Useful for:

- SQLite databases that need to be local to the runtime.
- Caches you can't afford to lose on restart.
- LLM model weights downloaded once and shared across instances.
- Workloads that legitimately need filesystem state (not just key-value).

Volumes are NOT useful for:

- Stateful databases — use [Postgres](/docs/data/postgres/) instead. It scales better, backs up automatically, and survives host failures.
- User-uploaded files — use [Storage / Buckets](/docs/data/storage/). Cheaper, browser-uploadable, geo-replicable.
- Shared state across multiple replicas — volumes are typically attached to ONE runtime instance.

## Create

```typescript
await miosa.projects.dataServices.create(projectId, {
  type: "volume",
  name: "model-weights",
  sizeGb: 50,
})
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Create a 50 GB volume
vol = miosa.volumes.create(name="model-weights", size_gb=50)
print(vol["id"])  # vol_...

# List all volumes
for v in miosa.volumes.list():
    print(v["name"], v["size_gb"], "GB")

# Delete a volume
miosa.volumes.delete(vol["id"])
```

## Mount

A volume is mounted into the runtime instance's filesystem at a path:
```typescript
await miosa.services.update(serviceId, {
  volumes: [
    { dataServiceId: volumeId, mountPath: "/var/models" },
  ],
})
```

At boot, `/var/models` is the volume's contents. Writes persist.

## Replicas and volumes

Most volumes attach to a single runtime instance. If you scale a service to N replicas, by default each replica gets the **same volume mount** if it's marked `shared: true`, or its own volume if `shared: false`.

Shared volumes have all the usual concurrency caveats (filesystem locks, file-corruption risk if multiple writers touch the same file). Use Postgres for shared state unless you really know what you're doing.

## Snapshots and backups

Volumes can be snapshotted on a schedule. Snapshots are point-in-time, immutable, restorable. Configure via:
```typescript
await miosa.projects.dataServices.update(volumeId, {
  snapshot_schedule: "0 4 * * *",  // daily at 4am UTC
  snapshot_retention_days: 7,
})
```

## Limits

| Limit | Default |
|---|---|
| Max volume size | 500 GB |
| Max volumes per project | 10 |
| Filesystem | ext4 |
| Backup retention | per schedule, default 7 days |

## When to use a volume

Realistic short list:

1. You're shipping a self-hosted SQLite-backed app to keep deployment simple.
2. You're running an LLM inference service and don't want to re-download model weights on every instance start.
3. You have a writable filesystem cache that's expensive to rebuild.

Anything else, use Postgres or Storage.

## See also

- [Overview](/docs/data/overview/) — the broader data plane
- [Postgres](/docs/data/postgres/) — for relational data (almost always the right answer)
- [Storage](/docs/data/storage/) — for user-uploaded files

---

# Domains

URL: https://miosa.ai/docs/deploy/domains
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/domains
Source: src/routes/docs/deploy/domains/+page.md
Description: Managed *.miosa.app URLs and custom domains. DNS verification, automatic TLS, instant repointing.

A **Domain** is a hostname that routes to a deployment. MIOSA gives every deployment a managed URL by default, and lets you attach custom domains with automatic Let's Encrypt TLS.

## Managed URLs

Every deployment gets a managed hostname at creation:
```

<deployment-slug>.<organization-slug>.miosa.app
```

Example: `smile-dental.cliniciq.miosa.app`. TLS is provisioned automatically against the wildcard cert.

If you configure a preview base domain, managed deployment URLs inherit it:

| Scope | Example URL |
|---|---|
| Organization preview domain `cliniciq.dev` | `https://smile-dental.cliniciq.dev` |
| Workspace preview domain `drsmithclinic.com` | `https://smile-dental.drsmithclinic.com` |
| Project preview domain `program.drsmithclinic.com` | `https://smile-dental.program.drsmithclinic.com` |

Precedence is project → workspace → organization → MIOSA fallback. Exact deployment custom domains still take priority over these managed URLs.

You can rename the deployment slug if needed (subject to uniqueness in your workspace). Renaming retires the old hostname; existing TLS for the old name continues to serve until its current cert expires.

## Custom domains

Three flavors of custom domain:

| Kind | Example | DNS record |
|---|---|---|
| Subdomain | `app.smiledental.test` | `CNAME` to the verification target |
| Apex | `smiledental.test` | `A` records to MIOSA's anycast IPs, or `ALIAS`/`ANAME` if your DNS provider supports it |
| Wildcard | `*.smiledental.test` | More involved — see "Wildcards" below |

## The attach flow

```typescript
// 1. Register the domain. MIOSA returns DNS instructions.
const domain = await miosa.deployments.domains.add(deploymentId, {
  domain: "smiledental.test",
})
console.log(domain.dns_records)
// [
//   { type: "A",   name: "@",            value: "203.0.113.10",
//     purpose: "traffic" },
//   { type: "TXT", name: "_miosa-verify", value: "miosa-domain-...",
//     purpose: "verification" }
// ]

// 2. After you've set the records, ask MIOSA to verify.
await miosa.deployments.domains.verify(deploymentId, domain.id)

// 3. MIOSA issues a Let's Encrypt cert. Live within ~60s of verification.
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# 1. Register the domain. MIOSA returns DNS instructions.
domain = miosa.deployments.domains(deployment_id).add(domain="smiledental.test")
for rec in domain.get("dns_records", []):
    print(rec["type"], rec["name"], rec["value"])

# 2. After DNS records are set, trigger verification.
miosa.deployments.domains(deployment_id).verify(domain["id"])

# 3. TLS is issued automatically — live within ~60s of verification.

# List all domains on a deployment
domains = miosa.deployments.domains(deployment_id).list()

# Remove a domain
miosa.deployments.domains(deployment_id).remove(domain["id"])
```

```bash
# 1. Register
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{"domain":"smiledental.test"}'

# Response includes dns_records[].

# 2. After DNS is set, verify
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/domains/$DOM/verify \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Once verified and TLS-active, MIOSA routes the domain to the deployment's active version.

## Redirect policy

For apex + www domains, set the redirect policy:

| Policy | Result |
|---|---|
| `none` | Both apex and www serve independently (you'd need to add www separately) |
| `apex_to_www` | `smiledental.test` 301-redirects to `www.smiledental.test` |
| `www_to_apex` | `www.smiledental.test` 301-redirects to `smiledental.test` |

Configure at attach time or update later via `PATCH /deployments/:id/domains/:domain_id`.

## What changing a domain does (and doesn't) do

Changing a domain mapping:

- Updates a row in MIOSA's route table.
- Takes effect within seconds (the edge proxy caches the route table with a short TTL).
- Does **not** rebuild the app.
- Does **not** restart runtime instances.

This is why rollback is trivial: the runtime instances are already running the old version; only the route mapping changes.

## DNS verification edge cases

| Situation | Behavior |
|---|---|
| CNAME points to the wrong host | Verification fails with `dns_target_mismatch`. Show the user the expected target. |
| TXT record not propagated yet | Verification fails with `dns_propagation_pending`. Retry after a few minutes — DNS TTL applies. |
| User typos the domain | Verification fails with `dns_resolution_error`. Domain stays in `pending` state. |
| Domain already attached to another deployment in your tenant | 409 Conflict. Detach from the other deployment first. |
| Domain attached to a different tenant | 403 Forbidden. Each domain belongs to at most one tenant. Contact support for transfer. |

## Wildcards

Wildcards (`*.smiledental.test`) require DNS-01 challenges, which means MIOSA needs to update DNS records on your domain in real time during cert issuance. Two ways:

1. **Delegate the subdomain to MIOSA.** Set `NS` records on `smiledental.test` pointing at MIOSA's nameservers for the subdomain you want wildcarded.
2. **Bring your own DNS provider.** Some providers expose API access for ACME DNS-01 — MIOSA can integrate (currently Route53 and Cloudflare; more on request).

Wildcards are typically only needed for white-label platforms serving per-end-user subdomains. For single-app deployments, regular CNAME + cert is simpler.

## White-label managed URLs

If you're building a platform and want your customers to see branded preview / deployment URLs, set preview domains through the API:

```http
PUT /api/v1/tenant/preview-domain
PUT /api/v1/workspaces/{id}/preview-domain
PUT /api/v1/projects/{id}/preview-domain
```

Each preview base domain needs two wildcard CNAME records:

| Record type | Name | Value | Used for |
|---|---|---|---|
| `CNAME` | `*` | `proxy.miosa.ai` | Managed deployments, computers, and default previews |
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` | Port-qualified sandbox previews |

## Edge cache and the route table

The route table (domain → active_version_id) is cached at MIOSA's edge with a short TTL (default 60s). This is what makes the routing layer resilient: if MIOSA's control plane has a brief outage, the edge keeps serving the last known route table. Customers' production stays up.

Trade-off: changes take up to TTL seconds to propagate everywhere. For most workflows that's fine. Force-invalidate by hitting `POST /api/v1/deployments/:id/route-refresh` if you need an immediate update (this is rate-limited per tenant).

For DNS verification logic, redirect policy semantics, and TLS state machine details, the canonical spec is `miosa-compute/docs/deployments/domains-routing.md`. These docs follow that contract.

## See also

- [Versions](/docs/deploy/versions/) — what the domain points at
- [Rollback](/docs/deploy/rollback/) — repointing the domain at an older version
- [Environments](/docs/deploy/environments/) — production vs staging URLs

---

# Environments

URL: https://miosa.ai/docs/deploy/environments
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/environments
Source: src/routes/docs/deploy/environments/+page.md
Description: Production, staging, preview/<source> — variable and secret scoping for deployments.

A **Deployment Environment** is the scope at which env vars, secrets, and data service bindings apply. Most projects have at least two: `production` and `staging`. Custom environments like `preview/feature-abc` are common for review-app workflows.

First-class `deployment_environments` records are part of the ongoing deployment refactor. Today, env vars are scoped per-deployment via `deployment_env_vars`. The shape and behavior here are the steady-state target.

## Defaults

Every project gets two environments at creation:

- `production` — what real users see
- `staging` — internal testing target before promoting to production

You can create additional environments (`preview/&lt;source&gt;`, `qa`, `canary`, etc.) as needed.

## What environments scope

| Item | Scope |
|---|---|
| Env vars | per environment |
| Secrets | per environment |
| Data service bindings (DATABASE_URL, REDIS_URL, etc.) | per environment |
| Domains | per environment (production gets the apex; staging gets a `staging.*` subdomain by convention) |
| Version promotion | per environment — promote a version to staging first, then to production |

The same deployment can run different versions in different environments. Common pattern:
```

production:   version 17 active
staging:      version 18 active   ← being tested
preview/pr-42: version 19 active  ← single-feature preview
```

## Env vars
```http
POST /api/v1/deployments/:id/env
GET  /api/v1/deployments/:id/env
```

Env vars are stored encrypted at rest (ChaCha20-Poly1305) and injected into the sandbox during development and into runtime instances at boot. The list endpoint returns previews of values, not the raw values, by default.

```typescript
await miosa.deployments.env.set(deploymentId, {
  environment: "production",
  vars: {
    STRIPE_KEY: "sk_live_...",
    NEXT_PUBLIC_API_URL: "https://api.smiledental.test",
  },
})

const preview = await miosa.deployments.env.list(deploymentId, {
  environment: "production",
})
// preview returns: { STRIPE_KEY: "sk_live_••••", NEXT_PUBLIC_API_URL: "https://api…" }
```

```bash
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/env \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{
    "environment": "production",
    "vars": { "STRIPE_KEY": "sk_live_..." }
  }'
```

## Secrets vs env vars

There's no strict UI distinction today — env vars are encrypted at rest regardless. The convention is:

- **Env vars**: configuration that can be retrieved as preview (truncated value).
- **Secrets**: same encryption, but marked `is_secret: true` so previews always show `••••` even to your own admins.

Future-state, secrets will support rotation and access-event audit logging.

## Data service bindings

When you create a Postgres / Redis / bucket via [Data](/docs/data/overview/), you bind it to a specific deployment environment. MIOSA injects the credential into env at boot:
```

production env:    DATABASE_URL=postgres://prod...
staging env:       DATABASE_URL=postgres://staging...
```

You don't ship two database URLs for one app; you ship one connection string variable, and MIOSA picks the right value based on which environment the runtime is booted in.

## Where to go next

- [Publishing](/docs/deploy/publishing/) — environments are picked at publish time
- [Domains](/docs/deploy/domains/) — attach a staging subdomain
- [Data](/docs/data/overview/) — environment-scoped credentials

---

# Deploy

URL: https://miosa.ai/docs/deploy/overview
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/overview
Source: src/routes/docs/deploy/overview/+page.md
Description: Turn a sandbox into a stable production URL with immutable history and instant rollback.

Deploying on MIOSA means turning a Sandbox into a stable production URL backed by immutable build artifacts, versioned history, and instant rollback. Once published, the URL never changes — only which version it points at.

## The deployment pipeline

Every publish travels the same path:
Diagram:
graph LR
    A[Sandbox] -->|publish| B[Source Snapshot]
    B --> C[Builder VM]
    C -->|builds| D[Release]
    D -->|creates| E[Deployment Version]
    E -->|promotes| F[Runtime Instance or Edge]
    F --> G[Domain]

1. **Sandbox** — the mutable environment where you (or an agent) write code.
2. **Source Snapshot** — an immutable tarball of `/workspace` captured at publish time. The sandbox can keep changing; the snapshot is frozen.
3. **Builder VM** — a short-lived Firecracker microVM that runs `install` + `build` from the snapshot. It exits when the release is stored.
4. **Release** — the immutable build output. Static: a tarball. Dynamic: a rootfs/OCI image.
5. **Deployment Version** — the row in history. `version_number` increases monotonically. Every version is bootable forever.
6. **Runtime Instance** — for dynamic deployments, a Firecracker microVM booted from the release rootfs. Static releases skip this; MIOSA's edge serves the files directly.
7. **Domain** — the route. Managed (auto-TLS) or custom. Points at the active version. Rollback is re-pointing this route — no rebuild.

## Static vs Dynamic

| | Static | Dynamic |
|---|---|---|
| Source shape | HTML / JS / CSS / assets only | Server-side code (Node, Python, Phoenix, Go, etc.) |
| Build output | File tarball | Rootfs / OCI image |
| Production runtime | MIOSA shared edge — no per-app process | Runtime Instances on the compute fleet |
| Scaling | Instant (edge serves files) | Scheduler manages desired instance count |
| Rollback speed | Seconds (route re-point) | Seconds (route re-point to older release) |
| Cost | Lower | Per CPU/RAM/time |
| Best for | Landing pages, SPAs, generated HTML, docs | APIs, SSR, WebSockets, background workers |

Pass `kind: "auto"` (or `runtime_kind: "auto"` in Python) and MIOSA inspects the build output to decide. A `dist/` with no server entrypoint becomes static; a `Procfile` or detected `start` command becomes dynamic.

## The deployment object

A **Deployment** is the stable product object — the thing the world thinks of as "the live app." It has a name, a slug, an active version, and one or more domains pointing at it.
```

Project
  └── Deployment ("smile-dental")
        ├── active_version_id ──► Version 17 ──► Release sha:abc...
        ├── Version 16 (archived, still bootable)
        ├── Version 15 (archived, still bootable)
        ├── domains:
        │     ├── smile-dental.miosa.ai   (managed, auto-TLS)
        │     └── smiledental.com         (custom, verified)
        └── data:
              └── postgres:  DATABASE_URL=...
```

A Deployment URL is **stable**. New publishes change which version it points at, not the URL itself.

## What gets versioned

| Thing | Versioned? |
|---|---|
| Source snapshot | Yes — sha256 of the tarball captured at publish time |
| Release artifact | Yes — sha256 of the static tarball or dynamic rootfs |
| Deployment Version | Yes — `version_number` monotonically increases |
| Domain ↔ version mapping | Yes — change history retained |
| Runtime Instances | Managed by scheduler against desired count; not versioned |
| Data Services | Not versioned — Postgres / Redis / buckets persist across deploys |

Rollback works because every release is immutable and stays in storage. Re-point the domain at version 14 and version 14's release rootfs boots immediately.

The current backend uses sandbox-backed deployments as a bridge while the release-rootfs + runtime-instance pipeline completes. Existing `POST /api/v1/sandboxes/:id/deploy` calls return `kind: "sandbox_backed"` until the new path is fully wired. New code should target `kind: "static" | "dynamic" | "auto"` and expect immutable releases as the steady state.

## Next


    The sandbox-to-version pipeline: source snapshots, builder VMs, and build modes.


    Immutable history. List, inspect, promote, and archive versions.


    The artifacts: static tarballs and dynamic rootfs images. How storage works.


    Dynamic deployments — booted from a release on the compute fleet. Scheduler, health checks, reconciler.


    Managed and custom domains. DNS verification, TLS, and route caching.


    Re-point a deployment at an older version in seconds, with no rebuild.

---

# Publishing

URL: https://miosa.ai/docs/deploy/publishing
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/publishing
Source: src/routes/docs/deploy/publishing/+page.md
Description: Turn a Sandbox into an immutable Deployment Version. Source snapshots, builder VMs, build modes.

Publish is the moment a mutable sandbox becomes a frozen, reproducible artifact ready to serve production traffic.

## The pipeline
Diagram:
flowchart LR
    SB[Sandbox] -->|freeze /workspace| SS[Source Snapshot]
    SS --> BLD[Builder VM]
    BLD -->|compile + package| REL[Release]
    REL -->|referenced by| VER[Deployment Version]
    VER -->|promote| DEP[Deployment]
    DEP -->|serves traffic| DOM[Domain]

1. Sandbox /workspace          (mutable; agent or developer is editing here)
2. Source snapshot             (tarball, sha256-keyed, stored in object storage)
3. Builder VM                  (Firecracker microVM booted from miosa-builder image)
4. Build                       (Dockerfile / Railpack / buildpack / static packager)
5. Release                     (static tarball or dynamic rootfs/OCI image, sha256-keyed)
6. Deployment Version          (database row pointing at the release)
7. Health check                (for dynamic; static skips this)
8. Promotion                   (Deployment.active_version_id updated)
```

The sequence below shows who acts at each step:

Diagram:
sequenceDiagram
    participant YC as Your Code
    participant M as MIOSA

    YC->>M: POST /deployments/:id/publish
    M-->>YC: 202 Accepted (build in progress)
    M->>M: freeze /workspace → source snapshot
    M->>M: boot builder VM
    M->>M: compile + package → release artifact
    M->>M: create Deployment Version row
    M->>M: health check (dynamic only)
    M->>M: promote — Deployment.active_version_id updated
    M-->>YC: version.state = ready, public_url live

You call one endpoint. MIOSA does all of this internally and returns the result when the version is ready.

## The publish call

```typescript
const result = await miosa.deployments.publish({
  sourceSandboxId: sandbox.id,
  kind: "auto",                       // "static" | "dynamic" | "auto"
  environment: "production",          // "production" | "staging" | etc.
  outputPath: "/workspace",
  buildCommand: "npm run build",      // optional; auto-detected if omitted
  runCommand: "npm start",            // dynamic only
  port: 3000,                         // dynamic only
  healthCheckPath: "/_health",        // dynamic only
  externalWorkspaceId: "dental-office-123",
  externalUserId: "dr-smith-456",
  externalProjectId: "landing-page-789",
})

console.log(result.deployment.public_url)
console.log(result.version.kind, result.version.state)
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

result = miosa.deployments.publish(
    deployment_id,
    source_sandbox_id=sandbox_id,
    kind="auto",              # "static" | "dynamic" | "auto"
    environment="production",
    output_path="/workspace",
    build_command="npm run build",   # optional; auto-detected if omitted
    run_command="npm start",         # dynamic only
    port=3000,                       # dynamic only
    health_check_path="/_health",    # dynamic only
    external_workspace_id="dental-office-123",
    external_user_id="dr-smith-456",
    external_project_id="landing-page-789",
)

print(result.deployment.public_url)
print(result.version.kind, result.version.state)
```

`deployments.publish()` targets the steady-state endpoint (`POST /deployments/:id/publish`).
Until this path lands in the backend, use `deployments.publish_from_sandbox(sandbox_id, ...)` which calls the currently-live `POST /sandboxes/:id/deploy` bridge.

```bash
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/publish \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source_sandbox_id": "'$SBX'",
    "kind": "auto",
    "environment": "production",
    "output_path": "/workspace",
    "build_command": "npm run build",
    "run_command": "npm start",
    "port": 3000,
    "health_check_path": "/_health"
  }'
```

Response shape:
```json
{
  "data": {
    "deployment": {
      "id": "dep_...",
      "active_version_id": "ver_...",
      "state": "running",
      "public_url": "https://smile-dental.workspace.miosa.app"
    },
    "version": {
      "id": "ver_...",
      "kind": "static",
      "state": "ready",
      "artifact_uri": "s3://...",
      "artifact_sha256": "...",
      "source_sha256": "..."
    },
    "services": [
      { "id": "svc_...", "type": "static_web", "state": "healthy" }
    ],
    "promoted": true
  }
}
```

## Source snapshots

Before the builder runs, MIOSA freezes a snapshot of the sandbox's source. The snapshot is a tarball of `/workspace` (or whatever `output_path` you specify), excluding cache directories that don't need to ship:
```

included:    application code, package manifests, lockfiles, public assets, config
excluded:    node_modules, .next/cache, dist (will be rebuilt), .git (unless needed),
             __pycache__, build/, target/
```

The snapshot tarball is uploaded to object storage and sha256-keyed. The version record stores `source_sha256` so retries can rebuild from the exact same input without re-snapshotting.

The sandbox keeps running while the build runs. You can keep editing.

## Build modes

MIOSA picks a build mode from the source. You can override with `build_command` if needed.

| Mode | Trigger | What happens |
|---|---|---|
| **Dockerfile** | `Dockerfile` exists in `output_path` | BuildKit (`buildctl`) builds the image inside the builder VM |
| **Railpack-style auto-detect** | `package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `mix.exs` | MIOSA detector picks the right install + build commands |
| **Static packager** | Only static files in output (no server entrypoint detected) | Files are tarballed and uploaded as a static release |
| **Explicit** | `buildCommand` and/or `runCommand` provided | MIOSA runs those, then packages whatever's in `output_path` |

The `miosa-builder` image and the Railpack-style detector are in active development. Until the dedicated builder VM is fully wired, publishes run inside a sandbox-backed bridge. This is transparent to the caller — the API shape doesn't change.

## What gets promoted, and when

Static publishes promote as soon as the artifact is uploaded — there's nothing to health-check.

Dynamic publishes don't promote until:

1. The build succeeded.
2. The release rootfs / OCI image was uploaded.
3. New Runtime Instances were scheduled on compute hosts.
4. Health checks (`GET healthCheckPath`) returned 2xx for the configured grace period (default 30s healthy before promotion).

If health checks fail, the **previous version stays live** and the new version is marked `failed`. No traffic is sent to the broken release. Your last known good production keeps serving.

## Idempotency

Pass `Idempotency-Key` on every publish. If the same key is sent twice within the retention window, MIOSA returns the original result without re-building. This makes retries safe — useful for shaky network connections and worker queues.

## Failure modes

| Failure | What happens | Recovery |
|---|---|---|
| Build command exits non-zero | Version marked `failed`, log uploaded, production unchanged | Fix in sandbox, publish again |
| Health check never passes | Version marked `failed`, runtime instances torn down | Fix run command or healthCheckPath, publish again |
| Source snapshot fails | Publish returns 5xx immediately, no version row created | Retry the request |
| Static build exceeds artifact size limit | Version marked `failed` | Reduce assets or contact support to raise limit |
| Two publishes race for the same deployment | Second one waits on the advisory lock; both eventually succeed in order | None — handled by `Engine.OperationLocks` |

## See also

- [Versions](/docs/deploy/versions/) — what publish produces
- [Releases](/docs/deploy/releases/) — the artifact itself
- [Runtime Instances](/docs/deploy/runtime-instances/) — for dynamic deploys
- [Rollback](/docs/deploy/rollback/) — when health checks pass but the app turns out broken

---

# Releases

URL: https://miosa.ai/docs/deploy/releases
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/releases
Source: src/routes/docs/deploy/releases/+page.md
Description: The immutable build artifact — static tarball or dynamic rootfs / OCI image, sha256-keyed.

A **Release** is the physical artifact produced by a build. Versions reference releases; releases sit in object storage; runtime instances boot from them.

You typically don't address releases directly through the API — they're an implementation detail of `Deployment Version`. But it's useful to know they exist as their own record because they're what makes rollback and horizontal scaling work.

First-class `deployment_releases` records arrive in a future deployment refactor phase. Today, release content is referenced via the `artifact_uri` / `artifact_sha256` fields on `deployment_versions`. The shape and semantics described here are how the API will look once `deployment_releases` lands; the current API exposes the same information through the version row.

## Release kinds

| Kind | Used by | Storage |
|---|---|---|
| `static` | Static deployments served from MIOSA's edge | `tar.zst` of the built directory |
| `oci` | Dynamic deployments via OCI image registries | OCI image blobs |
| `rootfs` | Dynamic deployments booted by Firecracker | `tar.zst` of a Linux rootfs |

The release format determines how the deployment is served:

- **Static releases** → MIOSA's static artifact server streams files from object storage directly. No per-app process runs.
- **OCI / rootfs releases** → MIOSA's scheduler picks compute hosts, Firecracker boots Runtime Instances from the release, the router sends traffic to them.

## Immutability

Releases are content-addressed by sha256. A release with sha256 `abc...` is always the same bytes, anywhere it's referenced. This is what makes:

- **Rollback** trivial: repoint a domain at an older version, which still references its release.
- **Scaling** trivial: schedule N copies of the same release on N hosts; every instance is byte-identical.
- **Audit** clean: the release that served traffic at time T can be reproduced from its hash.

A release is never mutated after creation. To "change" it, publish a new version, which produces a new release.

## Where releases live

Releases are stored in MIOSA-managed object storage by default. For larger plans, releases replicate across regions for cold-start locality. You can inspect the storage URI on the version record:
```json
{
  "version_number": 17,
  "artifact_uri": "s3://miosa-releases/dep_xyz/ver_abc.tar.zst",
  "artifact_sha256": "a5e6f0c1...",
  "artifact_manifest": {
    "files": 42,
    "total_bytes": 184320,
    "entrypoint": "index.html"
  }
}
```

You do not need to download releases yourself — MIOSA's serving plane reads from this URI when traffic arrives. The URI is shown for debugging and audit.

## Source snapshot vs release

These are two different artifacts in the same build:

| Artifact | What it is | Sha256 stored on |
|---|---|---|
| **Source snapshot** | Frozen tarball of the sandbox source at publish time | `version.source_sha256` |
| **Release** | The built output | `version.artifact_sha256` |

The source snapshot exists so retries / rebuilds are reproducible. The release exists so production can be served and scaled.

## Garbage collection

Static release artifacts older than the retention window (default 30 days for archived versions) may be garbage-collected. The version row remains for audit; if you attempt to rollback to a version whose artifact has been GC'd, MIOSA returns 410 Gone.

Active versions (`active_version_id` on any deployment) are never GC'd, even past retention.

## See also

- [Versions](/docs/deploy/versions/) — the record referencing the release
- [Runtime Instances](/docs/deploy/runtime-instances/) — what dynamic releases boot into
- [Publishing](/docs/deploy/publishing/) — how releases are created

---

# Rollback

URL: https://miosa.ai/docs/deploy/rollback
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/rollback
Source: src/routes/docs/deploy/rollback/+page.md
Description: Repoint a deployment at an older version. Seconds, no rebuild.

Rollback on MIOSA is fast because nothing has to be rebuilt. The previous release is still in storage. Runtime instances boot quickly. Static artifacts are streamed from object storage. The whole operation is "change one row, propagate to the edge cache."

## When you'd rollback

- New version passed health checks but the app is broken in real traffic (e.g. a feature flag mis-fire).
- A bad migration deployed.
- A regression you missed in staging.
- Hostile incident — quick revert while you investigate.

## How fast

| Step | Static | Dynamic |
|---|---|---|
| Update active version | `&lt;1s` | `&lt;1s` |
| Edge route cache refresh | `&lt;60s default` | `&lt;60s default` |
| New runtime instances spawn? | n/a (no per-app process) | Only if older version's instances were torn down; the scheduler boots replacements |
| Drain old runtime instances | n/a | Only if rolling forward, not on rollback |
| **Total wall clock** | **seconds** | **seconds to ~1 minute** |

If the older version's runtime instances are still healthy (recent rollforward where the old instances haven't been torn down yet), dynamic rollback is also instant — the router switches backends without any VM boots.

## How rollback works
Diagram:
sequenceDiagram
    participant C as Client
    participant API as Deployments API
    participant DB as active_version_id
    participant E as Edge routers
    participant RI as Runtime Instances

    C->>API: POST /deployments/:id/rollback { version_id }
    API->>DB: UPDATE active_version_id = version_id
    API->>E: invalidate route cache
    E-->>E: reload route table (<60s)
    API->>RI: confirm healthy instances for old version
    RI-->>API: instances ready
    API-->>C: deployment with new active_version_id

## API

```typescript
// Easy form: roll back to the previous version
await miosa.deployments.rollback(deploymentId)

// Explicit form: roll back to a specific version
await miosa.deployments.rollback(deploymentId, {
  versionId: "ver_01H...",
})
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Easy form: roll back to the previous version
deployment = miosa.deployments.rollback(deployment_id)

# Explicit form: roll back to a specific version
deployment = miosa.deployments.rollback(
    deployment_id,
    version_id="ver_01H...",
)

print(deployment.active_version_id)
print(deployment.state)
```

```bash
# Rollback to a specific version
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/rollback \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"version_id":"ver_01H..."}'
```

Server behavior:
```

1. Validate target version_id belongs to this deployment
2. Validate target version state === "ready" (cannot rollback to failed)
3. Validate target version's release artifact still exists in storage
   (returns 410 Gone if GC'd)
4. UPDATE deployments SET active_version_id = $version_id
5. Invalidate edge route cache
6. For dynamic: confirm enough healthy instances for the old version; spawn if needed
7. Return the deployment with the new active_version_id
```

Response:
```json
{
  "data": {
    "id": "dep_...",
    "active_version_id": "ver_01H...",
    "state": "running",
    "public_url": "https://smile-dental.cliniciq.miosa.app"
  }
}
```

## Picking the rollback target

Use the [Versions](/docs/deploy/versions/) API to inspect candidates:
```typescript
const versions = await miosa.deployments.versions.list(deploymentId, {
  state: "ready",
  limit: 10,
})

// Find the last known good version
const target = versions.data.find(v => v.id !== deployment.active_version_id)
```

For production, picking the immediately-previous version is usually correct. For incidents, you may need to go further back if multiple recent versions share the bug.

## Rolling forward after rollback

After a rollback, the version you rolled back FROM is still in `ready` state (unless you explicitly archive it). You can re-promote it later if it turns out the issue wasn't in the code:
```typescript
await miosa.deployments.versions.promote(deploymentId, originalVersionId)
```

This is a regular promotion, not a rollback. The path is symmetric.

## What rollback doesn't fix

| Issue | Why rollback doesn't help |
|---|---|
| Bad database migration | The database is *outside* the version. Roll back the schema separately or restore from backup. See [Postgres](/docs/data/postgres/). |
| Bad managed-data state | Same — data services persist across version changes by design. |
| External service config drift | Stripe webhooks, OAuth callbacks, etc. — not part of the release. |
| Already-served bad responses | Already in your customers' browsers / caches. Bust caches separately. |

Rollback fixes code; it does not fix state. Plan migrations to be backward-compatible (`expand → migrate → contract`) so older versions keep working after a forward migration.

## Idempotency

Rollback requests carry an `Idempotency-Key` header. Identical keys within the retention window return the original result without re-running the operation. This matters during incidents when retry storms are common.

## Audit

Every rollback emits an audit event with:

- The previous `active_version_id`
- The target version_id
- The user / API key that performed it
- The `Idempotency-Key`
- External attribution

Audit events are queryable through the platform audit API and are retained per the tenant's plan.

## See also

- [Versions](/docs/deploy/versions/) — picking a target
- [Domains](/docs/deploy/domains/) — what gets repointed
- [Runtime Instances](/docs/deploy/runtime-instances/) — what happens on the compute side
- [Releases](/docs/deploy/releases/) — why the rollback target's artifact must still exist

---

# Runtime Instances

URL: https://miosa.ai/docs/deploy/runtime-instances
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/runtime-instances
Source: src/routes/docs/deploy/runtime-instances/+page.md
Description: Dynamic deployments — Firecracker microVMs booted from a release on the compute fleet.

A **Runtime Instance** is a running production VM that serves a dynamic deployment. Static deployments do not have runtime instances; they're served from MIOSA's edge directly.

Production-grade runtime instances backed by their own data model (`runtime_instances` table, scheduler, reconciler) are part of the ongoing deployment refactor. Today, dynamic deployments use a sandbox-backed bridge. The API surface described here is the steady-state target; current deployments behave equivalently from the caller's perspective but use sandbox VMs under the hood until the bridge is retired.

## What a runtime instance is

A microVM booted by Firecracker from the customer's release rootfs (not from the sandbox image, not from the builder image). The release is the customer's app, fully packaged. The instance:

1. Boots in under a few seconds.
2. Receives `PORT`, `DATABASE_URL`, `AUTH_URL`, and other env vars injected by MIOSA at boot.
3. Starts the configured `run_command`.
4. Listens on `port`.
5. Responds to `GET health_check_path` with 2xx.
6. Joins the deployment's backend pool; the router starts sending it traffic.

When a runtime instance dies (crash, host failure, configured restart), MIOSA's reconciler notices and schedules a replacement on another healthy host.

## What you control vs what MIOSA controls

| You | MIOSA |
|---|---|
| Release contents (your code + dependencies) | Where to schedule instances |
| `run_command` and `port` | When to start / stop / replace instances |
| `health_check_path` | Routing healthy instances to traffic |
| Desired replica count (eventually; defaults to 1) | Boot-time env var injection |
| Env vars set on the deployment | Telemetry, logs streaming |

You don't pick a host directly. MIOSA's scheduler matches your workload's requirements (CPU, RAM, GPU if requested, region) against the fleet's free capacity.

## Lifecycle
```

pending  → starting  → healthy   → stopping  → stopped
                    ↘ unhealthy  ─┘
                    ↘ failed
```

- `pending`: scheduled, not yet booting.
- `starting`: VM is booting; health check not yet passing.
- `healthy`: serving traffic.
- `unhealthy`: failing health checks; router has removed it from the pool. Reconciler decides whether to restart or replace.
- `stopping` / `stopped`: deliberately torn down.
- `failed`: terminal — exceeded crashloop budget. Reconciler stops trying.

## Health checks and the grace period

When a runtime instance starts, it has a configurable grace period (default 60s) to become healthy. During grace, repeated 5xx / connection-refused are tolerated.

After grace, the health check is enforced strictly:

- 3 consecutive failures → instance marked `unhealthy`, removed from routing.
- If a replacement is needed and starts healthily, the old instance is torn down.
- Repeated rapid failures invoke crashloop backoff: 1s → 2s → 5s → 30s → 5min between restart attempts.

## Blue/green during publish

When you publish a new dynamic version, MIOSA does NOT terminate the existing healthy instances first. The sequence is:

1. Start new runtime instances from the new release.
2. Wait until enough new instances pass health checks.
3. Update the router so the deployment's hostname points at the new instances.
4. Drain (stop accepting new connections) and tear down old instances after old in-flight requests complete.

If step 2 never succeeds, step 3 never runs. The old version stays live, the new version is marked `failed`.

## Replicas

By default, a dynamic service has 1 replica. Increase by setting `desired_replicas` on the service. The reconciler spreads replicas across hosts and across availability zones where possible.
```typescript
await miosa.services.update(serviceId, { desiredReplicas: 3 })
```

Traffic load-balances across all healthy replicas in round-robin (or hash-based if sticky sessions are configured).

## Resource sizing

| Spec | Default | Tunable per service |
|---|---|---|
| CPU | 1 vCPU | yes |
| Memory | 512 MB | yes |
| Disk | 1 GB ephemeral | yes |
| GPU | none | yes, requires GPU-eligible plan |
| Outbound bandwidth | metered | yes |

Sizing is per-service, per-deployment. A worker service can be smaller than a web service. A GPU inference service needs a GPU-capable host.

## Logs

Runtime instances stream stdout/stderr to MIOSA's log plane. Logs are retained per the tenant's plan (default 7 days). Access them through:

- `GET /api/v1/deployments/:id/logs` — deployment-scoped, all services
- `GET /api/v1/services/:id/logs` — per-service
- `GET /api/v1/runtime-instances/:id/logs` — per-instance

Logs include structured metadata: `service_id`, `runtime_instance_id`, `version_id`, `host_id`. Filter by `external_workspace_id` to scope to a white-label customer.

## See also

- [Releases](/docs/deploy/releases/) — what runtime instances boot from
- [Environments](/docs/deploy/environments/) — variable / secret scope
- [Domains](/docs/deploy/domains/) — how traffic finds your instances
- [Rollback](/docs/deploy/rollback/) — what happens to old instances on rollback

---

# Versions

URL: https://miosa.ai/docs/deploy/versions
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/deploy/versions
Source: src/routes/docs/deploy/versions/+page.md
Description: Immutable history of every publish. Inspect, promote, archive.

Each successful publish produces a **Deployment Version**. Versions are immutable — the source hash, artifact hash, build log, and runtime config are frozen at creation. Versions never change after they're written.

How Deployments, Versions, and Releases relate:

Diagram:
graph TB
    DEP[Deployment smile-dental] -->|active_version_id| V3[Version v3 - active]
    DEP -->|history| V2[Version v2 - archived]
    DEP -->|history| V1[Version v1 - archived]
    V3 -->|artifact_uri| R3[Release sha256:abc]
    V2 -->|artifact_uri| R2[Release sha256:def]
    V1 -->|artifact_uri| R1[Release sha256:ghi]

## Version shape
```json
{
  "id": "ver_01H...",
  "deployment_id": "dep_01H...",
  "tenant_id": "...",
  "created_by": "user_...",
  "external_workspace_id": "dental-office-123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "landing-page-789",
  "source_sandbox_id": "sbx_...",
  "build_id": "bld_...",
  "version_number": 17,
  "kind": "static",
  "state": "ready",
  "artifact_uri": "s3://miosa-releases/dep_.../ver_.../dist.tar.zst",
  "artifact_manifest": { "files": 42, "total_bytes": 184320, "entrypoint": "index.html" },
  "artifact_sha256": "a5e6f0c1...",
  "runtime_image": null,
  "runtime_command": null,
  "runtime_port": null,
  "health_check_path": null,
  "build_log_uri": "s3://miosa-logs/builds/bld_.../log.txt",
  "metadata": { },
  "promoted_at": "2026-05-14T18:20:00Z",
  "archived_at": null,
  "created_at": "2026-05-14T18:19:48Z",
  "updated_at": "2026-05-14T18:20:00Z"
}
```

For dynamic versions, the `runtime_image`, `runtime_command`, `runtime_port`, and `health_check_path` fields are populated; for static they're null.

## States

| State | Meaning |
|---|---|
| `created` | Row exists, build not started |
| `building` | Build in progress |
| `ready` | Build succeeded, artifact uploaded, can be promoted |
| `failed` | Build failed or health checks didn't pass; not promotable |
| `archived` | Promoted-out-of; still bootable for rollback |

`state` transitions are one-way (no `ready → failed` after the fact); once a version is `ready`, it stays bootable until explicitly garbage-collected.

## Endpoints
```http
GET    /api/v1/deployments/:id/versions
GET    /api/v1/deployments/:id/versions/:version_id
POST   /api/v1/deployments/:id/versions/:version_id/promote
POST   /api/v1/deployments/:id/rollback
```

### List versions

```typescript
const versions = await miosa.deployments.versions.list(deploymentId, {
  limit: 50,
  state: "ready",
})

for (const v of versions.data) {
  console.log(v.version_number, v.kind, v.state, v.artifact_sha256.slice(0, 8))
}
```

```bash
curl https://api.miosa.ai/api/v1/deployments/$DEP/versions?state=ready \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Promote a specific version

Useful for staged rollouts: publish without auto-promote, manually promote when ready.

```typescript
const result = await miosa.deployments.versions.promote(deploymentId, versionId)
console.log(result.deployment.active_version_id) // === versionId
```

```bash
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/versions/$VER/promote \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Requires `deployments:write` scope. Listing/showing requires `deployments:read`.

## Versions and external attribution

Every version inherits attribution from the source sandbox or the publish call. Filtering versions by `external_workspace_id` shows all versions any of your external workspaces published, scoped to your MIOSA tenant.
```typescript
const acmeVersions = await miosa.deployments.versions.list(deploymentId, {
  externalWorkspaceId: "acme-team-123",
})
```

This is how white-label platforms expose a "deploy history" view per end-customer in their own UI.

## How long are versions kept?

`ready` versions are kept for at least 30 days by default. Archived versions older than that are eligible for garbage collection of their release artifacts; the version row itself stays for audit. Long-term storage policies are configurable per tenant — contact support if you need a different retention.

## See also

- [Releases](/docs/deploy/releases/) — what `artifact_uri` actually points at
- [Rollback](/docs/deploy/rollback/) — repoint at an older `ready` version
- [Publishing](/docs/deploy/publishing/) — how versions get created

---

# Files & Exec

URL: https://miosa.ai/docs/develop/files-and-exec
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/develop/files-and-exec
Source: src/routes/docs/develop/files-and-exec/+page.md
Description: Read, write, watch files inside a sandbox. Run commands, stream stdout/stderr, manage processes.

# Files & Exec

The Files and Exec APIs are how you (or an AI agent) interact with a Sandbox. Together they're the substrate for everything else: generating code, running builds, starting servers.

## Files

### Write

```typescript
await sandbox.files.write("/workspace/src/index.ts", `
  console.log("Hello from MIOSA")
`)

// Binary
await sandbox.files.write("/workspace/logo.png", pngBuffer, {
  encoding: "binary",
})
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/files/write \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{
    "path": "/workspace/src/index.ts",
    "content": "console.log(\"Hello from MIOSA\")"
  }'
```

Parent directories are created as needed. Existing files are overwritten.

### Read
```typescript
const content = await sandbox.files.read("/workspace/package.json")
const parsed = JSON.parse(content)
```
```bash
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/files/read?path=/workspace/package.json \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### List
```typescript
const entries = await sandbox.files.list("/workspace")
for (const e of entries) {
  console.log(e.type, e.path, e.size)
}
```
```bash
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/files/list?path=/workspace \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

### Watch

Stream filesystem events:
```typescript
for await (const event of sandbox.files.watch("/workspace")) {
  console.log(event.type, event.path)
  // event.type: "create" | "modify" | "delete"
}
```

Watch is implemented as Server-Sent Events. See [Events](/docs/api-reference/events/) for the SSE event shape.

### Filesystem layout

| Path | Purpose |
|---|---|
| `/workspace` | Working directory; this is where agents write app code |
| `/home/sandbox` | User home |
| `/tmp` | Temporary scratch (cleared on sandbox destroy) |
| `/opt/venv` | Pre-installed Python virtualenv (`miosa-sandbox` and Python templates) |
| `/usr/local/bin` | System binaries |

Generally, write inside `/workspace` and let your build tooling handle node_modules, virtualenvs, etc. Production publish freezes `/workspace` (excluding cache dirs) as the source snapshot — see [Publishing](/docs/deploy/publishing/).

## Exec

Run commands inside the sandbox.

### One-shot

```typescript
const result = await sandbox.exec({
  cmd: "npm",
  args: ["install"],
  cwd: "/workspace",
  env: { NODE_ENV: "development" },
  timeoutMs: 120000,
})

console.log(result.exit_code, result.stdout, result.stderr)
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{
    "cmd": "npm",
    "args": ["install"],
    "cwd": "/workspace",
    "timeout_ms": 120000
  }'
```

Blocks until the command exits (or `timeoutMs` elapses). Returns `exit_code`, `stdout`, `stderr`, and `duration_ms`.

### Detached (long-running servers)
```typescript
await sandbox.exec({
  cmd: "node",
  args: ["server.js"],
  cwd: "/workspace",
  detached: true,
})
```

Returns immediately with a `job_id`. The server keeps running. Use [Previews](/docs/develop/previews/) to expose its port.

### Streaming

For real-time stdout/stderr (e.g. tail an agent's compile output):
```typescript
for await (const chunk of sandbox.exec.stream({
  cmd: "pnpm",
  args: ["dev"],
})) {
  if (chunk.type === "stdout") process.stdout.write(chunk.data)
  if (chunk.type === "stderr") process.stderr.write(chunk.data)
  if (chunk.type === "exit") console.log("exit:", chunk.exit_code)
}
```

Implemented as SSE. See [Streaming Exec](/docs/api-reference/streaming-exec/).

### Terminal

Need an interactive PTY (for remote dev or AI agents driving CLIs)?
```typescript
const terminal = await sandbox.terminal()
terminal.send("ls /workspace\n")
for await (const out of terminal.output) {
  process.stdout.write(out)
}
```

Terminals are WebSocket-based with `xterm.js`-compatible ANSI passthrough. See [API Reference: Terminal](/docs/api-reference/streaming-exec/) for protocol details.

## Process management

For detached exec jobs:
```typescript
const job = await sandbox.exec({ cmd: "npm", args: ["start"], detached: true })

await sandbox.jobs.get(job.id)            // current state
await sandbox.jobs.stop(job.id)           // SIGTERM, then SIGKILL after grace
await sandbox.jobs.list()                 // all detached jobs
```

Detached jobs survive until you explicitly stop them or the sandbox is destroyed.

## Idempotency

Exec is **not** idempotent — running `npm install` twice runs it twice. If you need idempotent retries, store a marker file:
```typescript
const marker = "/workspace/.deps-installed"
const exists = await sandbox.files.exists(marker)
if (!exists) {
  await sandbox.exec({ cmd: "npm", args: ["ci"] })
  await sandbox.files.write(marker, new Date().toISOString())
}
```

File writes are idempotent — same path, same content, same result.

## Limits

| Limit | Default | Tunable |
|---|---|---|
| Max file size per write | 100 MB | Yes (plan-dependent) |
| Max files per sandbox | 1,000,000 | Yes |
| Max exec stdout buffer | 10 MB | Stream mode bypasses this |
| Max exec duration | timeout_ms parameter, default 30s | Yes; detached has no limit |
| Max concurrent detached jobs | 100 | Yes |

`cmd` and `args` are passed as a tuple to `execve` directly — no shell interpolation. You don't need to quote arguments or escape special characters. If you actually want a shell, set `cmd: "bash"` and `args: ["-c", "&lt;your shell command&gt;"]`.

## See also

- [Sandboxes](/docs/develop/sandboxes/) — the VM you're acting on
- [Previews](/docs/develop/previews/) — expose ports started via exec
- [API Reference: Streaming Exec](/docs/api-reference/streaming-exec/) — SSE wire format
- [API Reference: Files](/docs/api-reference/files/) — file API wire format

---

# Previews

URL: https://miosa.ai/docs/develop/previews
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/develop/previews
Source: src/routes/docs/develop/previews/+page.md
Description: Live URLs that proxy into a sandbox port. Public, private, embeddable, share-tokenized.

# Previews

A **Preview** is a URL that routes to a port inside a running Sandbox. The agent writes code, starts a dev server, the preview updates live in the browser. This is the build loop of AI app builders.

## Quick create

```typescript
// Make sure something is listening on the port first
const preview = await sandbox.previews.create({
  port: 3000,
  visibility: "private",   // or "public"
})

console.log(preview.url)
// → https://abc12345.preview.miosa.app
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/previews \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{"port":3000,"visibility":"private"}'
```

The URL follows the pattern `https://&lt;preview_slug&gt;.preview.miosa.app`. For white-label platforms, this can be `https://&lt;preview_slug&gt;.preview.&lt;your-domain&gt;` once DNS delegation is set up.

## Visibility

| Mode | Access |
|---|---|
| `public` | Anyone with the URL can view (and is rate-limited by IP). No auth required. |
| `private` | Requires either an authenticated MIOSA session OR a valid share token. |

For most white-label use cases, **always use `private`**. Then mint a share token to hand to the end user's browser.

## Share tokens

A share token is a short-lived, scoped credential that lets a specific browser access a private preview without exposing your MIOSA workspace API key.

```typescript
const share = await sandbox.previews.share(preview.id, {
  expiresInSec: 3600,  // 1 hour default; max varies by plan
})

console.log(share.share_url)
// → https://abc12345.preview.miosa.app?preview_token=<one-time raw token>

// In your end-user's frontend:
//   <iframe src={shareUrl} sandbox="allow-same-origin allow-scripts" />
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/previews/$PREVIEW/share \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{"expires_in_sec": 3600}'
```

Response:
```json
{
  "data": {
    "id": "preview_...",
    "share_token_prefix": "first12chars",
    "share_token_expires_at": "2026-05-14T19:30:00Z"
  },
  "preview_token": "miosa_pv_<one-time-raw-token>",
  "share_url": "https://abc12345.preview.miosa.app?preview_token=miosa_pv_<one-time-raw-token>"
}
```

The raw `preview_token` value is only in the create-share response. Persist it server-side if you need to re-display, or re-mint a new one. Subsequent reads of the preview return only the `share_token_prefix` (for matching to log entries) and the expiry timestamp.

The token can be passed two ways:
- As `?preview_token=...` query string in the URL (most common; works for iframes).
- As `x-miosa-preview-token: &lt;token&gt;` HTTP header (when you control the request).

MIOSA's proxy strips the credential before forwarding to your sandbox app — your app never sees the token. The proxy authenticates the request, then forwards a clean HTTP request to your dev server on the sandbox.

## Iframe embedding

Previews are designed to be embedded in iframes:
```html
<iframe src="https://abc12345.preview.miosa.app?preview_token=miosa_pv_..."
        sandbox="allow-same-origin allow-scripts allow-forms"
        style="width:100%; height:600px; border:0;"></iframe>
```

The preview proxy emits CSP `frame-ancestors` for `*.miosa.app`, `*.miosa.ai`, and `localhost:4000` by default. For white-label embedding into your own domain, contact support — the production proxy CSP is configurable per tenant.

## How it works
Diagram:
sequenceDiagram
    participant A as Agent / SDK
    participant S as Sandbox
    participant P as Preview proxy
    participant B as Browser

    A->>S: exec("node server.js", detached)
    A->>S: previews.create(port: 3000)
    S-->>A: { url: "https://abc.preview.miosa.app" }
    A->>S: previews.share(id, expiresInSec: 3600)
    S-->>A: { share_url: "...?preview_token=..." }
    B->>P: GET share_url
    P->>P: verify preview_token
    P->>S: proxy request to port 3000
    S-->>P: HTTP response
    P-->>B: response (token stripped)

## Lifecycle
```

active → expired → deleted
```

- `active` while the underlying sandbox is running and the preview hasn't been explicitly deleted.
- `expired` once the share token TTL (if set) elapses.
- `deleted` when you delete it, or automatically a short time after the sandbox is destroyed.

Re-creating a preview on the same port returns a new preview record with a new slug. Old preview URLs do not automatically transfer.

## Preview vs Deployment URL

| | Preview | Deployment URL |
|---|---|---|
| What it points at | A live sandbox port | An immutable deployment version |
| Updates live? | Yes — sandbox edits reflect immediately | No — only changes on rollback / re-promote |
| Lifetime | Tied to the sandbox | Persistent |
| Use it for | Build loop, sharing in-progress work | Production traffic |

You don't promote a preview to a deployment. You publish from a sandbox (which produces a deployment version with its own URL). The preview keeps living until the sandbox dies.

## Abuse limits

Public previews are aggressively rate-limited by IP at the edge. Private previews are rate-limited per share token. If you're embedding into a high-traffic site, use a custom domain and a dedicated tenant plan — preview hosts are not designed to serve production traffic.

## See also

- [Sandboxes](/docs/develop/sandboxes/) — what a preview proxies to
- [Browser Tokens](/docs/platform/browser-tokens/) — share-token patterns for white-label embedding
- [Publishing](/docs/deploy/publishing/) — turn a previewable sandbox into a production deployment

---

# Sandboxes

URL: https://miosa.ai/docs/develop/sandboxes
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/develop/sandboxes
Source: src/routes/docs/develop/sandboxes/+page.md
Description: Mutable Firecracker microVMs for AI agent code execution. Boot in ~150 ms, run commands, expose ports as live preview URLs, snapshot state for branching or rollback.

# Sandboxes

A **Sandbox** is a mutable Firecracker microVM that boots warm in ~150 ms from a versioned template snapshot. Your agent writes files into it, executes commands, exposes ports as live preview URLs, and snapshots state for branching or rollback. When the work is done you destroy it — or publish it to a production deployment.

## What a Sandbox is — concretely

- A Firecracker microVM (not a container, not a VM in the usual cloud sense)
- 1 vCPU, 1 GiB RAM, 3 GiB disk by default — configurable up to 8 vCPU, 8 GiB RAM, 10 GiB disk
- `/workspace` is the editable filesystem root
- Boots from a versioned template (`miosa-sandbox` by default; see [Templates](/docs/develop/templates/))
- Auto-destroyed after `timeout_sec` of wall-clock time (default 300 s; set `always_on=True` to disable)
- Network-isolated by default; preview URLs open specific ports to the internet

Pick a **Sandbox** for code-gen agents, builds, dev servers, command execution, and anything that needs a Linux process environment. Pick a [Computer](/docs/computers/overview/) when you need a full desktop — screenshots, mouse clicks, browser automation, computer-use agents.

## Lifecycle

Diagram:
stateDiagram-v2
    [*] --> provisioning
    provisioning --> running : boot complete (~150 ms warm)
    running --> paused : pause() / snapshot
    paused --> running : resume()
    running --> destroyed : destroy() or timeout_sec elapsed
    paused --> destroyed : destroy()
    running --> error : boot or runtime failure
    error --> destroyed
    destroyed --> [*]

| State | Meaning |
|---|---|
| `provisioning` | VM is booting from the template snapshot |
| `running` | Ready — exec, files, previews all work |
| `paused` | Snapshotted; resume() restores full state in ~200 ms |
| `destroyed` | Terminal — resources freed, ID unusable |
| `error` | Boot or runtime failure; check `sbx.data["metadata"]` for `last_error` |

Activity that resets the idle clock: exec calls, file writes, preview HTTP traffic, terminal stdin. Once `timeout_sec` elapses with no activity the sandbox transitions directly to `destroyed`.

## Create a sandbox

```python

from miosa import Miosa

miosa = Miosa(api_key=os.environ["MIOSA_API_KEY"])

sbx = miosa.sandboxes.create(
    "miosa-sandbox",              # template_id (positional); default if omitted
    cpu_count=2,                  # 1–8
    memory_mb=2048,               # up to 8192
    disk_size_mb=8192,            # up to 10240; default 3072
    timeout_sec=3600,             # wall-clock TTL; default 300
    env={"NODE_ENV": "production"},
    metadata={"agent_run": "abc123"},
    external_workspace_id="acme-corp",   # white-label attribution
    idempotency_key="run-2026-05-17-001",
)

print(sbx.id)         # sbx_a1b2c3d4
print(sbx.state)      # "running"
print(sbx.boot_ms)    # e.g. 148 (warm pool hit)
print(sbx.boot_path)  # "warm" | "cold"
```

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const sbx = await miosa.sandboxes.create({
  templateId: "miosa-sandbox",
  cpuCount: 2,
  memoryMb: 2048,
  diskSizeMb: 8192,
  timeoutSec: 3600,
  env: { NODE_ENV: "production" },
  metadata: { agentRun: "abc123" },
  externalWorkspaceId: "acme-corp",
  idempotencyKey: "run-2026-05-17-001",
});

console.log(sbx.id, sbx.state, sbx.boot_ms);
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-05-17-001" \
  -d '{
    "template_id": "miosa-sandbox",
    "cpu_count": 2,
    "memory_mb": 2048,
    "disk_size_mb": 8192,
    "timeout_sec": 3600,
    "env": { "NODE_ENV": "production" },
    "metadata": { "agent_run": "abc123" },
    "external_workspace_id": "acme-corp"
  }'
```

The response body contains `id`, `state`, `template_id`, `cpu_count`, `memory_mb`, `boot_ms`, `boot_path`, and `created_at`. Save the `id` — every subsequent call needs it.

### Context manager (auto-destroy)

The Python SDK supports `with` / `async with` — the sandbox is destroyed on exit even if an exception is raised:

```python
with miosa.sandboxes.create("miosa-sandbox") as sbx:
    sbx.files.write("/workspace/hello.py", "print('hello')")
    result = sbx.exec.run("python3 /workspace/hello.py")
    print(result.stdout)
# sbx.destroy() called automatically here
```

```typescript
// TypeScript: manual cleanup with try/finally
const sbx = await miosa.sandboxes.create({ templateId: "miosa-sandbox" });
try {
  await sbx.files.write("/workspace/hello.py", "print('hello')");
  const result = await sbx.exec.run("python3 /workspace/hello.py");
  console.log(result.stdout);
} finally {
  await sbx.destroy();
}
```

### Connect to an existing sandbox

```python
# By ID
sbx = miosa.sandboxes.get("sbx_a1b2c3d4")

# By name (if you set name= at create time)
sbx = miosa.sandboxes.get_by_name("my-dev-env")

# connect() is an alias for get()
sbx = miosa.sandboxes.connect("sbx_a1b2c3d4")
```

```typescript
const sbx = await miosa.sandboxes.get("sbx_a1b2c3d4");
// or
const sbx = await miosa.sandboxes.getByName("my-dev-env");
```

```bash
curl https://api.miosa.ai/api/v1/sandboxes/sbx_a1b2c3d4 \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# By name
curl https://api.miosa.ai/api/v1/sandboxes/by-name/my-dev-env \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

## Run a command — exec

`exec.run` blocks until the process exits and returns `stdout`, `stderr`, `exit_code`, and `duration_ms`.

```python
# Basic
result = sbx.exec.run("npm install")
print(result.stdout)
print(result.exit_code)   # 0 = success

# With options
result = sbx.exec.run(
    "pytest tests/ -x --tb=short",
    {"cwd": "/workspace", "env": {"PYTHONPATH": "/workspace"}, "timeout_sec": 120},
)
if result.exit_code != 0:
    raise RuntimeError(f"Tests failed:\n{result.stderr}")

# Shorthand — sbx.exec is also callable
result = sbx.exec("python3 main.py")
```

```typescript
const result = await sbx.exec.run("npm install");
console.log(result.stdout, result.exitCode);

// With options
const result2 = await sbx.exec.run("pytest tests/ -x --tb=short", {
  cwd: "/workspace",
  env: { PYTHONPATH: "/workspace" },
  timeoutSec: 120,
});
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/exec \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm install", "cwd": "/workspace", "timeout": 120}'
```

### Stream stdout/stderr in real time

`exec.stream` returns an iterator of SSE events. Use this for long commands (builds, test runs, installs) where you want to surface output progressively.

```python
for event in sbx.exec.stream("pnpm build", {"cwd": "/workspace"}):
    if event.type == "stdout":
        print(event.data.get("line", ""), end="")
    elif event.type == "stderr":
        print("[err]", event.data.get("line", ""), end="")
    elif event.type == "exit":
        code = event.data.get("exit_code", 0)
        print(f"\nExited with {code}")
        break
```

```typescript
for await (const event of sbx.exec.stream("pnpm build", { cwd: "/workspace" })) {
  if (event.type === "stdout") process.stdout.write(event.line ?? "");
  if (event.type === "stderr") process.stderr.write(event.line ?? "");
  if (event.type === "exit") {
    console.log("exit code:", event.exit_code);
    break;
  }
}
```

```bash
# Streaming exec — Accept: text/event-stream
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/exec/stream \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"command": "pnpm build", "cwd": "/workspace"}'
```

| Option | Type | Default | Description |
|---|---|---|---|
| `cwd` / `working_dir` | `str` | `/workspace` | Working directory for the command |
| `env` | `dict[str, str]` | `{}` | Extra env vars merged with the sandbox env |
| `timeout_sec` / `timeout` | `int` | 30 | Kill the process after this many seconds |

## Files — write, read, list, stat

All file paths are absolute. Parent directories are created automatically on write. File content is base64-encoded over the wire.

```python
# Write (str, bytes, or pathlib.Path)
sbx.files.write("/workspace/app.py", "print('hello')")
sbx.files.write("/workspace/logo.png", Path("./logo.png"))

# Read (returns bytes; .read_text returns str)
raw: bytes = sbx.files.read("/workspace/package.json")
text: str  = sbx.files.read_text("/workspace/package.json")

# List directory
listing = sbx.files.list("/workspace")
# → {"entries": [{"name": "app.py", "path": "/workspace/app.py", "size": 14, "is_dir": false}, ...]}

# Stat a single path
info = sbx.files.stat("/workspace/app.py")
# → {"path": ..., "size": 14, "is_dir": false, "mode": "0644", "modified_at": "..."}
```

```typescript
// Write
await sbx.files.write("/workspace/app.py", "print('hello')");
await sbx.files.write("/workspace/logo.png", pngUint8Array);

// Read
const bytes: Uint8Array = await sbx.files.read("/workspace/package.json");
const text: string      = await sbx.files.readText("/workspace/package.json");

// List
const listing = await sbx.files.list("/workspace");
// → { entries: [{ name, path, size, is_dir, modified_at }] }

// Stat
const info = await sbx.files.stat("/workspace/app.py");
```

```bash
# Write — content must be base64-encoded
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/files \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"path\": \"/workspace/hello.py\", \"content\": \"$(echo 'print(1)' | base64)\"}"

# Read
curl "https://api.miosa.ai/api/v1/sandboxes/$SBX/files/workspace/hello.py" \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# List
curl "https://api.miosa.ai/api/v1/sandboxes/$SBX/files?path=/workspace" \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Stat
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/files/stat \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/hello.py"}'
```

### Filesystem layout

| Path | Purpose |
|---|---|
| `/workspace` | Agent working directory — write all app code here |
| `/home/sandbox` | User home |
| `/tmp` | Scratch space — cleared on destroy |
| `/opt/venv` | Pre-installed Python virtualenv (`miosa-sandbox`, `python` templates) |
| `/usr/local/bin` | System binaries |

## Previews — expose a port

`previews.create` maps a sandbox port to a public HTTPS URL managed by MIOSA. The URL is live as long as the sandbox is running.

```python
# Start a server inside the sandbox first
sbx.exec.stream("python3 -m http.server 8080", {"cwd": "/workspace"})

# Then expose the port
preview = sbx.previews.create(port=8080)
print(preview["url"])    # https://sbx_a1b2c3d4.preview.miosa.app

# Or use the quick expose() helper
url = sbx.expose(8080)

# List all previews for this sandbox
previews = sbx.previews.list()

# Mint a time-limited share token (1 hour default)
token = sbx.previews.share(preview["id"], ttl_seconds=3600)
print(token["share_url"])

# Revoke all share tokens for a preview
sbx.previews.revoke_share(preview["id"])

# Delete a preview (stop routing to this port)
sbx.previews.delete(preview["id"])
```

```typescript
// Expose port
const preview = await sbx.previews.create({ port: 8080 });
console.log(preview.url);   // https://sbx_a1b2c3d4.preview.miosa.app

// Quick helper
const url = await sbx.expose(8080);

// Mint a share token
const token = await sbx.previews.share(preview.id, { ttlSeconds: 3600 });

// Revoke share tokens
await sbx.previews.revokeShare(preview.id);
```

```bash
# Create preview
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/previews \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

# List previews
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/previews \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Mint share token
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/previews/$PREVIEW_ID/share \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 3600}'
```

See [Previews](/docs/develop/previews/) for visibility controls, custom domains, and embedding.

## Snapshots — save and fork state

A snapshot freezes the entire VM state (memory + disk). You can restore the same sandbox to an earlier state, or create a branch by restoring into a new sandbox.

```python
# Save current state
snap = sbx.snapshots.create(comment="after npm install")
snap_id = snap["id"]   # e.g. "snap_xyz789"

# List all snapshots for this sandbox
snaps = sbx.snapshots.list()

# Restore this sandbox to a previous snapshot (in place)
sbx2 = sbx.snapshots.restore(snap_id)
# sbx2 is a new Sandbox handle pointing at the restored state

# Delete a snapshot
sbx.snapshots.delete(snap_id)
```

```typescript
// Save
const snap = await sbx.snapshots.create({ comment: "after npm install" });

// List
const snaps = await sbx.snapshots.list();

// Restore
const sbx2 = await sbx.snapshots.restore(snap.id);

// Delete
await sbx.snapshots.delete(snap.id);
```

```bash
# Create snapshot
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "after npm install"}'

# List
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/snapshots \
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Restore
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/restore/$SNAP_ID \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Delete
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/$SBX/snapshots/$SNAP_ID \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Pattern: snapshot after installing dependencies, before running agent-generated code. If the agent produces a bad state you can restore to the clean deps snapshot in ~200 ms instead of re-running the entire install.

## Pause and resume

`pause()` and `resume()` give you explicit control over the `running ↔ paused` transition without destroying state.

```python
sbx.pause()
# state is now "paused" — billing drops to storage rate only

sbx.resume()
# state returns to "running" in ~200 ms
```

```typescript
await sbx.pause();
await sbx.resume();
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/pause \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/resume \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Environment variables

Env vars set at create time are injected into the VM at boot and visible to all processes. They are read-only once the sandbox is running; `env.list()` returns the live set.

```python
# Set at create time
sbx = miosa.sandboxes.create(
    env={"DATABASE_URL": "postgres://...", "API_SECRET": "..."},
)

# Read the live env inside a running sandbox
env = sbx.env.list()
print(env)  # {"DATABASE_URL": "postgres://...", ...}
```

```typescript
const sbx = await miosa.sandboxes.create({
  env: { DATABASE_URL: "postgres://...", API_SECRET: "..." },
});

const env = await sbx.env.list();
```

```bash
# Pass at create time (in the POST body above)

# Read
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/env \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Env vars are stored in the sandbox record and visible to any process inside the VM. For secrets that must not appear in logs or snapshots, pass them as exec-level `env` on individual commands rather than at sandbox create time.

## Subscribe to sandbox events

The `events.stream()` endpoint emits lifecycle and activity SSE events for a sandbox — useful for monitoring agent runs.

```python
for event in sbx.events.stream():
    print(event["type"], event.get("data"))
    # types: "sandbox.started", "sandbox.destroyed", "exec.started", "exec.completed", ...
```

```typescript
for await (const event of sbx.events.stream()) {
  console.log(event.type, event.data);
}
```

```bash
curl https://api.miosa.ai/api/v1/sandboxes/$SBX/events \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Accept: text/event-stream"
```

## List and filter sandboxes

```python
# All running sandboxes
running = miosa.sandboxes.list(state="running")

# Filter by white-label workspace
ws_sandboxes = miosa.sandboxes.list(external_workspace_id="acme-corp")

# Filter by tags
tagged = miosa.sandboxes.list(tags=["pr-preview", "staging"])
```

```typescript
const running = await miosa.sandboxes.list({ state: "running" });
const byCorp  = await miosa.sandboxes.list({ externalWorkspaceId: "acme-corp" });
```

```bash
curl "https://api.miosa.ai/api/v1/sandboxes?state=running" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

## Sizing reference

| Field | Default | Validation range |
|---|---|---|
| `cpu_count` | 1 | 1–8 |
| `memory_mb` | 1024 | 1–8192 |
| `disk_size_mb` | 3072 | 1–10240 |
| `timeout_sec` | 300 | 1–86400 |
| `idle_timeout_sec` | 0 (disabled) | 0–86400 |
| `always_on` | `false` | — |

Set `always_on=True` to disable `timeout_sec` enforcement entirely. Useful for long-lived development environments or hosted IDEs. Set `idle_timeout_sec` to auto-destroy after a period of inactivity rather than a fixed wall-clock limit.

## Custom templates

Build a custom template when you need a reproducible base image with dependencies pre-installed — reduces every sandbox cold-start by eliminating the install step.

```python
template = miosa.sandboxes.create_template(
    name="my-nextjs-stack",
    build_spec={
        "from": "node",
        "steps": [
            {"run": "npm install -g pnpm@9"},
            {"run": "mkdir -p /workspace && cd /workspace && pnpm init"},
        ],
        "workdir": "/workspace",
        "startCmd": "pnpm dev",
        "previewPort": 3000,
    },
    description="Next.js 15 + pnpm 9 base",
)

# Trigger a build (creates the snapshot image)
build = miosa.sandboxes.create_template_build(
    template["id"],
    build_spec=template["build_spec"],
)
print(build["state"])   # "queued" → "building" → "ready"
```

```typescript
const template = await miosa.sandboxes.createTemplate({
  name: "my-nextjs-stack",
  buildSpec: {
    from: "node",
    steps: [{ run: "npm install -g pnpm@9" }],
    workdir: "/workspace",
    startCmd: "pnpm dev",
    previewPort: 3000,
  },
});

const build = await miosa.sandboxes.createTemplateBuild(template.id);
```

```bash
# Create template
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nextjs-stack",
    "build_spec": {
      "from": "node",
      "steps": [{"run": "npm install -g pnpm@9"}],
      "workdir": "/workspace",
      "startCmd": "pnpm dev",
      "previewPort": 3000
    }
  }'

# Trigger a build
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates/$TEMPLATE_ID/builds \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Validate a build spec before committing
curl -X POST https://api.miosa.ai/api/v1/sandbox-templates/validate \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"build_spec": {"from": "node", "steps": []}}'
```

See [Templates](/docs/develop/templates/) for the full `BuildSpec` reference, available base images, and template versioning.

## Production checklist

Before relying on sandboxes in production:

- Set an explicit `timeout_sec`. The default is 300 s. An agent loop that hangs without one will keep billing until the plan-max (up to 86400 s).
- Set `idle_timeout_sec` for user-facing dev environments so abandoned sessions clean themselves up.
- Pass `idempotency_key` on `sandboxes.create` calls in agent retry loops. The platform deduplicates creates with the same key within a 24-hour window.
- Use templates instead of installing dependencies inside every sandbox. A `pnpm install` that takes 45 s becomes a 150 ms warm boot.
- Snapshot before destructive operations. Restore is ~200 ms; re-running an install is not.
- Subscribe to `sbx.events.stream()` to detect unexpected exits and trigger retries.
- Never store long-lived secrets in `env` — pass them per-exec or use the Secrets API.
- Filter by `external_workspace_id` in your list calls to avoid scanning your entire tenant's sandbox set.

## Billing notes

Billing accrues from `state = "running"` until `state = "destroyed"` or `state = "paused"`.

- **Running**: billed at the vCPU-second + GiB-second rate for your plan
- **Paused**: billed at storage rate only (disk GiB-second)
- **Destroyed**: billing stops immediately

Templates cached on every region — picking a built-in template incurs no boot-delay penalty.

## See also


    Full filesystem and process API — recursive operations, watch, detached jobs.


    Live HTTPS URLs proxied to a sandbox port with share tokens and visibility controls.


    Built-in images and custom BuildSpec reference.


    Raw REST reference for snapshot create, list, restore, delete.

---

# Templates

URL: https://miosa.ai/docs/develop/templates
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/develop/templates
Source: src/routes/docs/develop/templates/+page.md
Description: Pre-built Firecracker images for every major language and framework. Pick the closest match to your stack.

# Templates

A **template** is a pre-built Firecracker image with a specific language and framework already installed. Pick the closest match to your stack; you can override install/start commands per-sandbox if needed.

## Template catalog

| Slug | Language / Framework | Default port | Best for |
|---|---|---|---|
| [`miosa-sandbox`](#miosa-sandbox) | Generic (default) | — | Custom builds, scripting, any language |
| [`node`](#node) | Node.js 24 LTS | 3000 | Node servers, scripts, CLIs |
| [`nextjs`](#nextjs) | Next.js 15 | 3000 | Full-stack React apps |
| [`react-vite`](#react-vite) | React + Vite | 5173 | SPA frontends |
| [`svelte`](#svelte) | SvelteKit 2 | 5173 | SvelteKit apps |
| [`python`](#python) | Python 3.13 | 8000 | Python services, FastAPI, data pipelines |
| [`go`](#go) | Go 1.24 | 8080 | Go services and CLIs |
| [`rust`](#rust) | Rust 1.85 | 8080 | Rust services |
| [`static`](#static) | Static HTML/CSS/JS | 8080 | Pure static sites, docs |

---

## miosa-sandbox

The default general-purpose template. Use it when no other template fits, or when you want a blank slate with common tooling.

**Pre-installed:** Node.js 20, Python 3.11, Go toolchain, Rust toolchain, git, curl, wget, unzip, common build tools (`gcc`, `make`), `uv`, `pnpm`, `yarn`.

**Default port:** None pre-configured — open any port you choose.

```python

client = miosa.Miosa(api_key="msk_u_...")

sandbox = client.sandboxes.create(
    template_id="miosa-sandbox",
)

# Install whatever you need
result = sandbox.exec("pip install flask && python -m flask run --port 5000 &")
```

```typescript

const miosa = new Miosa({ apiKey: 'msk_u_...' });

const sandbox = await miosa.sandboxes.create({
  templateId: 'miosa-sandbox',
});

// Install whatever you need
const result = await sandbox.exec(
  'pip install flask && python -m flask run --port 5000 &',
);
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "miosa-sandbox" }'
```

`miosa-sandbox` is the default when `template_id` is omitted.

---

## node

Node.js 24 LTS with npm, pnpm, and yarn pre-installed.

**Pre-installed:** Node.js 24 LTS, npm, pnpm, yarn, git.

**Default port:** 3000.

**Default install command:** `npm install`

**Default start command:** `npm start`

```python
sandbox = client.sandboxes.create(
    template_id="node",
    install_command="npm install",
    start_command="node server.js",
)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'node',
  installCommand: 'npm install',
  startCommand: 'node server.js',
});
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "node",
    "install_command": "npm install",
    "start_command": "node server.js"
  }'
```

---

## nextjs

Next.js 15 with a scaffold pre-installed and `pnpm` dependencies cached.

**Pre-installed:** Node.js 24 LTS, pnpm, Next.js 15 scaffold (in `/workspace`), Tailwind CSS.

**Default port:** 3000.

**Default install command:** `pnpm install`

**Default start command:** `pnpm dev`

```python
sandbox = client.sandboxes.create(
    template_id="nextjs",
)
# Dev server starts on port 3000 automatically
preview = sandbox.previews.create(port=3000)
print(preview.url)  # https://abc12345.preview.miosa.app
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'nextjs',
});
const preview = await sandbox.previews.create({ port: 3000 });
console.log(preview.url); // https://abc12345.preview.miosa.app
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "nextjs" }'
```

**Production publish gotcha:** Next.js SSR deployments require `output: "standalone"` in `next.config.js` so the builder can package the server. Static exports (`output: "export"`) work without this setting.
```js
// next.config.js — required for SSR publishing
module.exports = {
  output: 'standalone',
};
```

---

## react-vite

React 18 + Vite 5 for pure SPA development.

**Pre-installed:** Node.js 24 LTS, pnpm, React 18, Vite 5, TypeScript.

**Default port:** 5173.

**Default install command:** `pnpm install`

**Default start command:** `pnpm dev --host 0.0.0.0`

The `--host 0.0.0.0` flag in the start command is required for preview tunnels to reach the Vite dev server. It is included in the template default; only override if you know what you are doing.

```python
sandbox = client.sandboxes.create(
    template_id="react-vite",
)
preview = sandbox.previews.create(port=5173)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'react-vite',
});
const preview = await sandbox.previews.create({ port: 5173 });
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "react-vite" }'
```

**Production publish gotcha:** Vite produces a fully static output (`dist/`). The builder auto-detects this and serves it from the edge as a Static Release. No `output` config needed.

---

## svelte

SvelteKit 2 with adapters pre-installed.

**Pre-installed:** Node.js 24 LTS, pnpm, SvelteKit 2, `@sveltejs/adapter-auto`, `@sveltejs/adapter-node`, `@sveltejs/adapter-static`.

**Default port:** 5173.

**Default install command:** `pnpm install`

**Default start command:** `pnpm dev --host 0.0.0.0`

```python
sandbox = client.sandboxes.create(
    template_id="svelte",
)
preview = sandbox.previews.create(port=5173)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'svelte',
});
const preview = await sandbox.previews.create({ port: 5173 });
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "svelte" }'
```

**Production publish gotcha:** For SSR publishing, set `adapter-node` in `svelte.config.js`. For a static site, set `adapter-static`. The builder detects which adapter is configured and picks the appropriate release type.

---

## python

Python 3.13 with `uv`, `pip`, and common ML/data tooling.

**Pre-installed:** Python 3.13, `uv`, `pip`, `venv`, `fastapi`, `uvicorn`, `httpx`, `pydantic`, git.

**Default port:** 8000.

**Default install command:** `uv sync` (falls back to `pip install -r requirements.txt`)

**Default start command:** `uvicorn main:app --host 0.0.0.0 --port 8000`

```python
sandbox = client.sandboxes.create(
    template_id="python",
    start_command="uvicorn app:app --host 0.0.0.0 --port 8000 --reload",
)
preview = sandbox.previews.create(port=8000)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'python',
  startCommand: 'uvicorn app:app --host 0.0.0.0 --port 8000 --reload',
});
const preview = await sandbox.previews.create({ port: 8000 });
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "python",
    "start_command": "uvicorn app:app --host 0.0.0.0 --port 8000 --reload"
  }'
```

**Production publish gotcha:** The builder uses a `Procfile` or the configured start command to determine the entry point. Ensure your `main.py` / `app.py` is in `/workspace` and uvicorn listens on `0.0.0.0`, not `127.0.0.1`.

---

## go

Go 1.24 with modules enabled.

**Pre-installed:** Go 1.24, git, common build tools.

**Default port:** 8080.

**Default install command:** `go mod download`

**Default start command:** `go run .`

```python
sandbox = client.sandboxes.create(
    template_id="go",
    start_command="go run . -port 8080",
)
preview = sandbox.previews.create(port=8080)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'go',
  startCommand: 'go run . -port 8080',
});
const preview = await sandbox.previews.create({ port: 8080 });
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "go" }'
```

**Production publish gotcha:** For publishing, the builder runs `go build -o app .` and sets the start command to `./app`. Ensure your `main.go` reads the port from an environment variable (`PORT`) so the runtime instance can override it.

---

## rust

Rust 1.85 (stable) with Cargo.

**Pre-installed:** Rust 1.85 stable, `cargo`, common build tools.

**Default port:** 8080.

**Default install command:** `cargo fetch`

**Default start command:** `cargo run --release`

```python
sandbox = client.sandboxes.create(
    template_id="rust",
)
preview = sandbox.previews.create(port=8080)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'rust',
});
const preview = await sandbox.previews.create({ port: 8080 });
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "rust" }'
```

Rust compile times are long. The first `cargo build --release` inside a fresh sandbox can take 2–5 minutes depending on dependency count. Use snapshots to cache the compiled state for faster iteration.

**Production publish gotcha:** The builder runs `cargo build --release` and strips the resulting binary. Bind your listener to `0.0.0.0` and read the port from the `PORT` environment variable.

---

## static

Plain HTML, CSS, and JavaScript. No build step.

**Pre-installed:** A static file server (`caddy`) that serves `/workspace` on port 8080.

**Default port:** 8080.

**Default install command:** *(none)*

**Default start command:** `caddy file-server --root /workspace --listen :8080`

```python
sandbox = client.sandboxes.create(
    template_id="static",
)

# Write your HTML
sandbox.files.write("/workspace/index.html", "<h1>Hello world</h1>")

preview = sandbox.previews.create(port=8080)
print(preview.url)
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'static',
});

await sandbox.files.write('/workspace/index.html', '<h1>Hello world</h1>');

const preview = await sandbox.previews.create({ port: 8080 });
console.log(preview.url);
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "static" }'
```

**Production publish:** The builder detects a static site (no `package.json`, `Cargo.toml`, or `go.mod`) and packages `/workspace` as a Static Release. Assets are served from the edge — no Runtime Instances required.

---

## Custom templates

When the built-in catalog does not fit — proprietary toolchains, specific CUDA/GPU stacks, pre-loaded datasets — you can build and register your own template.

1. Write a `Dockerfile` for your image.
2. Build it using the custom template API (or the CLI: `miosa templates build`).
3. Verify the image boots correctly.
4. Register the slug so it is selectable in `template_id`.

See the [Custom Templates API Reference](/docs/api-reference/sandboxes/) for the full endpoint spec, including image upload, smoke-test hooks, and versioning.

---

## BuildSpec primer

A **BuildSpec** is an optional JSON document you attach to a sandbox or Deployment to override the default install and start commands. It is the escape hatch for any template when defaults are not quite right:
```json
{
  "install": "pnpm install --frozen-lockfile",
  "build": "pnpm build",
  "start": "node .next/standalone/server.js",
  "env": {
    "NODE_ENV": "production",
    "PORT": "3000"
  }
}
```

Pass a BuildSpec at sandbox creation time or at publish time. Build-time commands (`install`, `build`) run inside the Builder; the `start` command determines how Runtime Instances are launched. Environment variables set here are merged with any variables already on the Deployment.

---

---

# Fundamental Concepts

URL: https://miosa.ai/docs/fundamentals
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/fundamentals
Source: src/routes/docs/fundamentals/+page.md
Description: The mental model every MIOSA integrator needs — workspace, authentication, resources, attribution, idempotency, rate limits, errors, and events.

# Fundamental Concepts

MIOSA is a cloud platform for building and deploying applications. Before writing your first API call, read this page. It covers the eight concepts that underpin every MIOSA integration.

---

## 1. Organization, workspaces, and projects

Your MIOSA account starts as one **organization**. The organization has a permanent slug, one billing account, and API keys. Inside it, you can create multiple **workspaces** and **projects**:

- The organization is the authorization and billing boundary.
- A workspace usually represents a customer, client, team, or environment.
- A project represents the app, website, lead magnet, document, or workflow being built inside a workspace.
- Sandboxes, Computers, Deployments, Databases, Domains, Storage, Volumes, Functions, and Jobs belong to a project.

If you are building a platform product on top of MIOSA, use MIOSA workspaces for downstream customers and MIOSA projects for the things they create. External attribution fields still exist for your own IDs and chargeback.
Diagram:
graph TD
  Backend["Your Platform Backend"]
  Org["MIOSA Organization<br/>one slug · one bill"]
  WS["Workspace<br/>Dr. Smith Clinic"]
  Proj["Project<br/>Lead Magnet"]
  Sbx["Sandbox"]
  Dep["Deployment"]
  Db["Database"]
  Backend --> Org
  Org --> WS
  WS --> Proj
  Proj --> Sbx
  Proj --> Dep
  Proj --> Db

---

## 2. Authentication

Every API request carries one header:
```http
Authorization: Bearer <token>
```

The token is either an **API key** or a **browser token** (scoped JWT).

### API keys

API keys have the prefix `msk_` followed by a role segment:

| Prefix | Role | Use |
|---|---|---|
| `msk_u_...` | user | General-purpose server-side calls |
| `msk_a_...` | admin | Operator/platform tooling |
| `msk_p_...` | platform | Tenant-wide automation |

**API keys are server-side only.** Never put an `msk_*` key in browser code, a mobile app, or a public repository.

A leaked `msk_*` key grants full workspace access. Revoke it immediately at `DELETE /api/v1/api-keys/{id}` and rotate.

### Browser tokens

For browser-side access — embedding a preview, opening a terminal in an iframe — your backend mints a short-lived scoped token and passes it to the client:

```python

client = miosa.Miosa(api_key="msk_u_...")

token = client.browser_tokens.create(
    scope="sandbox",
    resource_id="sbx_abc123",
    expires_in=3600,
)
# Pass token.value to the browser — never the msk_ key.
```

```typescript

const miosa = new Miosa({ apiKey: 'msk_u_...' });

const token = await miosa.browserTokens.create({
  scope: 'sandbox',
  resourceId: 'sbx_abc123',
  expiresIn: 3600,
});
// Pass token.value to the browser — never the msk_ key.
```

```bash
curl -X POST https://api.miosa.ai/api/v1/browser-tokens \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "sandbox",
    "resource_id": "sbx_abc123",
    "expires_in": 3600
  }'
```

Browser tokens expire, are non-renewable, and are scoped to a single resource. They cannot create new resources.

See [Authentication](/docs/authentication/) and [Browser Tokens](/docs/platform/browser-tokens/) for the full reference.

---

## 3. Ownership and external attribution

Every MIOSA resource accepts canonical ownership fields and optional attribution fields:

| Field | Meaning |
|---|---|
| `workspace_id` / `workspace_slug` | The MIOSA workspace that owns the resource |
| `project_id` / `project_slug` | The MIOSA project that owns the resource |
| `external_workspace_id` | Your customer's account / tenant ID |
| `external_user_id` | The end-user inside that account |
| `external_project_id` | The project or app ID in your own database |

MIOSA stores canonical `workspace_id` and `project_id` on each resource. The external fields are stored as opaque strings. Both appear on list/read responses, and list endpoints accept them as filters:

```python
# Create a sandbox attributed to a specific customer
sandbox = client.sandboxes.create(
    template_id="miosa-sandbox",
    workspace_slug="acme-co",
    workspace_name="Acme Co",
    project_slug="invoice-bot",
    project_name="Invoice Bot",
    external_workspace_id="acme-co",
    external_user_id="alice@acme.com",
    external_project_id="invoice-bot",
)

# List only sandboxes for that customer
sandboxes = client.sandboxes.list(
    workspace_id=sandbox.workspace_id,
)
```

```typescript
// Create
const sandbox = await miosa.sandboxes.create({
  templateId: 'miosa-sandbox',
  workspaceSlug: 'acme-co',
  workspaceName: 'Acme Co',
  projectSlug: 'invoice-bot',
  projectName: 'Invoice Bot',
  externalWorkspaceId: 'acme-co',
  externalUserId: 'alice@acme.com',
  externalProjectId: 'invoice-bot',
});

// Filter
const sandboxes = await miosa.sandboxes.list({
  workspaceId: sandbox.workspaceId,
});
```

```bash
# Create
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "miosa-sandbox",
    "workspace_slug": "acme-co",
    "workspace_name": "Acme Co",
    "project_slug": "invoice-bot",
    "project_name": "Invoice Bot",
    "external_workspace_id": "acme-co",
    "external_user_id": "alice@acme.com",
    "external_project_id": "invoice-bot"
  }'

# Filter
curl "https://api.miosa.ai/api/v1/sandboxes?workspace_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer msk_u_..."
```

Filtering is always scoped to your MIOSA organization. You cannot see another organization's resources regardless of what workspace, project, or external IDs you pass.

See [Ownership and Attribution](/docs/platform/attribution/) for the full filter spec and billing split by workspace/project.

---

## 4. The six resources

Every MIOSA operation creates, reads, updates, or destroys one of these six types.


    A mutable microVM where agents or developers build an app. Execute commands, read and write files, run dev servers, take snapshots.

    [Sandboxes →](/docs/develop/sandboxes/)


    A temporary public URL that tunnels to a port inside a running sandbox. Safe to embed in an iframe with a browser token.

    [Previews →](/docs/develop/previews/)


    The stable product object the world knows as "the live app." Holds an `active_version_id`. Publishing creates a new Version; rollback resets it.

    [Deploy overview →](/docs/deploy/overview/)


    An immutable snapshot of a built Release attached to a Deployment. Promoting a Version updates live traffic. Prior Versions stay available for rollback.

    [Versions →](/docs/deploy/versions/)


    A production microVM booted from a dynamic Release. The scheduler places, scales, and health-checks instances automatically.

    [Runtime Instances →](/docs/deploy/runtime-instances/)


    A DNS hostname routed to a Deployment's active Version. Supports MIOSA-managed subdomains and custom domains with auto-provisioned TLS.

    [Domains →](/docs/deploy/domains/)


The publish pipeline connects them in order:
```

Sandbox → Builder → Release → Version → Deployment → Domain
```

A Builder is an internal ephemeral VM that runs the build. You never address it directly.

---

## 5. Idempotency

Every mutation endpoint (`POST`, `PUT`, `PATCH`, `DELETE`) accepts an optional `Idempotency-Key` header. Retrying a request with the same key is safe — MIOSA returns the original response without re-executing the operation.
```http
POST /api/v1/sandboxes
Authorization: Bearer msk_u_...
Idempotency-Key: create-sandbox-for-alice-2026-05-17
Content-Type: application/json

{ "template_id": "miosa-sandbox", "external_user_id": "alice" }
```

Idempotency keys are:

- Scoped to your workspace and the endpoint path.
- Valid for **24 hours** from first use.
- Stored regardless of whether the original request succeeded or failed.

If the first request timed out before you received a response, retry with the same key. You will receive the original result if the operation completed, or a `202 Accepted` if it is still in progress.

Use a deterministic, collision-resistant key tied to your own business event — for example, `"create-sandbox-{your_request_id}"`. UUIDs or hash of the request body both work.

---

## 6. Rate limits

Rate limits apply per API key, per workspace, and per endpoint family. Every response includes quota headers:
```http
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1748390460
```

Default limits:

| Endpoint family | Limit | Window |
|---|---|---|
| `GET /api/v1/*` (reads) | 600 requests | Per minute per key |
| `POST /PUT /PATCH /DELETE /api/v1/*` (writes) | 300 requests | Per minute per key |
| Auth (`/auth/login`, `/auth/refresh`) | 60 requests | Per minute per IP |

When you exceed a limit, the API returns `429 Too Many Requests` with a `Retry-After` header containing the number of seconds until your quota resets.

High-volume workloads (AI agent pipelines creating many sandboxes per minute) can request a quota increase from the [platform dashboard](https://miosa.ai/dashboard/workspace/quota) or by contacting support.

---

## 7. Errors

All errors use a consistent envelope:
```json
{
  "error": {
    "code": "SANDBOX_NOT_FOUND",
    "message": "No sandbox with id sbx_abc123 exists in this workspace.",
    "request_id": "req_01hx9z..."
  }
}
```

| Field | Description |
|---|---|
| `code` | Machine-readable constant. Use this in your `switch` statements, not `message`. |
| `message` | Human-readable explanation. May change between API versions. |
| `request_id` | Include this when contacting support or filing a bug report. |

HTTP status codes map directly to error categories:

| Status | Category |
|---|---|
| `400` | Invalid request body or parameters |
| `401` | Missing or invalid credential |
| `403` | Valid credential, insufficient permissions |
| `404` | Resource not found (or not visible to your workspace) |
| `409` | Conflict — resource already exists, duplicate idempotency key with different body |
| `422` | Validation error — request parsed correctly but failed domain rules |
| `429` | Rate limited |
| `5xx` | MIOSA-side fault — safe to retry with exponential backoff |

The full error code catalog is in the [API Reference](/docs/api-reference/).

---

## 8. Events (SSE)

Several long-running operations stream progress over [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). The SSE stream for a resource is always at:
```

GET /api/v1/{resource-type}/{id}/events
```

Because the browser `EventSource` API does not support custom headers, SSE endpoints use a **one-time ticket** for authentication instead of the `Authorization` header:

```python
# 1. Mint a ticket (server-side)
ticket = client.sandboxes.sse_ticket(sandbox_id="sbx_abc123")

# 2. Open the stream

url = f"https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/events?ticket={ticket.value}"
with urllib.request.urlopen(url) as resp:
    for event in sseclient.SSEClient(resp):
        print(event.data)
```

```typescript
// 1. Mint a ticket (server-side)
const ticket = await miosa.sandboxes.sseTicket('sbx_abc123');

// 2. Open the stream (browser or Node)
const url = `https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/events?ticket=${ticket.value}`;
const source = new EventSource(url);
source.onmessage = (e) => console.log(JSON.parse(e.data));
```

```bash
# 1. Mint a ticket
TICKET=$(curl -s -X POST \
  https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/sse-ticket \
  -H "Authorization: Bearer msk_u_..." | jq -r '.ticket')

# 2. Stream events
curl -N "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/events?ticket=$TICKET"
```

Event types vary by resource. Common event shapes:
```jsonc
// Build log line
{ "type": "log", "stream": "stdout", "data": "Installing dependencies...", "ts": 1748390460 }

// Status change
{ "type": "status_changed", "previous": "building", "current": "ready", "ts": 1748390462 }

// Error
{ "type": "error", "code": "BUILD_FAILED", "message": "Exit code 1", "ts": 1748390465 }
```

See [Events (SSE) API Reference](/docs/api-reference/events/) for the complete event catalog per resource type.

---

## 9. Sandboxes vs Computers

Two products, one platform. Pick based on what your workflow needs:

| | Sandbox | Computer |
|---|---|---|
| Primary use | Code execution, file I/O, dev servers, agent build loops | Desktop GUI, browser automation, screen-driven agents |
| Display | Headless (no screen) | X11 + VNC stream |
| Accessibility tree | No | Yes |
| APIs | exec, file I/O, snapshots, previews | screenshot, click, type, keyboard, scroll |
| Lifecycle | Short-to-medium, auto-suspend on idle | Session-oriented |
| Typical agent task | "Write and deploy a FastAPI service" | "Fill out this web form", "navigate a GUI app" |

**Use a Sandbox** when your agent needs to write code, run shell commands, manage files, or serve a dev server.

**Use a Computer** when your agent needs to operate a graphical interface — a browser, a desktop app, or anything with a visible screen.

Both products live in the same organization, can be separated by workspace/project, and appear on the same billing account.

---

## What's next

---

# Integrating an AI agent

URL: https://miosa.ai/docs/guides/agent
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/guides/agent
Source: src/routes/docs/guides/agent/+page.md
Description: How to bring your own AI agent and drive MIOSA Sandbox or Computer primitives to build, run, and deploy applications autonomously.

# Integrating an AI agent

MIOSA provides the substrate — sandboxes, computers, file I/O, exec, previews, snapshots. You provide the agent loop: the LLM calls, screenshot decoding, planning, and turn management. This guide shows how to wire the two together.

---

## The pattern
Diagram:
sequenceDiagram
  participant Your Agent
  participant MIOSA API
  participant Sandbox

  Your Agent->>MIOSA API: create sandbox
  MIOSA API->>Sandbox: boot Firecracker VM
  Your Agent->>MIOSA API: files.write(path, content)
  Your Agent->>MIOSA API: exec("npm run build")
  MIOSA API-->>Your Agent: SSE events (stdout, stderr, status)
  Your Agent->>MIOSA API: previews.create(port=3000)
  MIOSA API-->>Your Agent: { url }

Your agent code owns the loop — choosing the LLM, formatting tool calls, interpreting results, deciding when to stop. MIOSA executes the actions your agent requests and streams back results.

---

## Sandbox integration

Sandboxes are the preferred substrate for code-generation agents. The agent writes files, runs build commands, and opens preview URLs — all through MIOSA primitives.

```python

client = miosa.Miosa(api_key="msk_u_...")

# Boot a sandbox with a Next.js environment
sbx = client.sandboxes.create("nextjs")

# Agent writes the code it generated
sbx.files.write("/workspace/app/page.tsx", agent_generated_code)

# Run the build
result = sbx.exec("npm run build")
if result.exit_code != 0:
    # Feed stderr back to the agent so it can debug
    agent.feedback(result.stderr)
else:
    # Open a live preview
    preview = sbx.previews.create(port=3000)
    print(f"Preview: {preview.url}")
```

```typescript

const client = new Miosa({ apiKey: 'msk_u_...' });

// Boot a sandbox
const sbx = await client.sandboxes.create({ templateId: 'nextjs' });

// Agent writes the generated file
await sbx.files.write('/workspace/app/page.tsx', agentGeneratedCode);

// Run the build
const result = await sbx.exec('npm run build');
if (result.exitCode !== 0) {
  agent.feedback(result.stderr);
} else {
  const preview = await sbx.previews.create({ port: 3000 });
  console.log('Preview:', preview.url);
}
```

The sandbox persists between turns — files written in turn 1 are still there in turn 5. The agent does not need to re-send context on every call.

---

## Computer integration

Computers are full Linux desktop VMs with screenshot, click, type, and keyboard APIs. Use them when your agent needs to operate a graphical interface.

```python

client = miosa.Miosa(api_key="msk_u_...")

computer = client.computers.create(template="ubuntu-desktop")
computer.start()

# Screenshot → reason → act loop (your agent drives this)
while not done:
    png = computer.screenshot()
    action = agent.next_action(png)

    if action.type == "click":
        computer.left_click(action.x, action.y)
    elif action.type == "type":
        computer.type_text(action.text)
    elif action.type == "key":
        computer.key(action.combo)  # e.g. "ctrl+t", "enter"
    elif action.type == "scroll":
        computer.scroll(action.x, action.y, action.direction)
    elif action.type == "done":
        done = True

computer.stop()
```

```typescript

const client = new Miosa({ apiKey: 'msk_u_...' });

const computer = await client.computers.create({ template: 'ubuntu-desktop' });
await computer.start();

let done = false;
while (!done) {
  const png = await computer.screenshot();
  const action = await agent.nextAction(png);

  switch (action.type) {
    case 'click':
      await computer.leftClick(action.x, action.y);
      break;
    case 'type':
      await computer.typeText(action.text);
      break;
    case 'key':
      await computer.key(action.combo);
      break;
    case 'done':
      done = true;
      break;
  }
}

await computer.stop();
```

---

## State tracking

Your agent code is responsible for keeping turn history, screenshots, and decisions. MIOSA executes discrete actions — it does not maintain an agent loop or conversation state on your behalf.

A managed agent loop with built-in turn history and LLM orchestration is on the MIOSA roadmap. Today, state management lives in your application layer.

A minimal turn-log pattern:
```python
turns = []

while not done:
    png = computer.screenshot()
    action = agent.next_action(png, history=turns)
    turns.append({"screenshot": png, "action": action})

    # Execute action on the computer...
```

---

## Approval workflows

If your workflow requires human review before an action executes, your agent pauses and asks the user. MIOSA does not gate actions — all approval logic lives in your application.
```python
action = agent.next_action(png)

if action.requires_approval:
    approved = ask_user(f"Approve: {action.description}?")
    if not approved:
        agent.cancel(action)
        continue

computer.left_click(action.x, action.y)
```

---

## Streaming events

Subscribe to the sandbox or computer event stream to receive real-time progress without polling:

```python
# Sandbox events
for event in sbx.events.stream():
    if event.type == "sandbox.exec.stdout":
        print(event.data["line"])
    elif event.type == "sandbox.exec.completed":
        print(f"Exit code: {event.data['exit_code']}")
        break

# Computer events
for event in computer.events.stream():
    if event.type == "computer.stopped":
        print("Computer stopped:", event.data["reason"])
        break
```

```typescript
// Sandbox events
for await (const event of sbx.events.stream()) {
  if (event.type === 'sandbox.exec.stdout') {
    process.stdout.write(event.data.line);
  } else if (event.type === 'sandbox.exec.completed') {
    console.log('Exit code:', event.data.exit_code);
    break;
  }
}
```

See [Events (SSE) reference →](/docs/api-reference/events/) for the full event catalog.

---

## Best practices

- **Use `Idempotency-Key` on every action.** If your agent retries a failed request, the idempotency key prevents duplicate execution. Generate a key tied to your turn ID: `"turn-{turn_number}-{action_type}"`.
- **Cap `max_turns` in your agent loop.** A runaway agent loop can exhaust credits. Set a hard ceiling and surface the failure cleanly to the user.
- **Record screenshots and decisions.** Persist each turn's screenshot and the action taken. When an agent makes a bad decision, this record lets you replay and diagnose without re-running the whole task.
- **Use snapshots between turns.** Call `sbx.snapshots.create()` at stable checkpoints. If a later turn corrupts state, restore from snapshot rather than starting from scratch.
- **Prefer sandbox exec over computer desktop for code tasks.** File I/O and shell commands through the sandbox API are more reliable and faster than typing into a terminal window on a desktop.

---

## Examples


    An agent that generates and deploys a static site end-to-end.

    [View on GitHub →](https://github.com/Miosa-osa/miosa/tree/main/examples/agent-builds-static-app)


    Full Python and TypeScript SDK method signatures for sandboxes and computers.

    [SDK reference →](/docs/sdk/)

---

# MCP server

URL: https://miosa.ai/docs/guides/mcp
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/guides/mcp
Source: src/routes/docs/guides/mcp/+page.md
Description: Install and configure the MIOSA MCP server to drive sandboxes and computers from Claude Code, Cursor, Windsurf, and any other MCP-compatible client.

# MCP server

The MIOSA MCP (Model Context Protocol) server exposes 25 tools that let AI coding assistants create sandboxes, run commands, write files, take computer screenshots, and more — all without leaving the editor. The server speaks the MCP transport protocol, so any compliant client can drive it.

---

## How it works
Diagram:
sequenceDiagram
  participant Editor as Editor (Claude Code / Cursor)
  participant MCP as MIOSA MCP Server
  participant API as MIOSA API
  participant Sandbox

  Editor->>MCP: list_tools()
  MCP-->>Editor: 25 tool definitions
  Editor->>MCP: call_tool("sandbox_create", { template: "nextjs" })
  MCP->>API: POST /api/v1/sandboxes
  API->>Sandbox: boot Firecracker VM
  API-->>MCP: { id, status }
  MCP-->>Editor: { sandboxId: "sbx_..." }
  Editor->>MCP: call_tool("sandbox_exec", { id, command: "npm run build" })
  MCP->>API: POST /api/v1/sandboxes/:id/exec
  API-->>MCP: { stdout, stderr, exit_code }
  MCP-->>Editor: stdout + stderr

The MCP server is a thin stateless proxy. Your API key travels with every request; the server never stores credentials.

---

## Installation

### npx (no install)
```bash
npx @miosa/mcp
```

### Global install
```bash
npm install -g @miosa/mcp
miosa-mcp --version
```

### From source
```bash
git clone https://github.com/Miosa-osa/mcp-server
cd mcp-server && npm install && npm run build
node dist/index.js
```

---

## Configuration

### Claude Code

Add to `~/.claude/mcp.json` (or `claude mcp add` if your version supports it):
```json
{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/mcp"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

Restart Claude Code. The MIOSA tools appear in the tool picker automatically.

### Cursor

Open **Cursor → Settings → MCP** and add:
```json
{
  "miosa": {
    "command": "npx @miosa/mcp",
    "env": { "MIOSA_API_KEY": "msk_u_..." }
  }
}
```

### Windsurf

In `~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/mcp"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

Reload Windsurf. Tools are available in the Cascade panel.

### Environment variable reference

| Variable | Required | Default | Description |
|---|---|---|---|
| `MIOSA_API_KEY` | Yes | — | Your `msk_u_...` key |
| `MIOSA_API_URL` | No | `https://api.miosa.ai` | Override for self-hosted or staging |
| `MIOSA_DEFAULT_TEMPLATE` | No | `miosa-sandbox` | Template used when `sandbox_create` omits `template` |
| `MIOSA_TIMEOUT_MS` | No | `30000` | Per-request HTTP timeout in milliseconds |
| `MIOSA_LOG_LEVEL` | No | `warn` | `debug`, `info`, `warn`, `error` |

---

## Tool catalog (25 tools)

### Sandbox lifecycle

| Tool | Description |
|---|---|
| `sandbox_create` | Boot a new sandbox. Accepts `template`, `external_workspace_id`, `external_project_id`. |
| `sandbox_get` | Get sandbox status, IP, template, created_at. |
| `sandbox_list` | List sandboxes. Filterable by `external_workspace_id`, `status`. |
| `sandbox_stop` | Stop a running sandbox (VM paused, not destroyed). |
| `sandbox_destroy` | Permanently destroy a sandbox and release compute. |
| `sandbox_resume` | Resume a stopped sandbox from its last state. |

### File I/O

| Tool | Description |
|---|---|
| `file_write` | Write a file at an absolute path inside the sandbox. Creates parent directories. |
| `file_read` | Read a file. Returns content as a string. |
| `file_list` | List directory contents. Accepts `recursive` flag. |
| `file_delete` | Delete a file or directory. |
| `file_move` | Rename or move a file within the sandbox. |

### Execution

| Tool | Description |
|---|---|
| `sandbox_exec` | Run a shell command. Returns `stdout`, `stderr`, `exit_code`. |
| `sandbox_exec_stream` | Run a command and stream output as SSE events. |
| `sandbox_exec_background` | Run a command in the background. Returns a `job_id` for status polling. |
| `sandbox_job_status` | Poll a background job by `job_id`. |

### Previews

| Tool | Description |
|---|---|
| `preview_create` | Expose a sandbox port as a public HTTPS URL. |
| `preview_list` | List active previews for a sandbox. |
| `preview_destroy` | Tear down a preview URL. |

### Snapshots

| Tool | Description |
|---|---|
| `snapshot_create` | Snapshot the current sandbox state. |
| `snapshot_restore` | Restore a sandbox to a named snapshot. |
| `snapshot_list` | List snapshots for a sandbox. |

### Computers

| Tool | Description |
|---|---|
| `computer_create` | Boot a Linux desktop VM. Accepts `template` (`ubuntu-desktop`, `windows-11`). |
| `computer_screenshot` | Take a screenshot. Returns a base64-encoded PNG. |
| `computer_action` | Execute a desktop action: `click`, `type`, `key`, `scroll`, `double_click`. |
| `computer_stop` | Stop a desktop VM. |

---

## Usage examples

### Create a sandbox and run a build
```
You: Create a Next.js sandbox and install dependencies.
```
The assistant calls `sandbox_create({ template: "nextjs" })`, then `sandbox_exec({ command: "npm install" })` and streams back the output.

### Write a file and preview it
```
You: Write this React component to /workspace/app/page.tsx and open a preview.
```
The assistant calls `file_write`, then `sandbox_exec({ command: "npm run dev" })`, then `preview_create({ port: 3000 })` and returns the preview URL.

### Screenshot → fix loop
```
You: Open the browser in the Ubuntu desktop and screenshot what's on screen.
```
The assistant calls `computer_create`, `computer_screenshot`, describes what it sees, then calls `computer_action` to interact.

### Multi-turn file editing
```
You: The build failed. Check the error and fix the TypeScript types.
```
The assistant calls `sandbox_exec({ command: "npm run build" })`, reads the output, calls `file_read` on the failing file, patches it with `file_write`, and re-runs the build — all without leaving the conversation.

---

## Troubleshooting

Set `MIOSA_LOG_LEVEL=debug` to see every request and response the MCP server sends to the MIOSA API. Useful for diagnosing auth or timeout issues.

**`MIOSA_API_KEY is not set`** — The env var is missing from your MCP config. Confirm the `env` block is present in your client's MCP JSON and that the key starts with `msk_u_`.

**Tool calls timeout** — Sandbox boots take 2–8 s on first call. Increase `MIOSA_TIMEOUT_MS` if your client has a short MCP timeout. Claude Code default is 30 s; Cursor default is 10 s.

**`403 Unauthorized`** — Your key is valid but lacks the required scope. Check [API Keys](/docs/platform/api-keys/) to confirm the key has `sandboxes:write` and `computers:write` scopes.

**`No tools appear in Cursor`** — Cursor requires the MCP config to be valid JSON. Run `node -e "JSON.parse(require('fs').readFileSync('~/.codeium/windsurf/mcp_config.json','utf8'))"` to validate.

---

## Security considerations

- Store `MIOSA_API_KEY` in your client's secret store, not in a `.env` file committed to git.
- Use a **scoped key** for MCP: grant only `sandboxes:write`, `computers:write`, `files:write`. Never use an admin key for editor integrations.
- The MCP server makes outbound HTTPS requests only. It never opens inbound ports.
- Sandboxes created through MCP are subject to the same tenant-scoped authorization as API calls. The MCP server cannot access another tenant's resources.

---

## See also


    Drive sandboxes and computers from your own agent loop — outside an editor.

    [Agent guide →](/docs/guides/agent)


    Full Python and TypeScript SDK method signatures.

    [SDK reference →](/docs/sdk/)

---

# Known Limitations

URL: https://miosa.ai/docs/known-limitations
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/known-limitations
Source: src/routes/docs/known-limitations/+page.md
Description: An honest list of what doesn't work yet, what's in progress, and what's intentionally out of scope. Updated continuously.

# Known Limitations

We document what doesn't work, on purpose. If you hit something here, it isn't a bug in your code — it's a known gap. Each item notes the status or planned ship window.

Last updated: 2026-05-17. We update this page on every release.

## Sandboxes Ships next: regional warm pools

- **Cold boot for the first sandbox per region**: ~600 ms outside the warm pool window. Regional warm pools will close this gap in Q3 2026.
- **No GPU sandboxes yet**. GPU is available on Computers (Desktop) only via BYOC. Native GPU sandboxes are targeted for early 2027.
- **Snapshot size cap**: 8 GB compressed. Larger workloads should use a volume mount.
- **No nested virtualization**: you cannot run KVM or QEMU inside a sandbox. Docker-in-Docker works fine.
- **`msk_test_*` keys are not yet live**. All keys hit the billable production substrate. Test-mode billing isolation is on the roadmap.

## Deployments Phase 3/4 complete; dynamic runtime in hardening

- **Custom domain apex records require ALIAS / ANAME** — DNS providers that do not support flattening (e.g., GoDaddy) require a workaround. Native anycast nameservers are planned for Q4 2026.
- **No edge functions yet** — only origin compute. Edge runtime is targeted for Q1 2027.
- **Rollback is per-deployment, not per-route** — you cannot pin one URL path to version 1 and another to version 2 within the same deployment.
- **Dockerfile / BuildKit builds are fail-closed**. The builder pipeline supports static packager and dynamic slug modes today. OCI-rootfs build strategy is pending.
- **Railpack / Nixpacks framework detection** exists but dynamic generation from buildpacks is not complete.

## Data Services

- **Managed Postgres** Beta — provisioning lifecycle exists; per-project automatic credential injection is completing as part of Phase 6 hardening. PgBouncer connection pooling and off-box backup drills are in progress.
- **Redis** Beta — single-node only. Multi-zone replication is planned.
- **Object Storage** Beta — S3-compatible API is live; pre-signed browser uploads work. CDN distribution and geo-replication rollout are operational work in progress.
- **Auth-as-a-Service** Planned — not generally available. Bring your own auth provider (Clerk, Auth0, or self-hosted) for now. See [Auth-as-a-Service](/docs/data/auth/) for the target API shape.
- **Volumes** Planned — sandbox-local `/workspace` works today; persistent volumes attached to runtime instances are planned. Use Postgres or Object Storage for most persistence needs until then.
- **Usage / audit query views grouped by `external_workspace_id`** are not yet exposed. Raw audit events exist; cross-workspace aggregation rolls out in a later phase.

## Computers (Desktop) GA

- **Headed-only**: no headless mode for Computers — you boot a real Xfce desktop. For headless workloads, use Sandboxes.
- **Browser cookies do not persist** across sessions by default. Use a volume mount or browser profile snapshot to carry cookies across reboots.
- **No multi-monitor virtualization**. Single 1920 × 1080 frame buffer.
- **Audio not exposed**. The stream is video-only; system audio is dropped at the host.

## Computer-Use API

- **No managed agent loop** — you bring your own agent (Anthropic SDK, OpenAI computer-use API, or custom). A built-in `computer.prompt()` convenience will ship when the hosted Optimal session endpoint is publicly available.
- **Approval gating is not enforced server-side** — the approve / reject action protocol is a client-side convention only. Gate sensitive operations in your own agent code.
- **Computer sub-resources** (auto_stop, vnc_credentials, apps, stream_token, metrics, ports, volume attach/detach, clone) have full coverage in the Python SDK. TypeScript, Go, and Java parity is targeted Q3 2026.

## SDKs

| SDK | P1 + P2 resources | P3 / P4 resources | Computer depth |
|---|---|---|---|
| Python | Full | Full | Full |
| TypeScript | Full | Partial | Partial |
| Go | Full | Not yet | Partial |
| Java | Full | Not yet | Partial |
| Elixir | Full | Not yet | Partial |

- **`embeddings`, `provider_defaults`, `benchmarks`, `command_center`, `community`, `email`, `builder_sessions`, `snapshots_standalone`** are Python-only today. Other SDK languages are pending.
- **Python sync client uses long-poll fallback** for streaming events. Use the async client or the TypeScript SDK for proper SSE.
- **Tab-synced language preference** persists in `localStorage`, not your user account. Switching language on one device does not propagate to another.
- **`workspaces` and `credits`** resources are absent from the TypeScript SDK. Present in all others.

## API

- **No GraphQL endpoint**. REST + SSE by design.
- **Webhook delivery retries cap at 24 hours** — after that, the event is dropped. Use the audit log to backfill missed events.
- **Rate limits**: 600 requests per minute per workspace, 60 rpm per endpoint group. Higher limits are available on request.
- **Browser tokens have a fixed 5-minute TTL** — refresh server-side; do not attempt client-side extension.
- **One sandbox per browser token** — a single token cannot scope across multiple sandboxes.

## Pricing and Billing

- **No per-tenant usage budgets yet** — you set a workspace cap today; tenant-level caps tied to `external_workspace_id` roll out with the billing attribution extension.
- **Test-mode keys (`msk_test_*`) are not yet live**. All traffic is billable.

## Observability

- **No native log aggregation across workspaces** — query per-resource today. Cross-workspace log search is planned.
- **No OTLP trace export yet**. The `/events` SSE streams provide raw events; bring your own collector. Structured OTLP export is on the roadmap.

## What We Are Explicitly Not Building

- **Managed Kubernetes**. Sandboxes and Deployments cover the workloads people would otherwise use K8s for.
- **Generic VPS hosting**. Compute is always tied to a tenant identity (workspace or `external_workspace_id`).
- **Cryptocurrency or blockchain primitives**.

## See Also

- [Changelog](/docs/changelog/) — what we just shipped
- [Concepts](/docs/concepts/) — the resource model
- Contact platform@miosa.ai if a limitation here is blocking you — we prioritize the roadmap by demand.

---

# API Keys

URL: https://miosa.ai/docs/platform/api-keys
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/api-keys
Source: src/routes/docs/platform/api-keys/+page.md
Description: Workspace API keys — the one credential your backend uses for every MIOSA call.

A **Workspace API Key** authenticates your backend to MIOSA. One key per workspace; the key resolves to a tenant_id, scopes, and rate limits.

## Create a key

From the dashboard: **Workspace → Settings → API Keys → New key**. Or via API:
```http
POST /api/v1/api-keys
```

```typescript
const key = await miosa.apiKeys.create({
  name: "ClinicIQ backend prod",
  scopes: ["deployments:write", "sandboxes:write", "domains:write"],
})

console.log(key.token)  // shown ONCE — store it now
// → msk_live_a1b2c3d4...
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

key = miosa.api_keys.create(
    name="ClinicIQ backend prod",
    scopes=["deployments:write", "sandboxes:write", "domains:write"],
)

print(key["token"])  # shown ONCE — store it now
# → msk_live_a1b2c3d4...

# List all keys (tokens are NOT shown in list responses)
for k in miosa.api_keys.list():
    print(k["id"], k["name"])

# Revoke a key
miosa.api_keys.delete(key["id"])
```

The plaintext `msk_*` value is returned **exactly once** at creation. The dashboard shows only a prefix (first 12 chars) thereafter; the server stores only a hash.

If you lose a key, rotate — create a new one, swap it in, delete the old.

## Key shape
```

msk_<env>_<random>
```

- `msk_live_*` — production keys, full access.
- `msk_test_*` — test-mode keys (planned; usage doesn't count toward billing).
- `msk_u_*` — user-bound keys for personal CLI use; scopes limited to the user's own resources.

For platform integration (ClinicIQ-style), use `msk_live_*` and treat it like a Stripe secret key.

## Scopes

Each key has a list of scopes. MIOSA enforces scopes on every mutation. Reads typically require the matching `:read` scope; writes require `:write`.

Common scopes:

| Scope | Allows |
|---|---|
| `sandboxes:read` | List, get sandboxes |
| `sandboxes:write` | Create, exec, files.write, destroy |
| `deployments:read` | List, get deployments, versions, domains |
| `deployments:write` | Create, publish, rollback, attach domains |
| `domains:write` | Create, verify, delete custom domains |
| `data:write` | Provision managed Postgres / Redis / buckets |
| `usage:read` | Read usage events |
| `audit:read` | Read audit log |

For server-side platform integration, start with `sandboxes:write` + `deployments:write` + `domains:write`. Add more as needed. Principle of least privilege: don't give a key `*:write` unless that's what it actually needs to do.

## Rotation

Rotate keys on a schedule (we recommend every 90 days, or on incident). The flow:

1. Create a new key with the same scopes.
2. Roll out the new key to your backend (deploy + restart).
3. Confirm the new key works (recent activity logged with `key_id` of the new key).
### 4. Delete the old key

```typescript
// Step 1: create
const newKey = await miosa.apiKeys.create({ name: "...", scopes: [...] })

// Step 2-3: deploy, confirm.

// Step 4: revoke old
await miosa.apiKeys.delete(oldKeyId)
```

```python
# Step 1: create
new_key = miosa.api_keys.create(name="...", scopes=[...])

# Step 2-3: deploy, confirm.

# Step 4: revoke old
miosa.api_keys.delete(old_key_id)
```

Deleting a key invalidates it immediately. Any in-flight requests using the old key will start getting 401.

## Rate limits

Each key has a rate limit (request-per-minute) scoped by:

- Key ID (the key's own bucket)
- Organization (the account's overall bucket)
- Endpoint (publish has its own bucket, separate from list operations)

Limits scale with the plan. Headers in every response tell you where you stand:
```

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 547
X-RateLimit-Reset: 1715712060
```

429 responses include a `Retry-After` header. SDKs back off automatically.

## Audit

Every action authenticated by a key emits an audit event with:

- `api_key_id` (so you know which key did what)
- `actor` (the organization, plus the key's name)
- `workspace_id`, `project_id`, `external_workspace_id`, `external_user_id` (if passed or resolved in the request)
- The action (e.g. `deployments.publish`, `domains.create`)
- Timestamp + outcome

Read your audit log via:
```http
GET /api/v1/audit?api_key_id=key_...
GET /api/v1/audit?workspace_id=550e8400-e29b-41d4-a716-446655440000
```

## Browser keys (no)

There is no such thing as a browser-safe `msk_*`. If you need a browser to call MIOSA-like functionality, mint a scoped browser token server-side. See [Browser Tokens](/docs/platform/browser-tokens/).

Unlike Stripe, MIOSA does NOT issue separate `pk_*` publishable keys. Every MIOSA key is a server-side secret. If a third-party SDK or doc tells you to "just use the publishable key in the browser," that's not a MIOSA pattern — they're probably using a scoped browser token.

## See also

- [Attribution](/docs/platform/attribution/) — the IDs your API key carries on each call
- [Browser Tokens](/docs/platform/browser-tokens/) — for end-user-facing access
- [Authentication](/docs/authentication/) — the wider auth model (JWT for sessions, etc.)

---

# Resource Ownership and Attribution

URL: https://miosa.ai/docs/platform/attribution
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/attribution
Source: src/routes/docs/platform/attribution/+page.md
Description: Scope resources to MIOSA workspaces and projects while preserving your own workspace / user / project IDs for billing and reconciliation.

Resource ownership is how MIOSA decides where a resource lives. External attribution is how your platform maps that resource back to your own database.

- `workspace_id` and `project_id` are canonical MIOSA ownership. They affect routing, permissions, dashboard grouping, usage, and where resources appear.
- `external_workspace_id`, `external_user_id`, and `external_project_id` are opaque strings from your platform. They are copied to usage, audit, and child resources for reconciliation.

## Ownership fields

| Field | Meaning | Example |
|---|---|---|
| `workspace_id` | Existing MIOSA workspace UUID | `"550e8400-e29b-41d4-a716-446655440000"` |
| `workspace_slug` | Existing or auto-created workspace slug | `"dr-smith-clinic"` |
| `workspace_name` | Workspace display name when auto-created | `"Dr. Smith Clinic"` |
| `project_id` | Existing MIOSA project UUID | `"660e8400-e29b-41d4-a716-446655440001"` |
| `project_slug` | Existing or auto-created project slug inside the workspace | `"lead-magnet"` |
| `project_name` | Project display name when auto-created | `"Lead Magnet"` |

If no workspace selector is supplied, MIOSA uses the organization's default workspace. If no project selector is supplied, MIOSA uses or creates a `default` project inside that workspace.

When you pass `external_workspace_id` or `external_project_id` without a canonical ID/slug, MIOSA resolves the matching workspace/project or creates one for this organization. The response includes `workspace_id` and `project_id`; store those IDs and use them on future calls when possible.

## Attribution fields

| Field | Meaning | Example |
|---|---|---|
| `external_workspace_id` | Your customer/workspace/account ID | `"clinic_123"` |
| `external_user_id` | Your end-user ID inside that customer | `"dr-smith-456"` |
| `external_project_id` | Your project ID inside that workspace | `"project_789"` |

All three are optional, stored as text, and scoped to the authenticated MIOSA organization. They never grant access.

## How it flows
Diagram:
sequenceDiagram
    participant P as Platform backend
    participant M as MIOSA API
    participant U as Usage records
    participant B as Billing / chargeback

    P->>M: POST /sandboxes<br/>workspace_slug: dr-smith-clinic<br/>project_slug: lead-magnet<br/>external_workspace_id: clinic_123
    M-->>P: sandbox with workspace_id + project_id
    M->>U: usage event with canonical ownership + external IDs
    P->>M: GET /usage?workspace_id=...
    M-->>P: { total_usd: 4.20, line_items: [...] }
    P->>B: charge clinic_123 accordingly

## On every create

Pass ownership and attribution in the request body of create calls:

```typescript
await miosa.sandboxes.create({
  templateId: "miosa-sandbox",
  workspaceSlug: "dr-smith-clinic",
  workspaceName: "Dr. Smith Clinic",
  projectSlug: "lead-magnet",
  projectName: "Lead Magnet",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  externalProjectId: "project_789",
})
```

```typescript
await miosa.computers.create({
  template: "ubuntu-desktop",
  workspaceId: "550e8400-e29b-41d4-a716-446655440000",
  projectId: "660e8400-e29b-41d4-a716-446655440001",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  externalProjectId: "records_portal",
})
```

```typescript
await miosa.deployments.publish({
  sourceSandboxId: sandbox.id,
  workspaceId: sandbox.workspaceId,
  projectId: sandbox.projectId,
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  externalProjectId: "project_789",
})
```

```typescript
await miosa.deployments.domains.add(deploymentId, {
  domain: "program.drsmithclinic.com",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
})
```

Canonical ownership and attribution are stored on the resource row and on every event / audit / usage record produced from that resource.

## Filter by ownership or attribution

List endpoints accept canonical ownership filters and external attribution filters:
```http
GET /api/v1/sandboxes?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/sandboxes?project_id=660e8400-e29b-41d4-a716-446655440001
GET /api/v1/computers?external_project_id=records_portal&status=running
GET /api/v1/deployments?external_user_id=dr-smith-456
GET /api/v1/deployments/:id/domains?external_project_id=project_789
```

Filters are organization-scoped server-side. Another MIOSA organization cannot read your resources by guessing the same `workspace_id`, `project_id`, slug, or external ID.

## Inheritance

When a resource is derived from another, ownership and attribution are inherited by default:

- sandbox to preview
- sandbox to deployment
- deployment to build, version, service, release, runtime instance, and domain
- project to database, storage bucket, volume, function, cron job, auth, and integration
- computer to custom domain, usage records, and audit events

```typescript
const sandbox = await miosa.sandboxes.create({
  workspaceSlug: "dr-smith-clinic",
  projectSlug: "lead-magnet",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
})

const deployment = await miosa.deployments.publish({
  sourceSandboxId: sandbox.id,
})

console.log(deployment.workspace_id) // same as sandbox.workspace_id
console.log(deployment.project_id) // same as sandbox.project_id
```

Explicit values on the descendant request override inherited external IDs. Canonical project/workspace IDs must still belong to the authenticated organization.

## Authorization vs ownership vs attribution

Critical distinction:

- **Authorization** is the MIOSA organization. It is derived server-side from your API key or JWT.
- **Ownership** is `workspace_id` and `project_id`. It controls where resources live, but must belong to the authenticated organization.
- **Attribution** is `external_*`. It never authorizes anything. It only groups and filters inside the organization.

If you're building authorization in your own app, check your authenticated app user and the MIOSA organization first. Treat `external_*` as labels for billing, display, and reconciliation.

## Storage and indexing

Ownership and attribution are stored on:

- **Resource tables**: computers, sandboxes, sandbox previews, deployments, deployment versions, deployment builds, deployment environments, deployment services, deployment releases, runtime instances, service bindings, custom domains, databases, storage buckets, volumes, edge functions, cron jobs, preview environments, project auth, and project integrations.
- **Event tables**: usage meters, usage records, sandbox runtime events, and audit events.

Ownership filters are indexed by `tenant_id`, `workspace_id`, and `project_id`. Attribution filters are indexed by `tenant_id` plus the external ID field.

## What to use vs leave null

- Use `workspace_id` / `project_id` when you have already stored MIOSA IDs.
- Use `workspace_slug` / `project_slug` for human-readable integration code.
- Use `external_workspace_id` and `external_project_id` when your own database already has customer/project IDs.
- Use `external_user_id` when one end user triggered the action.

For white-label platforms, the best default is to pass canonical ownership and all three external IDs.

## See also

- [Overview](/docs/platform/overview/) — the white-label model
- [API Keys](/docs/platform/api-keys/) — the credential that ties requests to an organization
- [Browser Tokens](/docs/platform/browser-tokens/) — for end-user-facing access
- [White-label Setup](/docs/platform/white-label/) — domains, branding, and setup order
- [Usage & Billing](/docs/platform/usage-and-billing/) — chargeback by workspace/project

---

# Browser Tokens

URL: https://miosa.ai/docs/platform/browser-tokens
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/browser-tokens
Source: src/routes/docs/platform/browser-tokens/+page.md
Description: Short-lived scoped credentials your backend mints for end-user-facing access. Never expose `msk_*` to the browser.

When your end-user's browser needs direct MIOSA access — previewing a sandbox, opening a terminal, uploading a file — mint a short-lived browser token server-side and hand only that to the browser. The workspace API key (`msk_*`) never leaves your backend.

## The mint flow

Diagram:
sequenceDiagram
    participant BR as Browser
    participant BE as Your Backend
    participant MI as MIOSA

    BR->>BE: show preview
    BE->>MI: POST /previews/:id/share (msk_* key)
    MI-->>BE: preview_token + share_url
    BE-->>BR: share_url
    BR->>MI: GET share_url (token in query)
    MI->>MI: validate token, check scope + expiry
    MI-->>BR: preview content

## The pattern
```

[end user browser]                [your backend]                    [MIOSA]
        │                                 │                              │
        │  "show me my live preview"      │                              │
        ├────────────────────────────────►│                              │
        │                                 │                              │
        │                                 │  msk_*  +  preview ID        │
        │                                 ├─── POST .../preview/share ──►│
        │                                 │                              │
        │                                 │◄──── preview_token (raw) ────│
        │                                 │                              │
        │  share_url (with token)         │                              │
        │◄────────────────────────────────│                              │
        │                                 │                              │
        │  iframe.src = share_url         │                              │
        │  GET that URL ─────────────────────────────────────────────────►│
        │                                 │                              │
        │  preview content                                              │
        │◄──────────────────────────────────────────────────────────────│
```

The token is resource-bound (one preview), short-lived (configurable; default 1 hour), and never grants access to anything beyond the resource it was minted for.

## Preview share tokens (the main one)

The most common browser-facing flow.

```typescript
// Inside your authenticated request handler
const share = await miosa.sandboxes.previews.share(previewId, {
  expiresInSec: 3600,
})

res.json({
  share_url: share.share_url,
  expires_at: share.data.share_token_expires_at,
})
```

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/previews/$PREVIEW/share \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -d '{"expires_in_sec": 3600}'
```

Response:
```json
{
  "data": {
    "id": "preview_...",
    "share_token_prefix": "first12chars",
    "share_token_expires_at": "2026-05-14T19:30:00Z"
  },
  "preview_token": "miosa_pv_<one-time-raw-token>",
  "share_url": "https://abc12345.preview.miosa.app?preview_token=miosa_pv_<one-time-raw-token>"
}
```

Front-end:
```jsx
// React example
<iframe
  src={shareUrl}
  sandbox="allow-same-origin allow-scripts allow-forms"
  className="w-full h-[600px] border-0"
/>
```

The token authenticates the request at MIOSA's edge proxy. The proxy strips the credential before forwarding to your dev server on the sandbox — your application code never sees it.

## Token formats

| Use case | Where it goes | Lifetime |
|---|---|---|
| Preview share | `?preview_token=...` query string | configurable (default 1h, max 24h) |
| Terminal session | `wss://...?token=...` WebSocket query | typically 5-30m |
| Upload session | `Authorization: Bearer miosa_up_...` | minutes |
| Generic resource token | TBD | scoped per resource |

All formats are JWTs signed by MIOSA. The payload includes the resource ID, scopes, expiry, and an HMAC the proxy verifies. You can decode them client-side to inspect the expiry but you cannot forge them.

## Lifetime and expiry
```typescript
const share = await miosa.previews.share(previewId, {
  expiresInSec: 3600, // 1 hour
})
```

Plans have a max TTL (default 24 hours). Longer TTL means more risk if a token leaks; for browser embedding 1-3 hours is typical.

After expiry the preview returns 401. Your frontend should:

1. Watch `share.data.share_token_expires_at`.
2. Mint a new token before expiry by re-calling your backend.
3. Reload the iframe with the new `share_url`.

## Re-minting and revoking

A preview can have **multiple active share tokens** at the same time. Minting a new one does not invalidate previous ones.

To revoke all tokens for a preview, hit:
```http
DELETE /api/v1/sandboxes/:id/previews/:preview_id/share
```

This invalidates every outstanding share token for the preview. Useful for "I accidentally shared this externally, kill all browser access immediately."

## CSP and embedding

MIOSA's preview proxy emits `Content-Security-Policy` headers that allow the preview to be embedded as an iframe under specific origins. By default:

- `*.miosa.app`
- `*.miosa.ai`
- `localhost:4000` (for local dev of MIOSA frontend)

For white-label embedding (your platform served at `app.cliniciq.com` embedding MIOSA previews), the CSP needs to include your origin. Contact support to configure the proxy CSP per tenant.

## Audit

Every token issuance emits an audit event:
```json
{
  "action": "preview.share_token.issued",
  "resource_id": "preview_...",
  "actor": "api_key:msk_live_...",
  "metadata": {
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_id": "660e8400-e29b-41d4-a716-446655440001",
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "expires_at": "2026-05-14T19:30:00Z",
    "token_prefix": "miosa_pv_xyz"
  }
}
```

`token_prefix` lets you correlate audit events to log entries without storing the raw token.

## What browser tokens cannot do

- Cannot make MIOSA API calls (sandboxes.create, deployments.publish, etc.). They're proxy-only.
- Cannot escalate to a different resource. A preview token for `preview_A` cannot read `preview_B`.
- Cannot cross tenants.
- Cannot persist past expiry. A revoked or expired token is permanently dead.

If you need broader browser-side access (e.g. a developer dashboard your end users log into), use a full MIOSA user session (JWT) instead. See [Authentication](/docs/authentication/).

The raw token grants iframe access. Treat it like a session cookie — don't log it server-side or pass it through analytics tools. The `share_token_prefix` is safe to log.

## See also

- [Previews](/docs/develop/previews/) — the resource these tokens grant access to
- [API Keys](/docs/platform/api-keys/) — server-side credential the backend uses to mint
- [Attribution](/docs/platform/attribution/) — what gets logged in audit events

---

# Platform / White-label

URL: https://miosa.ai/docs/platform/overview
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/overview
Source: src/routes/docs/platform/overview/+page.md
Description: Build your own AI app builder on top of MIOSA with organization, workspace, project, resource ownership, custom domains, and short-lived browser tokens.

This section is for **builders** — platforms that embed MIOSA so their customers can build, preview, and deploy apps inside the builder's own product (AI app builders, white-label SaaS).

If you're a developer using MIOSA to ship your own app, read [Quickstart](/docs/quickstart/) Track A instead.

## What is the white-label model?

MIOSA lets one organization act as a platform for many downstream customers without giving those customers MIOSA accounts. Your backend holds a server-side `msk_*` key and creates resources inside MIOSA workspaces and projects. External attribution fields are still accepted for mapping back to your own database, but canonical ownership is now MIOSA `workspace_id` and `project_id`.

This is the ClinicIQ pattern: ClinicIQ is a SaaS that lets dental clinics build marketing sites, booking apps, lead magnets, and documents. ClinicIQ has one MIOSA organization slug, for example `cliniciq`. Each client clinic can be a MIOSA workspace, each site/app/document can be a project, and every sandbox, computer, database, deployment, storage bucket, volume, function, job, and domain belongs to that project.

The tenant hierarchy is:
```

MIOSA Organization (ClinicIQ / slug: cliniciq)
  └── MIOSA API key (msk_cliniciq_server_prod)
       └── Workspace (Dr. Smith Clinic / slug: dr-smith-clinic)
            └── Project (Lead Magnet / slug: lead-magnet)
                 └── Sandboxes, Computers, Databases, Deployments, Domains
```

## When to use it

- You are building a no-code / low-code platform and end users build inside your product
- Your customers must never need a MIOSA account or API key
- You need per-customer usage metering and chargeback on a single MIOSA bill
- Browser-side preview iframes must not expose your server-side API key
- You want to group sandboxes, computers, deployments, databases, and domains by workspace and project

## Quick example

```python

client = miosa.Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Create a sandbox in a client workspace and project
sandbox = client.sandboxes.create(
    template="miosa-sandbox",
    workspace_slug="dr-smith-clinic",
    workspace_name="Dr. Smith Clinic",
    project_slug="lead-magnet",
    project_name="Lead Magnet",
    external_workspace_id="clinic_123",
    external_user_id="dr-smith-456",
    external_project_id="project_789",
)

# List all sandboxes that belong to that workspace
dental_sandboxes = client.sandboxes.list(
    workspace_id=sandbox.workspace_id
)
```

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

// Create a sandbox in a client workspace and project
const sandbox = await miosa.sandboxes.create({
  template: "miosa-sandbox",
  workspaceSlug: "dr-smith-clinic",
  workspaceName: "Dr. Smith Clinic",
  projectSlug: "lead-magnet",
  projectName: "Lead Magnet",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  externalProjectId: "project_789",
})

// List all sandboxes that belong to that workspace
const dentalSandboxes = await miosa.sandboxes.list({
  workspaceId: sandbox.workspaceId,
})
```

## How it fits together
Diagram:
sequenceDiagram
    participant B as Browser (end user)
    participant CQ as ClinicIQ Backend
    participant M as MIOSA API

    B->>CQ: "New site" click
    CQ->>M: POST /sandboxes<br/>Bearer msk_*<br/>workspace_slug: dr-smith-clinic<br/>project_slug: lead-magnet
    M-->>CQ: { id: "sbx_...", workspace_id: "...", project_id: "..." }
    CQ->>M: POST /sandboxes/{id}/preview-token
    M-->>CQ: { token: "pt_...", url: "...", expires_at: "..." }
    CQ-->>B: sandbox_id + preview_url (token only)
    B->>M: iframe preview (short-lived token, no msk_*)

The `msk_*` key never reaches the browser. The browser only receives a short-lived preview token scoped to a single resource.

## Ownership and attribution fields

Every create request accepts canonical ownership fields and optional external attribution fields:

| Field | Type | Purpose |
|---|---|---|
| `workspace_id` | UUID | Existing MIOSA workspace that owns the resource |
| `workspace_slug` | string | Existing or auto-created workspace slug |
| `workspace_name` | string | Display name used if a workspace is auto-created from an external ID |
| `project_id` | UUID | Existing MIOSA project that owns the resource |
| `project_slug` | string | Existing or auto-created project slug inside the workspace |
| `project_name` | string | Display name used if a project is auto-created |
| `external_workspace_id` | string | Your customer's account, clinic, tenant, or workspace ID |
| `external_user_id` | string | The individual end user who triggered the action |
| `external_project_id` | string | Your project/app/document ID |

If you pass an external workspace or project ID without a MIOSA ID/slug, MIOSA resolves or creates the matching workspace/project for the authenticated organization. Responses include both canonical IDs and external IDs so your backend can store the MIOSA IDs and use them on future calls.

These IDs are scoped under your organization. Another MIOSA organization cannot read or mutate your resources even if they know the same slug or external ID values.

Never put `msk_*` API keys in a browser. Any browser code that needs MIOSA access must go through your backend, which mints a scoped preview token. Treat the API key like a Stripe secret key — server-only, rotated periodically, audited.

## Next


    The one server-side key. Rotation, scopes, audit.
    [Open →](/docs/platform/api-keys/)


    Canonical `workspace_id` / `project_id` ownership plus `external_*` fields for billing and your own database.
    [Open →](/docs/platform/attribution/)


    Short-lived scoped tokens for preview and terminal access from the end-user's browser.
    [Open →](/docs/platform/browser-tokens/)


    Per-tenant, per-external-workspace usage. Chargeback to your customers.
    [Open →](/docs/platform/usage-and-billing/)


## Reference integration

A working end-to-end example lives at [`examples/white-label-cliniciq/`](https://github.com/Miosa-osa/miosa/tree/main/examples/white-label-cliniciq). It shows server-side sandbox creation with attribution, tenant-scoped listing, preview token minting, and browser-safe embedding in ~150 lines of TypeScript.

See also [`examples/agent-builds-static-app/`](https://github.com/Miosa-osa/miosa/tree/main/examples/agent-builds-static-app) for the "AI agent builds + previews + deploys" pattern.

---

# Usage & Billing

URL: https://miosa.ai/docs/platform/usage-and-billing
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/usage-and-billing
Source: src/routes/docs/platform/usage-and-billing/+page.md
Description: Track MIOSA usage per workspace, per project, per external customer, and per user. Chargeback to your customers.

If you're a platform reselling MIOSA capacity, you need to attribute MIOSA costs back to your own customers. MIOSA emits usage events with [resource ownership and external attribution](/docs/platform/attribution/) on every billable action; you query them, group, and chargeback in your own currency / margin model.

The usage report APIs described here are part of Phase 10 of the deployment refactor. Today, usage events are captured (with attribution) in the `usage_meters`, `sandbox_runtime_events`, and `optimal_usage_records` tables; the grouped-read endpoints are being wired. Tenants with platform integration needs today can query raw events via the database or wait for the public API.

## What's metered

| Dimension | Unit | When emitted |
|---|---|---|
| Sandbox runtime | sandbox-seconds (per vCPU, per GB-RAM) | Per-second while running |
| Builder runtime | builder-seconds | During publish |
| Runtime instance runtime | runtime-seconds (per vCPU, per GB-RAM) | Per-second while serving |
| Static artifact storage | GB-months | Continuously |
| Static artifact bandwidth | GB egress | Per response |
| Object storage (buckets) | GB-months + GB egress | Continuously / per response |
| Managed Postgres | GB-months + connections | Continuously |
| Managed Redis | GB-months | Continuously |
| Ownership and attribution: every event carries `workspace_id`, `project_id`, and the `external_*` fields if present on the source resource |

Computers (desktop product) have a separate metering schema; see [Computers](/docs/computers/overview/) for that side.

## Usage report API
```http
GET /api/v1/usage?period_start=2026-05-01&period_end=2026-06-01
GET /api/v1/usage?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/usage?external_workspace_id=clinic_123&period=2026-05
```

```typescript
const report = await miosa.usage.report({
  period: { start: "2026-05-01", end: "2026-06-01" },
  groupBy: ["external_workspace_id"],
})

for (const row of report.data) {
  console.log(
    row.external_workspace_id,
    "$" + row.total_usd.toFixed(2),
    row.line_items
  )
}
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

# Grouped chargeback report for a billing period
report = miosa.usage.report(
    period_start="2026-05-01",
    period_end="2026-06-01",
    group_by=["external_workspace_id"],
)

for row in report.get("data", []):
    print(row["external_workspace_id"], f"${row['total_usd']:.2f}")

# Single-workspace query for the current period
summary = miosa.usage.report(
    external_workspace_id="clinic_123",
)
print(summary)

# Raw per-session events
sessions = miosa.usage.sessions(external_workspace_id="clinic_123")
for s in sessions:
    print(s["dimension"], s["qty"])
```

Response shape:
```json
{
  "data": [
    {
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "660e8400-e29b-41d4-a716-446655440001",
      "external_workspace_id": "clinic_123",
      "external_user_id": null,
      "external_project_id": null,
      "total_usd": 4.20,
      "line_items": [
        { "dimension": "sandbox_seconds", "qty": 1200, "usd": 0.40 },
        { "dimension": "static_bandwidth_gb", "qty": 38.2, "usd": 3.80 }
      ]
    },
    {
      "external_workspace_id": "smile-clinic-456",
      "total_usd": 11.75,
      "line_items": [...]
    }
  ],
  "period": { "start": "2026-05-01", "end": "2026-06-01" },
  "currency": "usd"
}
```

Use `groupBy` to slice by any combination of ownership and external IDs. Typical groupings:

- `["workspace_id"]` — per-client workspace
- `["workspace_id", "project_id"]` — per-app/project inside a client
- `["external_workspace_id"]` — per-customer chargeback
- `["external_workspace_id", "external_project_id"]` — per-app within a customer
- `["external_user_id"]` — per-user attribution (e.g. for fair-use limits)
- `[]` — total for the entire MIOSA organization

## Audit log

Every mutation also emits an audit event with attribution. Different table, separate read endpoint:
```http
GET /api/v1/audit?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/audit?external_workspace_id=clinic_123
GET /api/v1/audit?api_key_id=key_...
GET /api/v1/audit?action=deployments.publish
```

Audit is for security / compliance, usage is for billing. Both share the same ownership and attribution model.

## Quotas and limits

MIOSA enforces quotas at the organization and plan level. You can enforce per-workspace, per-project, or per-user limits in your own app logic, querying usage to make decisions.

Example: ClinicIQ wants to cap each dental office at $50/month. Their backend:

1. Queries `/api/v1/usage?workspace_id=550e8400-e29b-41d4-a716-446655440000&period=current_month`.
2. If `total_usd &gt; 50`, denies new sandbox creation in the ClinicIQ app.
3. Optionally, hits a MIOSA endpoint to suspend the customer's sandboxes (not a single endpoint today; do it client-side by destroying their sandboxes).

For platform-level safety, MIOSA can also enforce per-external-workspace soft quotas at the tenant config level (Phase 8) — talk to support if you need this.

## Pricing

Pricing is plan-dependent. Visit the [Pricing page](https://miosa.ai/pricing) on the marketing site for current rates, or contact support for enterprise plans.

Platform integrations typically negotiate volume rates — talk to sales before scaling to thousands of end users.

## Billing tenancy

Important: your MIOSA bill is one bill. MIOSA charges the organization owner for all usage, regardless of which workspace/project or `external_workspace_id` it came from. Ownership and attribution exist so you can charge your customers. MIOSA does not bill your downstream clinics directly.
```

MIOSA -> ClinicIQ:        $X / month, one invoice
ClinicIQ -> clinic_123:   $Y / month (markup, your pricing model)
ClinicIQ -> clinic_456:   $Z / month
```

## See also

- [Ownership and Attribution](/docs/platform/attribution/) — the IDs that flow through usage events
- [API Keys](/docs/platform/api-keys/) — the credential for usage queries (`usage:read` scope)
- [Audit](/docs/api-reference/events/) — for security log queries

---

# White-label setup

URL: https://miosa.ai/docs/platform/white-label
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/white-label
Source: src/routes/docs/platform/white-label/+page.md
Description: Configure organization slug, workspace/project ownership, preview domains, deployment domains, branding, and resource attribution.

# White-label setup

MIOSA can run behind your product and your customers' domains. The important order is: set the organization identity first, then create workspaces/projects, then attach domains at the organization, workspace, project, deployment, or computer level.

---

## Setup flow
Diagram:
flowchart TD
  A[Set organization name] --> B[Organization slug is created once]
  B --> C[Create workspaces for customers]
  C --> D[Create projects inside workspaces]
  D --> E[Create sandboxes, computers, data, and deployments]
  E --> F[Use miosa.app fallback URLs]
  F --> G[Attach custom domains when ready]
  G --> H[Issue browser tokens to end users]

## 1. Organization identity

Every account needs a real organization name. MIOSA derives the organization slug from that name, and the slug is permanent after setup. Do this before letting users create resources.

Example:

| Organization name | Organization slug | Default managed deployment URL |
|---|---|---|
| `ClinicIQ` | `cliniciq` | `https://lead-magnet.cliniciq.miosa.app` |

If a newly created account still has a temporary setup slug such as `org-...` or a slug that does not match the organization name, require setup before normal app navigation.

```http
GET /api/v1/platform/tenants/current
Authorization: Bearer msk_live_...
```

If setup is required, update the tenant with the final organization name:
```http
PUT /api/v1/tenants/{tenant_id}
Authorization: Bearer msk_live_...
Content-Type: application/json

{
  "name": "ClinicIQ"
}
```

The API normalizes the slug from `name`. If a `slug` is supplied, it must match the normalized organization name. After setup, `name` and `slug` are immutable.

The organization slug is used in MIOSA-managed URLs until a custom domain is attached. Make the setup screen explicit: "Create your organization name. This creates your permanent MIOSA slug and can only be done once."

## 2. Workspaces and projects

For white-label platforms, use workspaces for downstream customers and projects for the things they build.

ClinicIQ example:

```
Organization: ClinicIQ
  Workspace: Dr. Smith Clinic
    Project: Summer lead magnet
      Sandboxes: generated app previews
      Databases: form submissions
      Deployment: production lead magnet
      Domain: program.drsmithclinic.com
  Workspace: Downtown Dental
    Project: Booking portal
```

Create workspaces and projects directly, or let resource create calls auto-resolve them from `workspace_slug` / `project_slug` or `external_workspace_id` / `external_project_id`.

```http
POST /api/v1/sandboxes
Content-Type: application/json

{
  "template_id": "miosa-sandbox",
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "summer-lead-magnet",
  "project_name": "Summer Lead Magnet",
  "external_workspace_id": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789"
}
```

Responses include `workspace_id` and `project_id`. Store those IDs for future calls.

## 3. Default URL behavior

Until custom DNS is configured, MIOSA uses managed URLs:

| Resource | Default URL shape |
|---|---|
| Sandbox preview | `https://{port}-{sandbox_slug}.sandbox.miosa.app` |
| Computer desktop | `https://{computer_slug}.computer.miosa.ai/desktop/index.html` |
| Deployment | `https://{deployment_slug}.{organization_slug}.miosa.app` |

For ClinicIQ, a deployment named `Lead Magnet` defaults to something like:

```text
https://lead-magnet.cliniciq.miosa.app
```

This fallback is always available. Customers do not need to configure DNS unless they want their own domain.

## 4. Organization preview domain

Set a tenant preview domain when generated sandbox preview URLs should use your organization's domain instead of `miosa.app`.

Example:

```http
PUT /api/v1/tenant/preview-domain
Content-Type: application/json

{
  "preview_domain": "cliniciq.dev"
}
```

DNS:

| Record type | Name | Value |
|---|---|---|
| `CNAME` | `*` | `proxy.miosa.ai` |
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` |

After DNS propagates:

```http
GET /api/v1/tenant/preview-domain/verify
```

Sandbox preview URLs then use:

```text
https://5173-sbx01j9x.sandbox.cliniciq.dev
```

## 5. Workspace and project preview domains

Set a workspace preview domain when one downstream customer should get branded managed URLs for previews, computers, and deployments:

```http
PUT /api/v1/workspaces/{workspace_id}/preview-domain
Content-Type: application/json

{
  "preview_domain": "drsmithclinic.com"
}
```

Set a project preview domain when only one generated thing should use its own base domain:

```http
PUT /api/v1/projects/{project_id}/preview-domain
Content-Type: application/json

{
  "preview_domain": "program.drsmithclinic.com"
}
```

Each base domain uses the same two wildcard CNAME records: `*` and `*.sandbox`, both pointing to `proxy.miosa.ai`.

Examples after setup:

| Scope | Example |
|---|---|
| Workspace preview | `https://lead-magnet.drsmithclinic.com` |
| Workspace sandbox port | `https://5173-sbx01j9x.sandbox.drsmithclinic.com` |
| Project deployment | `https://lead-magnet.program.drsmithclinic.com` |

## 6. Resource custom domains

Attach exact domains when a project, deployment, or computer needs its own public URL.

Examples:

- `drsmithclinic.com` for a website deployment
- `program.drsmithclinic.com` for a lead magnet
- `app.drsmithclinic.com` for an app
- `preview.drsmithclinic.com` for a client-specific preview surface

For deployments:

```http
POST /api/v1/deployments/{deployment_id}/domains
Content-Type: application/json

{
  "domain": "program.drsmithclinic.com"
}
```

For computers:

```http
POST /api/v1/computers/{computer_id}/domains
Content-Type: application/json

{
  "domain": "desktop.drsmithclinic.com"
}
```

The domain response returns DNS instructions and verification status. Exact resource domains take precedence over managed MIOSA URLs.

## 7. Domain precedence

When MIOSA renders or routes a URL, use this mental model:

| Priority | Source | Example |
|---|---|---|
| 1 | Exact resource domain | `program.drsmithclinic.com` |
| 2 | Project domain override | `program.drsmithclinic.com` |
| 3 | Workspace/client domain override | `preview.drsmithclinic.com` |
| 4 | Organization preview domain | `cliniciq.dev` |
| 5 | MIOSA managed fallback | `miosa.app` |

Workspace/project preview domains are inherited by generated sandbox previews, computer URLs, and managed deployment URLs. Exact resource custom domains still win when attached.

## 8. Branding

Tenant branding controls the product UI, desktop wallpaper, logos, support URL, and whether "Powered by MIOSA" is shown.

```http
PUT /api/v1/tenant/branding
Content-Type: application/json

{
  "custom_app_name": "ClinicIQ",
  "custom_logo_url": "https://cliniciq.com/logo-dark.png",
  "support_url": "https://help.cliniciq.com",
  "desktop_wallpaper_url": "https://cliniciq.com/wallpaper.png",
  "powered_by_visible": false
}
```

Wallpaper requirements:

| Property | Value |
|---|---|
| Format | PNG or JPEG |
| Dimensions | 1920 x 1080 recommended |
| File size | Max 5 MB |

## 9. Browser tokens

Never expose an `msk_*` API key in a browser. Your backend creates sandboxes, deployments, and domains, then issues scoped browser tokens for the end user.

```typescript
const token = await client.browserTokens.create({
  workspaceId: "550e8400-e29b-41d4-a716-446655440000",
  projectId: "660e8400-e29b-41d4-a716-446655440001",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  permissions: ["sandbox:read", "sandbox:exec", "preview:read"],
  ttlSeconds: 3600,
})
```

## Complete setup checklist

- [ ] Require organization setup if the account still has a temporary slug or no organization name.
- [ ] Explain that organization name creates the permanent MIOSA slug one time.
- [ ] Create or auto-resolve workspaces for downstream customers.
- [ ] Create or auto-resolve projects for each app, website, lead magnet, document, or workflow.
- [ ] Store `workspace_id` and `project_id` from create responses.
- [ ] Use `miosa.app` fallback URLs until DNS is configured.
- [ ] Configure organization preview domain if previews should use your domain.
- [ ] Configure workspace or project preview domains when a customer/project needs its own managed URL base.
- [ ] Attach exact custom domains to deployments or computers when a customer wants their own URL.
- [ ] Apply tenant branding and support links.
- [ ] Issue browser tokens from your backend only.

---

## See also


    Workspace/project ownership plus external IDs for chargeback and filtering.

    [Attribution reference →](/docs/platform/attribution)


    Domain APIs, DNS records, and verification responses.

    [Custom domains →](/docs/api-reference/custom-domains)


    Workspace create, update, settings, and usage.

    [Workspaces →](/docs/api-reference/workspaces)


    Project create, update, and workspace scoping.

    [Projects →](/docs/api-reference/projects)

---

# Quickstart

URL: https://miosa.ai/docs/quickstart
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/quickstart
Source: src/routes/docs/quickstart/+page.md
Description: A five-minute hands-on tour of MIOSA — create a sandbox, write code, preview it live, and publish to production. Two tracks: static deploy and agent-driven build.

# Quickstart

Two tracks. Pick one, finish it, then read the other.

- **Track 1: Static deploy** — write a small site inside a sandbox, preview it live, publish to a permanent URL. Good first pass through the whole platform.
- **Track 2: Agent-driven build** — drive a sandbox entirely through the API as your own AI agent (BYO LLM), then optionally screenshot a Computer.

Both tracks take five minutes.

---

## Prerequisites

1. A MIOSA account at [miosa.ai](https://miosa.ai) with a workspace created.
### 2. A workspace API key: Dashboard → Settings → API Keys → New key. It starts with `msk_`. Export it:

```bash
export MIOSA_API_KEY="msk_live_..."
```

### 3. SDK installed for your language

```bash
npm install @miosa/sdk
# or: pnpm add @miosa/sdk
```

```bash
pip install miosa
```

Workspace API keys are server-only. For browser-side preview embedding, your backend mints a short-lived share token. See [Browser Tokens](/docs/platform/browser-tokens/).

---

## Track 1: Static deploy

### Step 1 — Create a sandbox.

```typescript

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

const sandbox = await miosa.sandboxes.create({
  templateId: "miosa-node",
})
console.log(sandbox.id, sandbox.state)
// sbx_a1b2c3d4e5  running
```

```python

from miosa import Miosa

miosa = Miosa(api_key=os.environ["MIOSA_API_KEY"])

sandbox = miosa.sandboxes.create(template_id="miosa-node")
print(sandbox.id, sandbox.state)
# sbx_a1b2c3d4e5  running
```

### Step 2 — Write a small static site into `/workspace`.

```typescript
await sandbox.files.write(
  "/workspace/index.html",
  `<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>My App</title></head>
  <body><h1>Hello from MIOSA</h1><p>Built in a sandbox.</p></body>
</html>`
)
```

```python
sandbox.files.write(
    "/workspace/index.html",
    """<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>My App</title></head>
  <body><h1>Hello from MIOSA</h1><p>Built in a sandbox.</p></body>
</html>""",
)
```

### Step 3 — Start a dev server so you can preview it.

```typescript
await sandbox.exec({
  cmd: "python3",
  args: ["-m", "http.server", "3000", "--bind", "0.0.0.0"],
  cwd: "/workspace",
  detached: true,
})
```

```python
sandbox.exec(
    cmd="python3",
    args=["-m", "http.server", "3000", "--bind", "0.0.0.0"],
    cwd="/workspace",
    detached=True,
)
```

### Step 4 — Create a preview and open it.

```typescript
const preview = await sandbox.previews.create({ port: 3000 })
console.log(preview.url)
// https://abc12345.preview.miosa.app
```

```python
preview = sandbox.previews.create(port=3000)
print(preview.url)
# https://abc12345.preview.miosa.app
```

   Open the URL in your browser. You see your `index.html` served live from inside the sandbox.

### Step 5 — Publish to production.

```typescript
const result = await miosa.deployments.publish({
  sourceSandboxId: sandbox.id,
  kind: "static",
  outputPath: "/workspace",
})
console.log("live at:", result.deployment.public_url)
// live at: https://my-app-a1b2.miosa.app
```

```python
result = miosa.deployments.publish(
    source_sandbox_id=sandbox.id,
    kind="static",
    output_path="/workspace",
)
print("live at:", result.deployment.public_url)
# live at: https://my-app-a1b2.miosa.app
```

   MIOSA freezes a source snapshot, runs a Builder to package the files, stores an immutable Release, and routes the Deployment URL to it. The sandbox remains alive and editable.

### Step 6 — Make a change and republish.
   Edit `/workspace/index.html` again and call `deployments.publish` once more. A new Version is created, the Release is new, and the Deployment's `active_version_id` flips. The previous version is archived — roll back instantly by calling `deployments.rollback`.

### Step 7 — (Optional) Attach a custom domain.
   See [Domains](/docs/deploy/domains/) for the DNS setup. Short version: add a `CNAME` from your domain to the generated host, hit the verify endpoint, MIOSA issues a TLS certificate.

### Step 8 — Clean up.

```typescript
await sandbox.destroy()
```

```python
sandbox.destroy()
```

   The sandbox is gone. The published deployment and its domain are unaffected — the Release is immutable and lives in object storage independently of the sandbox.

### What you just did

| Step | What happened |
|------|--------------|
| `sandboxes.create` | Booted a Firecracker microVM from the `miosa-node` template in ~150 ms |
| `files.write` | Wrote a file into `/workspace` inside the running VM |
| `exec` | Ran a command inside the VM over the exec API |
| `previews.create` | Opened a tunnel from a public hostname to port 3000 inside the VM |
| `deployments.publish` | Froze source, ran Builder, stored Release, created Version, made it live |
| `sandbox.destroy` | Terminated the VM; deployment is unaffected |

---

## Track 2: Agent-driven build

This track treats the sandbox as an agent's tool environment. You supply the intelligence (any LLM); the sandbox supplies isolated compute, file system, and execution.

### Step 1 — Create a sandbox with external attribution.
   If you're embedding MIOSA in your own product, pass your user/project IDs so you can filter resources later.

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: "miosa-node",
  externalWorkspaceId: "clinic-123",
  externalUserId: "dr-smith-456",
  externalProjectId: "patient-portal-789",
})
console.log(sandbox.id)
// sbx_f6g7h8i9j0
```

```python
sandbox = miosa.sandboxes.create(
    template_id="miosa-node",
    external_workspace_id="clinic-123",
    external_user_id="dr-smith-456",
    external_project_id="patient-portal-789",
)
print(sandbox.id)
# sbx_f6g7h8i9j0
```

### Step 2 — Give your agent an exec tool.
   The pattern below shows the structure. Substitute `callYourLLM` with your actual model call.

```typescript
// Tool the agent can call
async function execInSandbox(command: string): Promise<string> {
  const result = await sandbox.exec({ cmd: "bash", args: ["-c", command] })
  return result.stdout + result.stderr
}

// Example: agent scaffolds a project
const output = await execInSandbox("npx create-react-app /workspace/my-app --template minimal 2>&1 | tail -5")
console.log(output)
// Success! Created /workspace/my-app
// Happy hacking!
```

```python
def exec_in_sandbox(command: str) -> str:
    result = sandbox.exec(cmd="bash", args=["-c", command])
    return result.stdout + result.stderr

# Example: agent scaffolds a project
output = exec_in_sandbox(
    "npx create-react-app /workspace/my-app --template minimal 2>&1 | tail -5"
)
print(output)
# Success! Created /workspace/my-app
# Happy hacking!
```

### Step 3 — Let the agent write files directly.

```typescript
// Agent writes a component
await sandbox.files.write(
  "/workspace/my-app/src/App.jsx",
  `export default function App() {
  return <main><h1>Generated by my agent</h1></main>;
}`
)
```

```python
# Agent writes a component
sandbox.files.write(
    "/workspace/my-app/src/App.jsx",
    """export default function App() {
  return <main><h1>Generated by my agent</h1></main>;
}""",
)
```

### Step 4 — Start the dev server, create a preview, stream it to your user.

```typescript
await sandbox.exec({
  cmd: "bash", args: ["-c", "cd /workspace/my-app && npm start &"],
  detached: true,
})

const preview = await sandbox.previews.create({ port: 3000 })
const share = await sandbox.previews.share(preview.id)

console.log("embed this URL in your product's UI:", share.share_url)
// https://abc12345.preview.miosa.app?token=stk_...
```

```python
sandbox.exec(
    cmd="bash",
    args=["-c", "cd /workspace/my-app && npm start &"],
    detached=True,
)

preview = sandbox.previews.create(port=3000)
share = sandbox.previews.share(preview.id)

print("embed this URL in your product's UI:", share.share_url)
# https://abc12345.preview.miosa.app?token=stk_...
```

   The `share_url` is safe to put in an `&lt;iframe&gt;` in your end user's browser. It expires after the configured TTL. Your `msk_*` key never leaves your server.

### Step 5 — Take a screenshot of a Computer (optional).
   If your agent needs to verify GUI output or run browser-based tasks, use a Computer instead of (or alongside) a Sandbox.

```typescript
const computer = await miosa.computers.create({
  name: "agent-browser",
  templateType: "miosa-desktop",
  size: "small",
})

// Let the agent observe the screen
const png = await computer.desktop.screenshot()
// → Buffer containing PNG bytes; send to your vision model

// Let the agent interact
await computer.desktop.click({ x: 800, y: 400 })
await computer.desktop.type("hello world")

await computer.destroy()
```

```python
computer = miosa.computers.create(
    name="agent-browser",
    template_type="miosa-desktop",
    size="small",
)

# Let the agent observe the screen
png = computer.desktop.screenshot()
# → bytes containing PNG; send to your vision model

# Let the agent interact
computer.desktop.click(x=800, y=400)
computer.desktop.type("hello world")

computer.destroy()
```

### Step 6 — Publish what the agent built.

```typescript
const result = await miosa.deployments.publish({
  sourceSandboxId: sandbox.id,
  kind: "static",
  outputPath: "/workspace/my-app/build",
  externalProjectId: "patient-portal-789",
})
console.log("agent's app is live at:", result.deployment.public_url)
// agent's app is live at: https://patient-portal-a1b2.miosa.app
```

```python
result = miosa.deployments.publish(
    source_sandbox_id=sandbox.id,
    kind="static",
    output_path="/workspace/my-app/build",
    external_project_id="patient-portal-789",
)
print("agent's app is live at:", result.deployment.public_url)
# agent's app is live at: https://patient-portal-a1b2.miosa.app
```

### Step 7 — Filter all sandboxes for this customer.

```typescript
const allForClinic = await miosa.sandboxes.list({
  externalWorkspaceId: "clinic-123",
})
console.log(`${allForClinic.length} sandboxes for clinic-123`)
// 3 sandboxes for clinic-123
```

```python
all_for_clinic = miosa.sandboxes.list(external_workspace_id="clinic-123")
print(f"{len(all_for_clinic)} sandboxes for clinic-123")
# 3 sandboxes for clinic-123
```

### Step 8 — Clean up.

```typescript
await sandbox.destroy()
```

```python
sandbox.destroy()
```

### What you just did

| Step | What happened |
|------|--------------|
| External attribution | Tagged every resource with your customer's IDs — no MIOSA accounts needed for your end users |
| Exec as agent tool | Ran arbitrary shell commands inside an isolated VM from your agent loop |
| `files.write` | Agent wrote generated code directly to the sandbox file system |
| Share token | Minted a browser-safe URL for preview embedding — workspace key stays server-side |
| Computer screenshot | Optionally gave the agent a real desktop with a vision-accessible screen |
| `deployments.publish` | Shipped the agent's output to a permanent immutable URL |
| `sandboxes.list` with attribution | Queried only resources belonging to one customer — cross-tenant leakage impossible |

---

## What's next

- **Add a real backend.** Move from static to dynamic deploys with [Publishing](/docs/deploy/publishing/) and a managed [Postgres database](/docs/data/postgres/).
- **Authenticate end users.** [Auth-as-a-service](/docs/data/auth/) adds a full JWT signup/login flow with one environment variable.
- **Roll back a bad deploy.** [Rollback](/docs/deploy/rollback/) repoints the domain at an older version in seconds.
- **Understand every primitive.** [Concepts](/docs/concepts/) is the canonical architecture reference.
- **See a full white-label example.** The [reference integration](https://github.com/Miosa-osa/miosa/tree/main/examples/white-label-cliniciq) shows a complete platform embedding.
- **API wire format.** [API Reference](/docs/api-reference/) documents every endpoint.

---

# Elixir SDK

URL: https://miosa.ai/docs/sdks/elixir
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/elixir
Source: src/routes/docs/sdks/elixir/+page.md
Description: Install, configure, and make your first request with the MIOSA Elixir SDK.

The official Elixir SDK for MIOSA. Requires Elixir 1.15+ and OTP 25+. All functions return `{:ok, result}` or `{:error, %Miosa.Error{}}`.

## Install

```elixir
# mix.exs
{:miosa, "~> 0.1"}
```

Then run `mix deps.get`.

  The package will be available on Hex.pm as `miosa`. Until first publish, use the GitHub dependency: `{:miosa, github: "Miosa-osa/miosa", sparse: "sdks/elixir"}`.

## First request

```elixir
client = Miosa.Client.new("msk_live_...")

# Create a sandbox, run a command, destroy it
{:ok, sandbox} = Miosa.Sandboxes.create(client, %{name: "quick-exec"})
:ok = Miosa.Computer.start(client, sandbox.id)

{:ok, %{output: output}} =
  Miosa.Exec.run(client, sandbox.id, command: "python3 -c 'print(1 + 1)'")

IO.puts(output)  # "2\n"
:ok = Miosa.Computer.destroy(client, sandbox.id)
```

## Configure

| Option | Env var | Default | Description |
|---|---|---|---|
| `api_key` (positional) | — | — | Workspace key (`msk_live_*`). Must start with `msk_`. |
| `:base_url` | `MIOSA_BASE_URL` | `https://api.miosa.ai/api/v1` | API endpoint |
| `:timeout` | — | `30_000` | Connect timeout in milliseconds |
| `:receive_timeout` | — | `60_000` | Receive timeout for long-running requests |
| `:retry` | — | `false` | Pass to `Req` retry middleware |

```elixir
client = Miosa.Client.new("msk_live_...",
  base_url: "https://api.miosa.ai/api/v1",
  timeout: 30_000,
  receive_timeout: 60_000,
  retry: false
)
```

The client struct is a plain value — pass it as the first argument to every resource function. There is no global state or process registration.

  `Miosa.Client.new/2` raises `ArgumentError` if the key does not start with `msk_`. Use `Miosa.client/2` as a convenience alias if you prefer that entry point.

## Authentication

The API key is sent as `Authorization: Bearer <key>` on every request.

```elixir
# From environment variable (recommended for production)
client = Miosa.Client.new(System.fetch_env!("MIOSA_API_KEY"))

# With additional headers (e.g., for white-label proxies)
client = Miosa.Client.new("msk_live_...",
  headers: [{"x-tenant-id", "acme-corp"}]
)
```

## Error handling

All functions follow the `{:ok, result} | {:error, %Miosa.Error{}}` contract. Match on `status` for typed dispatch:

```elixir
case Miosa.Computers.get(client, "nonexistent-id") do
  {:ok, computer} ->
    IO.puts("Found: #{computer.name}")

  {:error, %Miosa.Error{status: 401}} ->
    IO.puts("Invalid API key")

  {:error, %Miosa.Error{status: 403}} ->
    IO.puts("Access denied")

  {:error, %Miosa.Error{status: 404}} ->
    IO.puts("Computer not found")

  {:error, %Miosa.Error{status: 422, message: msg}} ->
    IO.puts("Validation error: #{msg}")

  {:error, %Miosa.Error{status: 429, message: msg}} ->
    IO.puts("Rate limited: #{msg}")

  {:error, %Miosa.Error{status: 402}} ->
    IO.puts("Insufficient credits — top up at miosa.ai/billing")

  {:error, %Miosa.Error{status: status, message: msg}} ->
    IO.puts("API error #{status}: #{msg}")
end
```

The `%Miosa.Error{}` struct fields are: `:message`, `:status`, `:code`, `:body`.

## Streaming events

`Miosa.Sandbox.Events.stream/3` opens an SSE connection and calls your callback for each event. Return `:stop` to close the stream, `:continue` to keep reading:

```elixir
Miosa.Sandbox.Events.stream(client, sandbox_id, fn event ->
  IO.puts("[#{event.type}] #{inspect(event.data)}")

  if event.type in ~w(build.completed build.failed build.timed_out) do
    :stop
  else
    :continue
  end
end)
```

For computer-level SSE (e.g., agent session events):

```elixir
Miosa.Client.stream_sse(
  client,
  "/computers/#{computer_id}/agent/#{session_id}/stream",
  fn event ->
    IO.puts("[#{event.type}] #{event.data}")
    if event.type == "finished", do: :stop, else: :continue
  end
)
```

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, destroy) | ✓ |
| Sandbox sub-resources (events, files, env, tags, terminal, previews, snapshots) | ✓ |
| Computers (CRUD + lifecycle) | ✓ |
| Computer sub-resources (terminal, env, ports, volumes, logs, auto-stop, metrics, inbox, OSA) | ✓ |
| Desktop | ✓ |
| Files (upload, download, list, delete) | ✓ |
| Exec | ✓ |
| Deployments | ✓ |
| Databases (managed Postgres) | ✓ |
| Storage (object storage) | ✓ |
| Volumes | ✓ |
| Custom domains (flat + per-deployment) | ✓ |
| Functions / cron jobs / health checks / webhooks | ✓ |
| Sandbox templates | ✓ |
| API keys | ✓ |
| Tenant / regions / settings | ✓ |
| Dashboard / analytics / audit log / usage | ✓ |
| Channels / integrations / project integrations | ✓ |
| External keys | ✓ |
| MCP | ✓ |
| Models / completions / embeddings | ✓ |
| Provider defaults / benchmarks | ✓ |
| Command center / builder sessions / community | ✓ |
| OpenComputers | ✓ |
| Admin | ✓ |
| Snapshots (standalone) | ✓ |
| Credits | ✓ |

## Common patterns

### Idempotency key

```elixir
{:ok, sandbox} = Miosa.Sandboxes.create(client, %{
  name: "my-sandbox",
  idempotency_key: UUID.uuid4()
})
```

### Pagination

```elixir
defp fetch_all_audit_log(client, after_cursor \\ nil, acc \\ []) do
  params = %{limit: 50} |> then(fn p ->
    if after_cursor, do: Map.put(p, :after, after_cursor), else: p
  end)

  case Miosa.AuditLog.list(client, params) do
    {:ok, %{items: items, next_cursor: nil}} ->
      {:ok, acc ++ items}
    {:ok, %{items: items, next_cursor: cursor}} ->
      fetch_all_audit_log(client, cursor, acc ++ items)
    {:error, _} = err ->
      err
  end
end
```

### Custom base URL (self-hosted)

```elixir
client = Miosa.Client.new("msk_live_...",
  base_url: "https://api.your-domain.com/api/v1"
)
```

### Webhook verification

```elixir
defp verify_webhook(payload, signature, secret) do
  expected = :crypto.mac(:hmac, :sha256, secret, payload) |> Base.encode16(case: :lower)
  Plug.Crypto.secure_compare(expected, signature)
end
```

## Where to next

  Full endpoint reference with request/response schemas
  Run your first sandbox in 60 seconds
  Computers, sandboxes, and the resource model
  Switch to the Go SDK

---

# Go SDK

URL: https://miosa.ai/docs/sdks/go
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/go
Source: src/routes/docs/sdks/go/+page.md
Description: Install, configure, and make your first request with the MIOSA Go SDK.

The official Go SDK for MIOSA. Requires Go 1.21+. All methods accept a `context.Context` for cancellation and timeouts.

## Install

```bash
go get github.com/miosa-ai/miosa-go
```

  If goproxy has not indexed the first release yet, use `GOPROXY=direct go get github.com/miosa-ai/miosa-go`.

## First request

```go
package main

    "context"
    "fmt"

    miosa "github.com/miosa-ai/miosa-go"
)

func main() {
    ctx := context.Background()
    client := miosa.NewClient("msk_live_...")

    // Create a sandbox, run a command, delete it
    sandbox, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{
        Name: "quick-exec",
    })
    if err != nil {
        panic(err)
    }

    result, err := client.Exec.Run(ctx, sandbox.ID, miosa.ExecParams{
        Command: "python3 -c 'print(1 + 1)'",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Output) // "2\n"

    _ = client.Sandboxes.Delete(ctx, sandbox.ID)
}
```

## Configure

| Option | Env var | Default | Description |
|---|---|---|---|
| `apiKey` (positional) | `MIOSA_API_KEY` | — | Workspace key (`msk_live_*`) |
| `WithBaseURL(u)` | — | `https://api.miosa.ai/api/v1` | API endpoint |
| `WithTimeout(d)` | — | `60s` | Per-request timeout |
| `WithMaxRetries(n)` | — | `3` | Automatic retries on 429 / 5xx |
| `WithHTTPClient(hc)` | — | default `http.Client` | Custom HTTP client |

```go

    "time"
    miosa "github.com/miosa-ai/miosa-go"
)

client := miosa.NewClient(
    "msk_live_...",
    miosa.WithBaseURL("https://api.miosa.ai/api/v1"),
    miosa.WithTimeout(60 * time.Second),
    miosa.WithMaxRetries(3),
)
```

## Authentication

Keys are passed as `Authorization: Bearer <key>`. The SDK validates the key format at construction time.

```go
// From environment variable (recommended)

client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))
```

## Error handling

The SDK uses typed error structs — use `errors.As` to match them:

```go

    "errors"
    "fmt"
    miosa "github.com/miosa-ai/miosa-go"
)

_, err := client.Computers.Get(ctx, "nonexistent-id")
if err != nil {
    var notFound *miosa.NotFoundError
    var authErr *miosa.AuthenticationError
    var permErr *miosa.PermissionError
    var rateLimit *miosa.RateLimitError
    var validErr *miosa.ValidationError
    var credErr *miosa.InsufficientCreditsError
    var srvErr *miosa.ServerError

    switch {
    case errors.As(err, &notFound):
        fmt.Println("Computer not found")
    case errors.As(err, &authErr):
        fmt.Println("Invalid API key")
    case errors.As(err, &permErr):
        fmt.Println("Access denied")
    case errors.As(err, &rateLimit):
        fmt.Printf("Rate limited — retry after %.0fs\n", rateLimit.RetryAfter)
    case errors.As(err, &validErr):
        fmt.Println("Validation error:", validErr.Message)
    case errors.As(err, &credErr):
        fmt.Println("Insufficient credits")
    case errors.As(err, &srvErr):
        fmt.Printf("Server error %d\n", srvErr.StatusCode)
    default:
        fmt.Println("Transport error:", err)
    }
}
```

## Streaming events

The Go SDK exposes in-VM events over WebSocket via `computer.Events.Subscribe`. Construct a computer handle first, then subscribe:

```go
// computer.Events is an EventsService bound to that computer's ID.
stream, err := computer.Events.Subscribe(ctx, miosa.EventSubscribeOptions{
    Subscribe: []miosa.EventProducer{
        miosa.ProducerWindow,
        miosa.ProducerFile,
        miosa.ProducerProcess,
    },
    Paths: []string{"/home/user"},
})
if err != nil {
    panic(err)
}
defer stream.Close()

for ev := range stream.C {
    fmt.Printf("[%s] %v\n", ev.Type, ev.Payload)
}
```

The `stream.C` channel is closed when the connection closes or the context is cancelled.

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, delete) | ✓ |
| Computers (CRUD + lifecycle) | ✓ |
| Computer sub-resources (terminal, env, ports, volumes, logs, auto-stop, metrics, inbox, OSA) | ✓ |
| Desktop | ✓ |
| Files (upload, download, list, delete) | ✓ |
| Exec | ✓ |
| Deployments | ✓ |
| Databases (managed Postgres) | ✓ |
| Storage (object storage) | ✓ |
| Volumes | ✓ |
| Custom domains (flat + per-deployment) | ✓ |
| Functions / cron jobs / health checks / webhooks | ✓ |
| Sandbox templates | ✓ |
| API keys | ✓ |
| Tenant / regions / settings | ✓ |
| Dashboard / analytics / audit log / usage | ✓ |
| Channels / integrations / project integrations | ✓ |
| External keys | ✓ |
| MCP | ✓ |
| Models / completions / embeddings | ✓ |
| Provider defaults / benchmarks | ✓ |
| Command center / builder sessions / community | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | ✓ |
| Admin | ✓ |
| Snapshots (standalone) | ✓ |
| Credits | ✓ |

## Common patterns

### Idempotency key

```go

key := uuid.NewString()
sandbox, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{
    Name:           "my-sandbox",
    IdempotencyKey: key,
})
```

### Context-based timeouts

```go
ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
defer cancel()

result, err := client.Exec.Run(ctx, computerID, miosa.ExecParams{
    Command: "npm run build",
    Timeout: 80,
})
```

### Pagination

```go
var after string
for {
    page, err := client.AuditLog.List(ctx, miosa.AuditLogListParams{
        After: after,
        Limit: 50,
    })
    if err != nil {
        break
    }
    for _, entry := range page.Items {
        fmt.Println(entry.Action, entry.CreatedAt)
    }
    if page.NextCursor == "" {
        break
    }
    after = page.NextCursor
}
```

### Custom base URL (self-hosted)

```go
client := miosa.NewClient(
    "msk_live_...",
    miosa.WithBaseURL("https://api.your-domain.com/api/v1"),
)
```

## Where to next

  Full endpoint reference with request/response schemas
  Run your first sandbox in 60 seconds
  Computers, sandboxes, and the resource model
  Switch to the Python SDK

---

# Java SDK

URL: https://miosa.ai/docs/sdks/java
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/java
Source: src/routes/docs/sdks/java/+page.md
Description: Install, configure, and make your first request with the MIOSA Java SDK.

The official Java SDK for MIOSA. Requires Java 11+. Blocking methods have async `*Async()` variants that return `CompletableFuture`.

## Install

```xml
<dependency>
  <groupId>ai.miosa</groupId>
  <artifactId>miosa-sdk</artifactId>
  <version>0.1.0</version>
</dependency>
```

```groovy
implementation 'ai.miosa:miosa-sdk:0.1.0'
```

```kotlin
implementation("ai.miosa:miosa-sdk:0.1.0")
```

```scala
libraryDependencies += "ai.miosa" % "miosa-sdk" % "0.1.0"
```

  The artifact will be available on Maven Central as `ai.miosa:miosa-sdk`. Until first publish, build from source or contact the MIOSA team for a snapshot JAR.

## First request

```java

public class QuickStart {
    public static void main(String[] args) {
        MiosaClient client = new MiosaClient("msk_live_...");

        // Create a sandbox, run a command, destroy it
        Computer sandbox = client.sandboxes().create("quick-exec", "small");
        sandbox.start();

        ExecResult result = sandbox.exec().bash("python3 -c 'print(1 + 1)'");
        System.out.println(result.getOutput()); // "2\n"

        sandbox.destroy();
    }
}
```

## Configure

| Option | Env var | Default | Description |
|---|---|---|---|
| `apiKey` (constructor or builder) | `MIOSA_API_KEY` | — | Workspace key (`msk_live_*`) |
| `baseUrl(String)` | — | `https://api.miosa.ai/api/v1` | API endpoint |
| `timeout(Duration)` | — | `30s` | Per-request timeout |
| `maxRetries(int)` | — | `3` | Automatic retries on 429 / 5xx |

```java

// Builder pattern
MiosaClient client = MiosaClient.builder()
    .apiKey("msk_live_...")
    .baseUrl("https://api.miosa.ai/api/v1")
    .timeout(Duration.ofSeconds(60))
    .maxRetries(3)
    .build();

// Convenience constructor (equivalent to builder with defaults)
MiosaClient client2 = new MiosaClient("msk_live_...");
```

## Authentication

Keys are sent as `Authorization: Bearer <key>`. The client validates the key format at construction time.

```java
// From environment variable (recommended for production)
String apiKey = System.getenv("MIOSA_API_KEY");
MiosaClient client = new MiosaClient(apiKey);

// With additional default headers
MiosaClient client2 = MiosaClient.builder()
    .apiKey("msk_live_...")
    .defaultHeader("X-Tenant-ID", "acme-corp")
    .build();
```

## Error handling

```java

try {
    client.computers().get("nonexistent-id");
} catch (NotFoundException e) {
    System.out.println("Computer not found");
} catch (AuthException e) {
    System.out.println("Invalid API key");
} catch (PermissionException e) {
    System.out.println("Access denied");
} catch (RateLimitException e) {
    System.out.printf("Rate limited — retry after %ds%n", e.getRetryAfter());
} catch (ValidationException e) {
    System.out.println("Validation failed: " + e.getMessage());
} catch (InsufficientCreditsException e) {
    System.out.println("Top up credits at miosa.ai/billing");
} catch (ServerException e) {
    System.out.printf("Server error %d%n", e.getStatusCode());
} catch (MiosaException e) {
    System.out.printf("API error %d: %s%n", e.getStatusCode(), e.getMessage());
}
```

## Streaming events

In-VM events use a WebSocket subscription bound to a computer. Access `computer.events()` and call `subscribe()`:

```java

Computer computer = client.computers().get("comp_abc123");

EventsSubscription sub = computer.events().subscribe(
    EventSubscriptionOptions.builder()
        .subscribe(List.of("file", "process", "window"))
        .paths(List.of("/workspace"))
        .build()
);

// Callback style
sub.onEvent(event -> {
    System.out.printf("[%s] %s%n", event.getType(), event.getPayload());
});

// Or reactive Flow style
sub.events().subscribe(new MyFlowSubscriber());

// Close when done
sub.close();
```

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, start, destroy, bash) | ✓ |
| Computers (CRUD + lifecycle) | ✓ |
| Computer sub-resources (terminal, env, ports, volumes, logs, auto-stop, metrics, inbox, OSA) | ✓ |
| Desktop (screenshot, click, type, drag, scroll, key, windows) | ✓ |
| Files (upload, download, list, delete) | ✓ |
| Exec | ✓ |
| Deployments (publish, versions, rollback, domains) | ✓ |
| Databases (managed Postgres) | ✓ |
| Storage (object storage) | ✓ |
| Volumes | ✓ |
| Custom domains (flat + per-deployment) | ✓ |
| Functions / cron jobs / health checks / webhooks | ✓ |
| Sandbox templates | ✓ |
| API keys | ✓ |
| Tenant / regions / settings | ✓ |
| Dashboard / analytics / audit log / usage | ✓ |
| Channels | ✓ |
| Integrations / project integrations | ✓ |
| External keys | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | ✓ |
| Admin | ✓ |
| Snapshots (standalone) | ✓ |
| Builder sessions / community | ✓ |
| Models / completions / embeddings | — |
| MCP | — |
| Credits | — |

## Common patterns

### Async operations

```java

CompletableFuture future = client.sandboxes().createAsync("async-agent", "small");

future
    .thenAccept(sandbox -> System.out.println("Created: " + sandbox.getId()))
    .exceptionally(err -> {
        System.out.println("Failed: " + err.getMessage());
        return null;
    });
```

### Idempotency key

```java

Computer sandbox = client.sandboxes().create(
    builder -> builder
        .name("my-sandbox")
        .idempotencyKey(UUID.randomUUID().toString())
);
```

### Pagination

```java
String after = null;
while (true) {
    var page = client.auditLog().list(
        b -> b.after(after).limit(50)
    );
    for (var entry : page.getItems()) {
        System.out.println(entry.getAction() + " " + entry.getCreatedAt());
    }
    if (page.getNextCursor() == null) break;
    after = page.getNextCursor();
}
```

### Custom base URL (self-hosted)

```java
MiosaClient client = MiosaClient.builder()
    .apiKey("msk_live_...")
    .baseUrl("https://api.your-domain.com/api/v1")
    .build();
```

## Where to next

  Full endpoint reference with request/response schemas
  Run your first sandbox in 60 seconds
  Computers, sandboxes, and the resource model
  Switch to the Go SDK

---

# Python SDK

URL: https://miosa.ai/docs/sdks/python
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/python
Source: src/routes/docs/sdks/python/+page.md
Description: Install, configure, and make your first request with the MIOSA Python SDK.

The official Python SDK for MIOSA. Supports Python 3.9+ and provides both synchronous (`Miosa`) and asynchronous (`AsyncMiosa`) clients.

## Install

```bash
pip install miosa
```

```bash
uv add miosa
```

```bash
poetry add miosa
```

```bash
pipenv install miosa
```

```bash
conda install -c conda-forge miosa
```

  The package will be available on PyPI as `miosa`. Until first publish, install from GitHub: `pip install git+https://github.com/Miosa-osa/miosa.git#subdirectory=sdks/python`

## First request

```python
from miosa import Miosa

client = Miosa(api_key="msk_live_...")

# Create a sandbox, run a command, destroy it
sandbox = client.sandboxes.create(image="miosa-sandbox")
result = sandbox.run("python3 -c 'print(1 + 1)'")
print(result.stdout)   # "2\n"
sandbox.destroy()
```

## Configure

| Option | Env var | Default | Description |
|---|---|---|---|
| `api_key` | `MIOSA_API_KEY` | — | Workspace key (`msk_live_*`) |
| `base_url` | `MIOSA_BASE_URL` | `https://api.miosa.ai/api/v1` | API endpoint |
| `timeout` | — | `30.0` | Per-request timeout in seconds |
| `max_retries` | — | `3` | Automatic retries on 429 / 5xx |

```python
from miosa import Miosa

# Reads MIOSA_API_KEY from environment
client = Miosa()

# Explicit configuration
client = Miosa(
    api_key="msk_live_...",
    base_url="https://api.miosa.ai/api/v1",
    timeout=60.0,
    max_retries=3,
)
```

Both clients support the context manager protocol:

```python
with Miosa() as client:
    computers = client.computers.list()
```

## Authentication

The API key is sent as `Authorization: Bearer <key>` on every request. Keys must start with `msk_`.

```python
from miosa import Miosa

# From environment variable (recommended for production)

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Custom Authorization header (advanced — for proxy setups)
client = Miosa(
    api_key="msk_live_...",
    default_headers={"X-Tenant-ID": "acme-corp"},
)
```

## Async vs sync

Both clients expose an identical surface; `AsyncMiosa` methods are coroutines:

```python
# Sync
from miosa import Miosa
client = Miosa()
sandbox = client.sandboxes.create(image="miosa-sandbox")

# Async

from miosa import AsyncMiosa

async def main():
    async with AsyncMiosa(api_key="msk_live_...") as client:
        sandbox = await client.sandboxes.create(image="miosa-sandbox")
        result = await sandbox.run("echo hi")
        print(result.stdout)

asyncio.run(main())
```

## Error handling

```python
from miosa import (
    Miosa,
    MiosaError,
    AuthenticationError,
    NotFoundError,
    PermissionError,
    RateLimitError,
    ValidationError,
    InsufficientCreditsError,
    ServerError,
)

client = Miosa()

try:
    computer = client.computers.get("nonexistent-id")
except NotFoundError:
    print("Computer not found")
except AuthenticationError:
    print("Invalid API key")
except PermissionError:
    print("Access denied")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Validation failed: {e.message}")
except InsufficientCreditsError:
    print("Top up credits at miosa.ai/billing")
except ServerError as e:
    print(f"Server error {e.status_code}")
except MiosaError as e:
    print(f"API error {e.status_code}: {e.message}")
```

## Streaming events

`sandbox.events.stream()` opens an SSE connection and yields `SandboxEvent` objects. Use `sandbox.events.astream()` in async code:

```python
# Sync
for event in sandbox.events.stream():
    print(event.type, event.data)
    if event.type in ("build.completed", "build.failed", "build.timed_out"):
        break

# Async (AsyncMiosa — AsyncSandboxEvents.stream() is an async generator)
async for event in sandbox.events.stream():
    print(event.get("type"), event.get("data"))
    if event.get("type") in ("build.completed", "build.failed", "build.timed_out"):
        break
```

---

## Resource Reference

Full method signatures across all 19 resource groups (185 methods total). Every method on `AsyncMiosa` is a coroutine with the same signature — prefix calls with `await`.

### Sandboxes

`client.sandboxes` — `client.sandbox_templates`

```python
# Sandbox lifecycle
sandbox = client.sandboxes.create(
    image="miosa-sandbox",
    name="my-sandbox",           # optional display name
    vcpus=1,
    memory_mb=512,
    timeout_seconds=300,
    idempotency_key="uuid-v4",   # optional
)
sandbox = client.sandboxes.get(sandbox_id)
sandboxes = client.sandboxes.list(page=1, per_page=20)
client.sandboxes.destroy(sandbox_id)

# Execution
result = client.sandboxes.exec(sandbox_id, cmd=["bash", "-c", "echo hi"])
result = sandbox.run("npm install", opts={"cwd": "/app", "timeout_sec": 120})
result = sandbox.exec(["python3", "main.py"])

# Output fields: result.stdout, result.stderr, result.exit_code

# Files (on sandbox handle)
sandbox.files.write("/app/main.py", content="print('hello')")
sandbox.files.write("/app/data.bin", content=b"\x00\x01\x02")
content = sandbox.files.read("/app/main.py")          # → str
data    = sandbox.files.read("/app/data.bin")          # → bytes
entries = sandbox.files.list("/app")                   # → list[FileEntry]
sandbox.files.delete("/app/old.txt")
sandbox.files.mkdir("/app/subdir")
sandbox.files.move("/app/old.txt", "/app/new.txt")

# Events (SSE)
for event in sandbox.events.stream():
    print(event.type, event.data)
    if event.type in ("build.completed", "build.failed", "build.timed_out"):
        break

# Templates
templates = client.sandbox_templates.list()
template  = client.sandbox_templates.get(template_id)
template  = client.sandbox_templates.create(
    name="my-template",
    image="miosa-sandbox",
    description="optional",
)
client.sandbox_templates.delete(template_id)
```

### Computers

`client.computers`

```python
# CRUD
computer = client.computers.create(
    name="runner-1",
    template_type="miosa-desktop",
    size="small",                       # "small" | "medium" | "large"
    selected_apps=["vscode", "chrome"],
    workspace_id="ws-uuid",             # assign to workspace (optional)
    external_workspace_id="org_abc",    # your own workspace ref (optional)
    external_project_id="proj_xyz",     # your own project ref (optional)
    idempotency_key="uuid-v4",
)
computer = client.computers.get(computer_id)
result   = client.computers.list(workspace_id="ws-uuid")  # workspace_id filter optional
client.computers.update(computer_id, agent_session_id="session-uuid")
client.computers.delete(computer_id)

# Lifecycle
client.computers.start(computer_id)
client.computers.stop(computer_id)
client.computers.restart(computer_id)
clone = client.computers.clone(computer_id)
client.computers.resize(computer_id, size="medium")
client.computers.move(computer_id, region="us-east-ny")

# Access tokens
vnc  = client.computers.vnc_credentials(computer_id)
tok  = client.computers.stream_token(computer_id)
urls = client.computers.urls(computer_id)
apps = client.computers.list_apps(computer_id)

# Auto-stop
cfg = client.computers.get_auto_stop(computer_id)
client.computers.update_auto_stop(computer_id, auto_stop_seconds=3600)

# Metrics
metrics = client.computers.metrics(computer_id, window="1h")

# Env vars
env_vars = client.computers.env.list(computer_id)
client.computers.env.create(computer_id, name="DATABASE_URL", value="postgres://...")
client.computers.env.update(computer_id, name="DATABASE_URL", value="postgres://new")
client.computers.env.delete(computer_id, name="DATABASE_URL")

# Port exposure
ports = client.computers.ports.list(computer_id)
client.computers.ports.create(computer_id, port=3000, visibility="public")
client.computers.ports.update(computer_id, port=3000, visibility="private")
client.computers.ports.delete(computer_id, port=3000)
```

### Desktop

`client.desktop` — desktop control for a running computer. All coordinates are pixels (0,0 = top-left).

```python
# Screenshots
png_bytes = client.desktop.screenshot(computer_id)
png_bytes = client.desktop.screenshot_region(computer_id, x=0, y=0, width=800, height=600)

# Mouse
client.desktop.click(computer_id, x=500, y=300, button="left")  # button: "left"|"right"|"middle"
client.desktop.double_click(computer_id, x=500, y=300)
client.desktop.move(computer_id, x=200, y=400)
client.desktop.mouse_down(computer_id, x=100, y=200, button="left")
client.desktop.mouse_up(computer_id, x=400, y=500, button="left")
client.desktop.drag(computer_id, start_x=100, start_y=200, end_x=400, end_y=500)
client.desktop.scroll(computer_id, x=500, y=300, direction="down", amount=3)
cursor = client.desktop.cursor(computer_id)  # → {"x": 500, "y": 300}

# Keyboard
client.desktop.type(computer_id, text="Hello, World!")
client.desktop.key(computer_id, key="ctrl+c")
client.desktop.hotkey(computer_id, keys=["ctrl", "shift", "t"])
client.desktop.key_down(computer_id, key="shift")
client.desktop.key_up(computer_id, key="shift")

# Clipboard
text = client.desktop.get_clipboard(computer_id)
client.desktop.set_clipboard(computer_id, text="Hello, World!")

# Screen info
size = client.desktop.screen_size(computer_id)   # → {"width": 1280, "height": 720}
env  = client.desktop.environment(computer_id)   # → display, session_type, user, de

# Wallpaper (white-label branding)
client.desktop.set_wallpaper(computer_id, url="https://cdn.example.com/bg.png")

# Accessibility tree (AT-SPI)
tree = client.desktop.accessibility_tree(computer_id)

# Flow control
client.desktop.wait(computer_id, seconds=2)

# Application launcher
client.desktop.launch(computer_id, app="firefox")

# Window management
windows = client.desktop.list_windows(computer_id)
client.desktop.focus_window(computer_id, window_id="0x2200003")
size = client.desktop.window_size(computer_id, window_id="0x2200003")
pos  = client.desktop.window_position(computer_id, window_id="0x2200003")
client.desktop.resize_window(computer_id, window_id="0x2200003", width=1024, height=768)
client.desktop.move_window(computer_id, window_id="0x2200003", x=50, y=50)
client.desktop.maximize_window(computer_id, window_id="0x2200003")
client.desktop.minimize_window(computer_id, window_id="0x2200003")
client.desktop.close_window(computer_id, window_id="0x2200003")
```

### Workspaces

`client.workspaces`

```python
workspaces = client.workspaces.list()
workspace  = client.workspaces.create(name="staging", description="Staging environment")
workspace  = client.workspaces.get(workspace_id)
workspace  = client.workspaces.update(workspace_id, name="staging-us-east")
client.workspaces.delete(workspace_id)

# Computers in a workspace
computers = client.workspaces.list_computers(workspace_id)

# Settings (resource limits)
settings  = client.workspaces.update_settings(
    workspace_id,
    max_computers=10,
    max_computer_size="large",
    default_computer_size="small",
    default_auto_stop_seconds=3600,
    allowed_template_types=[],
)

# Observability
stats = client.workspaces.stats(workspace_id)
usage = client.workspaces.usage(workspace_id, window="7d", granularity="day")
```

### Files

`client.files` — file system access inside a running computer or sandbox.

```python
# Upload / download
client.files.upload(computer_id, remote_path="/app/main.py", content="print('hi')")
client.files.upload(computer_id, remote_path="/app/data.bin", content=b"\x00\x01")
content   = client.files.download(computer_id, remote_path="/app/main.py")

# Directory listing
entries   = client.files.list(computer_id, path="/app")

# Metadata
stat      = client.files.stat(computer_id, path="/app/main.py")

# Mutations
client.files.delete(computer_id, path="/app/old.txt")
client.files.mkdir(computer_id, path="/app/subdir")
client.files.rename(computer_id, from_path="/app/old.txt", to_path="/app/new.txt")
client.files.copy(computer_id, from_path="/app/a.txt", to_path="/app/b.txt")
client.files.chmod(computer_id, path="/app/script.sh", mode="755")
```

### Exec

`client.exec` — run bash or Python without opening a desktop session.

```python
# Bash
result = client.exec.bash(
    computer_id,
    cmd="npm run build",
    cwd="/app",
    env={"NODE_ENV": "production"},
    timeout_sec=120,
)

# Python
result = client.exec.python(
    computer_id,
    code="import sys; print(sys.version)",
    cwd="/app",
    env={},
    timeout_sec=30,
)

# Output fields: result.stdout, result.stderr, result.exit_code
```

### Snapshots

`client.snapshots`

```python
snapshot  = client.snapshots.create(computer_id, label="before-upgrade")
snapshot  = client.snapshots.get(snapshot_id)
snapshots = client.snapshots.list(computer_id)
client.snapshots.restore(computer_id, snapshot_id=snapshot_id)
client.snapshots.delete(snapshot_id)
```

### Deployments

`client.deployments`

```python
deployment  = client.deployments.create(
    name="api-server",
    computer_id=computer_id,
    port=8080,
    domain="api.example.com",   # optional custom domain
)
deployment  = client.deployments.get(deployment_id)
deployments = client.deployments.list()
client.deployments.update(deployment_id, domain="api-v2.example.com")
client.deployments.delete(deployment_id)
```

### Databases

`client.databases` — managed Postgres instances.

```python
db  = client.databases.create(name="prod-db", plan="starter")
db  = client.databases.get(db_id)
dbs = client.databases.list()
client.databases.update(db_id, plan="pro")
client.databases.delete(db_id)

# Connection details
creds = client.databases.credentials(db_id)  # → {"connection_string": "postgres://..."}
```

### Storage

`client.storage` — object storage buckets and objects.

```python
# Buckets
bucket  = client.storage.create_bucket(name="my-bucket")
bucket  = client.storage.get_bucket(bucket_id)
buckets = client.storage.list_buckets()
client.storage.delete_bucket(bucket_id)

# Objects
client.storage.upload_object(bucket_id, key="path/file.txt", data=b"hello")
data    = client.storage.download_object(bucket_id, key="path/file.txt")
objects = client.storage.list_objects(bucket_id, prefix="path/")
client.storage.delete_object(bucket_id, key="path/file.txt")

# Signed URLs
url     = client.storage.signed_url(bucket_id, key="path/file.txt", expires_in=3600)
```

### Volumes

`client.volumes`

```python
volume  = client.volumes.create(name="data-vol", size_gb=20)
volume  = client.volumes.get(volume_id)
volumes = client.volumes.list()
client.volumes.resize(volume_id, size_gb=40)
client.volumes.attach(volume_id, computer_id=computer_id, mount_path="/mnt/data")
client.volumes.detach(volume_id, computer_id=computer_id)
client.volumes.delete(volume_id)
```

### Custom Domains

`client.domains`

```python
domain  = client.domains.create(domain="example.com", deployment_id=deployment_id)
domain  = client.domains.get(domain_id)
domains = client.domains.list()
client.domains.verify(domain_id)
client.domains.delete(domain_id)
```

### Functions

`client.functions` — `client.cron_jobs` — `client.health_checks` — `client.webhooks`

```python
# Serverless functions
fn   = client.functions.create(name="my-fn", runtime="python3.11", handler="main.handler")
fn   = client.functions.get(fn_id)
fns  = client.functions.list()
res  = client.functions.invoke(fn_id, payload={"key": "value"})
client.functions.update(fn_id, handler="main.v2_handler")
client.functions.delete(fn_id)

# Cron jobs
job  = client.cron_jobs.create(name="nightly", schedule="0 2 * * *", function_id=fn_id)
job  = client.cron_jobs.get(job_id)
jobs = client.cron_jobs.list()
client.cron_jobs.update(job_id, schedule="0 3 * * *")
client.cron_jobs.delete(job_id)

# Health checks
hc   = client.health_checks.create(name="api", url="https://api.example.com/health")
hc   = client.health_checks.get(hc_id)
hcs  = client.health_checks.list()
client.health_checks.delete(hc_id)

# Webhooks
wh   = client.webhooks.create(url="https://example.com/hook", events=["computer.started"])
wh   = client.webhooks.get(wh_id)
whs  = client.webhooks.list()
client.webhooks.update(wh_id, events=["computer.started", "computer.stopped"])
client.webhooks.delete(wh_id)
```

### API Keys

`client.api_keys`

```python
key  = client.api_keys.create(name="ci-runner", scopes=["computers:read", "computers:write"])
key  = client.api_keys.get(key_id)
keys = client.api_keys.list()
client.api_keys.revoke(key_id)
```

### Tenant / Settings / Regions

`client.tenant` — `client.settings` — `client.regions`

```python
# Tenant
tenant   = client.tenant.get()
client.tenant.update(name="Acme Corp", logo_url="https://...")

# Settings
settings = client.settings.get()
client.settings.update(default_computer_size="medium", auto_stop_default=3600)

# Regions
regions  = client.regions.list()
region   = client.regions.get(region_slug)
```

### Dashboard / Analytics / Audit Log / Usage

`client.dashboard` — `client.analytics` — `client.audit_log` — `client.usage`

```python
# Dashboard summary
summary = client.dashboard.get()

# Analytics
stats   = client.analytics.computers(window="7d")
stats   = client.analytics.usage(window="30d")

# Audit log (paginated)
page = 1
while True:
    result = client.audit_log.list(page=page, per_page=50)
    for entry in result.items:
        print(entry.action, entry.created_at)
    if not result.has_next:
        break
    page += 1

# Credit & compute usage
usage = client.usage.credits(window="30d")
usage = client.usage.compute(window="30d")
```

### Channels / Integrations / External Keys

`client.channels` — `client.integrations` — `client.external_keys`

```python
# Channels
ch   = client.channels.create(name="alerts", type="slack", config={"webhook_url": "..."})
chs  = client.channels.list()
client.channels.delete(ch_id)

# Integrations
intg = client.integrations.create(provider="github", token="ghp_...")
intg = client.integrations.get(intg_id)
ints = client.integrations.list()
client.integrations.delete(intg_id)

# External keys (BYOK — bring your own key)
ek   = client.external_keys.create(provider="openai", key="sk-...")
eks  = client.external_keys.list()
client.external_keys.delete(ek_id)
```

### MCP

`client.mcp`

```python
server  = client.mcp.create_server(name="my-mcp", image="miosa-mcp-base")
server  = client.mcp.get_server(server_id)
servers = client.mcp.list_servers()
client.mcp.delete_server(server_id)
```

### Models / Completions / Embeddings

`client.models` — `client.completions` — `client.embeddings`

```python
# Model discovery
models  = client.models.list()
model   = client.models.get(model_id)

# Completions (Optimal / proxied LLM)
resp    = client.completions.create(
    model="qwen3:32b",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=512,
    stream=False,
)

# Streaming completions
for chunk in client.completions.stream(model="qwen3:32b", messages=[...]):
    print(chunk.delta, end="", flush=True)

# Async streaming
async for chunk in client.completions.astream(model="qwen3:32b", messages=[...]):
    print(chunk.delta, end="", flush=True)

# Embeddings
result  = client.embeddings.create(model="nomic-embed-text", input="The quick brown fox")
vectors = result.embeddings  # list[list[float]]

# Provider defaults & benchmarks
defaults   = client.provider_defaults.get()
client.provider_defaults.update(default_model="qwen3:32b")
benchmarks = client.benchmarks.list()
```

### Command Center / Builder Sessions / Community

`client.command_center` — `client.builder_sessions` — `client.community`

```python
# Command center (Optimal sessions across a fleet of computers)
session  = client.command_center.create_session(
    computer_ids=["comp-1", "comp-2"],
    instructions="Run the test suite on all machines",
)
session  = client.command_center.get_session(session_id)
sessions = client.command_center.list_sessions()
client.command_center.cancel_session(session_id)

# Builder sessions (agent-assisted app builds)
bs   = client.builder_sessions.create(computer_id=computer_id, goal="Build a React app")
bs   = client.builder_sessions.get(bs_id)
bss  = client.builder_sessions.list()
client.builder_sessions.cancel(bs_id)

# Community templates
templates = client.community.list_templates()
template  = client.community.get_template(template_id)
client.community.fork_template(template_id, name="my-fork")
```

### OpenComputers

`client.open_computers` — headless compute hosts, jobs, files, tunnels, agents, clusters.

```python
# Hosts
host  = client.open_computers.hosts.create(name="worker-1", region="us-east-ny")
host  = client.open_computers.hosts.get(host_id)
hosts = client.open_computers.hosts.list()
client.open_computers.hosts.delete(host_id)

# Jobs
job   = client.open_computers.jobs.create(
    host_id=host_id,
    image="ubuntu:22.04",
    cmd=["bash", "-c", "echo hello"],
)
job   = client.open_computers.jobs.get(job_id)
jobs  = client.open_computers.jobs.list(host_id=host_id)
client.open_computers.jobs.cancel(job_id)

# Files (on open computers)
client.open_computers.files.upload(host_id, remote_path="/data/input.csv", content=b"...")
data  = client.open_computers.files.download(host_id, remote_path="/data/output.csv")
ls    = client.open_computers.files.list(host_id, path="/data")

# Tunnels
tunnel  = client.open_computers.tunnels.create(host_id=host_id, port=8080)
tunnels = client.open_computers.tunnels.list(host_id=host_id)
client.open_computers.tunnels.delete(tunnel_id)

# Agents
agent   = client.open_computers.agents.create(host_id=host_id, name="my-agent")
agents  = client.open_computers.agents.list(host_id=host_id)
client.open_computers.agents.delete(agent_id)

# Clusters
cluster  = client.open_computers.clusters.create(name="gpu-cluster", size=4)
cluster  = client.open_computers.clusters.get(cluster_id)
clusters = client.open_computers.clusters.list()
client.open_computers.clusters.delete(cluster_id)
```

### Admin

`client.admin` — tenant administrator endpoints. Requires an `admin`-scoped API key.

```python
# Tenant management
tenants = client.admin.tenants.list()
tenant  = client.admin.tenants.get(tenant_id)
client.admin.tenants.suspend(tenant_id)
client.admin.tenants.unsuspend(tenant_id)

# User management
users = client.admin.users.list(tenant_id=tenant_id)
user  = client.admin.users.get(user_id)
client.admin.users.remove(user_id)

# API key management
keys = client.admin.api_keys.list()
client.admin.api_keys.revoke(key_id)
stats = client.admin.api_keys.stats()

# Platform metrics
metrics = client.admin.metrics.platform()
metrics = client.admin.metrics.compute()
```

---

## Resource coverage

| Resource group | Methods | Available |
|---|---|---|
| Sandboxes (create, get, list, destroy, exec, run, events, files) | 12 | ✓ |
| Sandbox templates | 4 | ✓ |
| Computers (CRUD + lifecycle + env + ports + metrics) | 22 | ✓ |
| Desktop (screenshot, mouse, keyboard, clipboard, windows, a11y) | 24 | ✓ |
| Workspaces (CRUD + settings + stats + usage) | 9 | ✓ |
| Files (upload, download, list, stat, delete, mkdir, rename, copy, chmod) | 9 | ✓ |
| Exec (bash, python) | 2 | ✓ |
| Snapshots | 5 | ✓ |
| Deployments | 5 | ✓ |
| Databases (managed Postgres) | 6 | ✓ |
| Storage (buckets + objects + signed URLs) | 9 | ✓ |
| Volumes | 7 | ✓ |
| Custom domains | 5 | ✓ |
| Functions / cron jobs / health checks / webhooks | 20 | ✓ |
| API keys | 4 | ✓ |
| Tenant / regions / settings | 6 | ✓ |
| Dashboard / analytics / audit log / usage | 7 | ✓ |
| Channels / integrations / external keys | 9 | ✓ |
| MCP | 4 | ✓ |
| Models / completions / embeddings / provider defaults / benchmarks | 9 | ✓ |
| Command center / builder sessions / community | 12 | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | 21 | ✓ |
| Admin (tenants, users, api-keys, metrics) | 11 | ✓ |
| Credits | — | — |

---

## Common patterns

### Workspace-scoped creation

```python
from miosa import Miosa

client = Miosa()

# Create a workspace for a customer
ws = client.workspaces.create(name="acme-staging")

# All computers created here are isolated inside acme-staging
computer = client.computers.create(
    name="dev-box",
    template_type="miosa-desktop",
    size="small",
    workspace_id=ws.id,
    external_workspace_id="org_acme",   # map to your own system
    external_project_id="proj_api",
)

# List only acme-staging computers
computers = client.computers.list(workspace_id=ws.id)

# Usage attribution per workspace
usage = client.workspaces.usage(ws.id, window="30d")
```

### Desktop automation with async

```python

from miosa import AsyncMiosa

async def automate(computer_id: str) -> None:
    async with AsyncMiosa() as client:
        # Take a screenshot before doing anything
        before = await client.desktop.screenshot(computer_id)

        # Open a browser
        await client.desktop.launch(computer_id, app="firefox")
        await client.desktop.wait(computer_id, seconds=2)

        # Navigate via address bar
        await client.desktop.key(computer_id, key="ctrl+l")
        await client.desktop.type(computer_id, text="https://miosa.ai")
        await client.desktop.key(computer_id, key="Return")
        await client.desktop.wait(computer_id, seconds=3)

        # Take a screenshot after navigation
        after = await client.desktop.screenshot(computer_id)

        # Read the accessibility tree to find elements
        tree = await client.desktop.accessibility_tree(computer_id)

asyncio.run(automate("your-computer-id"))
```

### Desktop automation with accessibility tree

```python
from miosa import Miosa

client = Miosa()
computer_id = "your-computer-id"

# Get the accessibility tree to locate buttons without guessing coordinates
tree = client.desktop.accessibility_tree(computer_id)

# Find a button by name and click its center
def find_node(node, name):
    if node.get("name") == name:
        return node
    for child in node.get("children", []):
        result = find_node(child, name)
        if result:
            return result

btn = find_node(tree["tree"], "Close")
if btn:
    cx = btn["x"] + btn["width"] // 2
    cy = btn["y"] + btn["height"] // 2
    client.desktop.click(computer_id, x=cx, y=cy)
```

### Idempotency key

Wrap mutating calls with an idempotency key so retries are safe:

```python

sandbox = client.sandboxes.create(
    image="miosa-sandbox",
    idempotency_key=str(uuid.uuid4()),
)
```

### Pagination

List endpoints accept `page` and `per_page` (or cursor-based `after`):

```python
page = 1
while True:
    result = client.audit_log.list(page=page, per_page=50)
    for entry in result.items:
        print(entry.action, entry.created_at)
    if not result.has_next:
        break
    page += 1
```

### Custom base URL (self-hosted)

```python
client = Miosa(
    api_key="msk_live_...",
    base_url="https://api.your-domain.com/api/v1",
)
```

### Webhook verification

```python

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

### Exec with environment and working directory

```python
result = sandbox.run(
    "npm run build",
    opts={"cwd": "/app", "env": {"NODE_ENV": "production"}, "timeout_sec": 120},
)
print(result.stdout)
```

## Where to next

  Full endpoint reference with request/response schemas
  Run your first sandbox in 60 seconds
  Computers, sandboxes, and the resource model
  Switch to the TypeScript SDK

---

# TypeScript SDK

URL: https://miosa.ai/docs/sdks/typescript
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/typescript
Source: src/routes/docs/sdks/typescript/+page.md
Description: Install, configure, and make your first request with the MIOSA TypeScript SDK.

The official TypeScript/JavaScript SDK for MIOSA. Works with Node.js 18+, Deno, Bun, and modern bundlers. Fully typed — no `any`.

## Install

```bash
npm install @miosa/sdk
```

```bash
pnpm add @miosa/sdk
```

```bash
yarn add @miosa/sdk
```

```bash
bun add @miosa/sdk
```

```typescript

```

  The package will be available on npm as `@miosa/sdk`. Until first publish, install from GitHub: `npm install Miosa-osa/miosa#main` (or `pnpm add github:Miosa-osa/miosa#main`).

## First request

```typescript

const client = new Miosa({ apiKey: "msk_live_..." });

// Create a sandbox, run a command, destroy it
const sandbox = await client.sandboxes.create({ templateId: "miosa-sandbox" });
const result = await sandbox.exec.run("python3 -c 'print(1 + 1)'");
console.log(result.stdout); // "2\n"
await sandbox.destroy();
```

## Configure

| Option | Env var | Default | Description |
|---|---|---|---|
| `apiKey` | `MIOSA_API_KEY` | — | Workspace key (`msk_live_*`) |
| `baseUrl` | `MIOSA_BASE_URL` | `https://api.miosa.ai/api/v1` | API endpoint |
| `timeout` | — | `30000` | Per-request timeout in milliseconds |
| `maxRetries` | — | `3` | Automatic retries on 429 / 5xx |

```typescript

// Reads MIOSA_API_KEY from process.env
const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

// Explicit configuration
const client2 = new Miosa({
  apiKey: "msk_live_...",
  baseUrl: "https://api.miosa.ai/api/v1",
  timeout: 60_000,
  maxRetries: 3,
});
```

  The constructor throws synchronously if `apiKey` is omitted or does not start with `msk_`.

## Authentication

The API key is sent as `Authorization: Bearer <key>` on every request.

```typescript

// Standard — key from environment
const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

// With additional default headers (e.g., for white-label proxies)
const client2 = new Miosa({
  apiKey: "msk_live_...",
  defaultHeaders: { "X-Tenant-ID": "acme-corp" },
});
```

## Async vs sync

All methods return `Promise`. Use `await` or `.then()`. There is no separate sync client — Node.js is always async.

```typescript
// Sequential
const sandbox = await client.sandboxes.create({ templateId: "miosa-sandbox" });
const result = await sandbox.exec.run("echo hello");

// Parallel
const [sb1, sb2] = await Promise.all([
  client.sandboxes.create({ name: "worker-a" }),
  client.sandboxes.create({ name: "worker-b" }),
]);
```

## Error handling

```typescript

  Miosa,
  MiosaError,
  AuthenticationError,
  NotFoundError,
  PermissionError,
  RateLimitError,
  ValidationError,
  InsufficientCreditsError,
  ServerError,
} from "@miosa/sdk";

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

try {
  await client.computers.get("nonexistent-id");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Computer not found");
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (err instanceof PermissionError) {
    console.log("Access denied");
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited — retry after ${err.retryAfter}s`);
  } else if (err instanceof ValidationError) {
    console.log("Validation failed:", err.message);
  } else if (err instanceof InsufficientCreditsError) {
    console.log("Top up credits at miosa.ai/billing");
  } else if (err instanceof ServerError) {
    console.log(`Server error ${err.statusCode}`);
  } else if (err instanceof MiosaError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}
```

## Streaming events

`sandbox.events.stream()` returns an `AsyncIterableIterator<Record<string, unknown>>` (SSE events as plain objects):

```typescript
for await (const event of sandbox.events.stream()) {
  const type = event["type"] as string | undefined;
  console.log(type, event["data"]);
  if (["build.completed", "build.failed", "build.timed_out"].includes(type ?? "")) {
    break;
  }
}
```

Computer desktop events via `client.events.subscribe()`:

```typescript
const sub = await client.events.subscribe(computerId, {
  subscribe: ["window", "file", "process"],
  paths: ["/home/user/projects"],
});
for await (const ev of sub) {
  console.log(ev.type, ev.payload);
}
```

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, destroy, exec, events, files, previews, tags, snapshots) | ✓ |
| Computers (CRUD + lifecycle) | ✓ |
| Computer sub-resources (terminal, env, ports, volumes, logs, auto-stop, OSA) | ✓ |
| Desktop (screenshot, click, type, drag, scroll, key, windows) | ✓ |
| Files (upload, download, list, delete) | ✓ |
| Exec | ✓ |
| Deployments | ✓ |
| Databases (managed Postgres) | ✓ |
| Storage (object storage) | ✓ |
| Volumes | ✓ |
| Custom domains (flat + per-deployment) | ✓ |
| Functions / cron jobs / health checks / webhooks | ✓ |
| Sandbox templates | ✓ |
| API keys | ✓ |
| Tenant / regions / settings | ✓ |
| Dashboard / analytics / audit log / usage | ✓ |
| Channels / integrations / project integrations | ✓ |
| External keys | ✓ |
| MCP | ✓ |
| Models / completions / embeddings | ✓ |
| Provider defaults / benchmarks | ✓ |
| Command center / builder sessions / community | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | ✓ |
| Admin | ✓ |
| Snapshots (standalone) | ✓ |
| Credits | ✓ |

## Common patterns

### Idempotency key

```typescript

const sandbox = await client.sandboxes.create({
  templateId: "miosa-sandbox",
  idempotencyKey: randomUUID(),
});
```

### Pagination

```typescript
let cursor: string | undefined;
do {
  const page = await client.auditLog.list({ after: cursor, limit: 50 });
  for (const entry of page.items) {
    console.log(entry.action, entry.createdAt);
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

### Custom base URL (self-hosted)

```typescript
const client = new Miosa({
  apiKey: "msk_live_...",
  baseUrl: "https://api.your-domain.com/api/v1",
});
```

### Webhook verification

```typescript

function verifyWebhook(payload: Buffer, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  return expected === signature;
}
```

## Where to next

  Full endpoint reference with request/response schemas
  Run your first sandbox in 60 seconds
  Computers, sandboxes, and the resource model
  Switch to the Python SDK