# MIOSA Documentation - Full Text

Generated: 2026-06-09T07:08:00.015Z
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, deploy, and operate AI-generated applications on managed compute.

# MIOSA Documentation

Build, preview, deploy, and operate AI-generated applications from one API. MIOSA gives your product isolated sandboxes for code work, live previews for iteration, durable deployments for production, desktop computers for browser agents, and white-label controls for customer-owned experiences.

<div class="docs-hero-actions">
  <a class="docs-hero-cta primary" href="/docs/quickstart/">Start building →</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-06-09">June 9, 2026</time></p>

---

## Start here


    Create a sandbox, run a command, expose a live preview, and understand the resource model before wiring MIOSA into your product.



    Use isolated Linux environments for generated code, dependency installs, file edits, build commands, tests, and preview servers.



    Publish generated applications to stable URLs with versions, releases, environment variables, dynamic runtimes, and rollback paths.



    Put previews, deployments, browser tokens, and customer attribution behind your own product and domain model.



    Give agents a full Linux desktop when they need browsers, screenshots, clicks, uploads, form fills, or human handoff.



    Use the REST API directly, ship with SDKs, or automate workflows from the CLI. Always trust URLs returned by the API.


---

## What you can build


    An agent writes files into a sandbox, runs builds, opens previews, applies feedback, snapshots progress, and publishes a production app.



    Give each customer isolated workspaces, branded preview domains, deployment domains, custom domains, browser tokens, and usage attribution.



    Turn prompts into published landing pages, intake forms, calculators, content hubs, and campaign sites without exposing MIOSA.



    Run apps that need a server process, API routes, background work, environment variables, and persistent release management.



    Execute user code in isolated environments, stream stdout and stderr, capture artifacts, and shut work down when finished.



    Use Computers for real browser sessions: navigate, click, type, upload files, capture screenshots, and hand control to users.



    Bring third-party computer capacity into MIOSA while keeping one API, one product surface, and one user relationship.



    Measure sandbox lifecycles, desktop readiness, screenshot/action latency, and task success across agent workflows.


---

## Platform guides

---

## Developer surfaces

| Surface | Use it when |
|---|---|
| [REST API](/docs/api-reference/) | You want complete control over sandboxes, files, exec, previews, deployments, computers, domains, tokens, and events. |
| [CLI](/docs/cli/) | You want to create, inspect, publish, and debug resources from a terminal. |
| [Python SDK](/docs/sdks/python/) | You are building agent loops, backend orchestration, or data workflows in Python. |
| [TypeScript SDK](/docs/sdks/typescript/) | You are building Node services, web backends, or product integrations in TypeScript. |
| [MCP server](/docs/mcp/) | You want an AI agent to use MIOSA tools through the Model Context Protocol. |
| [Agent Development Kit](/docs/adk/) | You want higher-level agent building blocks on top of the raw sandbox and deployment APIs. |

---

## For LLMs

MIOSA publishes machine-readable docs indexes so agents can retrieve current public documentation without scraping the site.

---

## Current production contract

Use URLs returned by the API instead of constructing hostnames yourself:

- `preview_url` for sandbox previews.
- `desktop_url` for computer desktops.
- `public_url` for deployments.
- `custom_domain` or deployment-domain URLs when a workspace has branded domains configured.

See the [changelog](/docs/changelog/) for the latest public platform behavior.

<style>
  .docs-hero-actions {
    display: flex;
    flex-wrap: wrap;
    gap: 0.75rem;
    margin: 1.5rem 0 0.75rem;
  }

  .docs-hero-cta {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-height: 2.5rem;
    padding: 0 1rem;
    border-radius: 6px;
    border: 1px solid var(--dbd, #333);
    font-size: 0.9375rem;
    font-weight: 600;
    line-height: 1;
    text-decoration: none !important;
  }

  .docs-hero-cta.primary {
    background: var(--dt, #fff);
    border-color: var(--dt, #fff);
    color: var(--dbg, #1a1a1a);
  }

  .docs-hero-cta.secondary {
    background: transparent;
    color: var(--dt, #fff);
  }

  .docs-hero-cta:hover {
    text-decoration: none !important;
    border-color: var(--dt3, #777);
  }

  :global(html:not(.dark)) .docs-hero-cta.primary {
    background: #171717;
    border-color: #171717;
    color: #fff;
  }

  :global(html:not(.dark)) .docs-hero-cta.secondary {
    color: #171717;
  }
</style>

---

# Agent Development Kit (ADK)

URL: https://miosa.ai/docs/adk
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/adk
Source: src/routes/docs/adk/+page.md
Description: Build LLM agents that use MIOSA sandboxes, desktops, and deploys with the tool-call loop already wired. TypeScript ADK first; Python next.

# Agent Development Kit (ADK)

The MIOSA ADK lets you build production-ready LLM agents that natively use
MIOSA primitives  -  sandboxes, full desktop environments, and one-click
deploys  -  with the tool-call loop already wired.

If `@miosa/sdk` is "call MIOSA APIs from code", `@miosa/adk` is **"build an
AGENT that uses MIOSA"**.

```bash
npm install @miosa/adk @anthropic-ai/sdk
```

---

## 30-second example

```typescript

const agent = new Agent({
  provider: anthropicProvider({
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-opus-4-7",
  }),
  miosaApiKey: process.env.MIOSA_API_KEY!,
});

const result = await agent.run({
  prompt:
    "Create a MIOSA sandbox, write a Python hello-world, run it, then destroy the sandbox.",
  maxIterations: 10,
});

console.log(result.finalText);
```

That's it. The agent boots a sandbox, writes the file, runs it, prints
output, destroys the sandbox, returns the final response. No tool-loop
boilerplate.

---

## ADK vs SDK

The raw TypeScript SDK around MIOSA's REST API. You call methods:

```typescript
const computer = await client.computers.create({ name: "x" });
await computer.exec.bash("echo hello");
```

Use this when you're **writing application code** that talks to MIOSA.

Adds the agent loop on top. You give it a provider + prompt:

```typescript
const agent = new Agent({ provider, miosaApiKey });
await agent.run({ prompt: "build a flask app and run it" });
```

Use this when you're **building an agent** that should use MIOSA.

---

## Built-in MIOSA tools

When you pass `miosaApiKey`, the agent gets these tools out of the box:

| Tool | Does |
|------|------|
| `create_sandbox` | Boot a Debian 12 microVM (Python + Node). |
| `create_desktop` | Start a full desktop environment. |
| `list_sandboxes` | List your active computers. |
| `get_sandbox` | Fetch one sandbox by id (status / IP). |
| `destroy_sandbox` | Delete a computer. |
| `exec` | Run a bash command. |
| `exec_python` | Run a Python snippet inline. |
| `read_file` | Read a file from the VM. |
| `write_file` | Write a file inside the VM. |
| `list_files` | List a directory inside the VM. |

Get an API key at <https://miosa.ai/dashboard/api-keys>, or run
`npx -y @miosa/cli mcp install` to wire one via browser-based auth.

---

## Custom tools

Compose your own tool catalogue alongside (or instead of) the MIOSA tools:

```typescript

  Agent,
  anthropicProvider,
  miosaTools,
  type Tool,
} from "@miosa/adk";

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

const sendSlack: Tool = {
  name: "send_slack",
  description: "Post a message to the #builds Slack channel.",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"],
  },
  async execute(args) {
    const text = String(args["text"] ?? "");
    // your Slack call here
    return `Sent: ${text}`;
  },
};

const agent = new Agent({
  provider: anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  tools: [...miosaTools({ client: miosa }), sendSlack],
});
```

---

## Streaming step events

Drive a live UI as the agent runs:

```typescript
const result = await agent.run({
  prompt: "...",
  onStep: (step) => {
    console.log(`[turn ${step.index}] ${step.text}`);
    for (const call of step.toolCalls) {
      console.log(
        `  → ${call.name}(${JSON.stringify(call.input)}) → ${call.output.slice(0, 80)}`,
      );
    }
  },
});
```

The `AgentStep` shape:

```typescript
interface AgentStep {
  index: number;
  text: string;
  toolCalls: Array<{
    id: string;
    name: string;
    input: Record<string, unknown>;
    output: string;
    isError: boolean;
  }>;
  usage?: { inputTokens: number; outputTokens: number };
}
```

---

## Providers

`@miosa/adk` ships with one provider today; the `Provider` interface is small
enough that adding more is straightforward.

```typescript

const provider = anthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-opus-4-7", // default
  maxTokens: 4096, // default
});
```

Uses `@anthropic-ai/sdk` Messages API with native tool-use. Supports any
Claude model that supports tool calling.

Implement the `Provider` interface for OpenAI, Gemini, Ollama, or anything
that supports tool use:

```typescript

const openaiProvider: Provider = {
  name: "openai",
  model: "gpt-4o",
  async step(args: ProviderStepArgs): Promise {
    // 1. translate args.messages + args.tools into OpenAI's format
    // 2. call openai.chat.completions.create(...)
    // 3. extract text + tool_calls + stop_reason
    return { text, toolCalls, stopReason: "end_turn" };
  },
};

const agent = new Agent({ provider: openaiProvider, miosaApiKey: "..." });
```

PRs adding first-party OpenAI / Gemini / Ollama providers are welcome at
[the MIOSA monorepo](https://github.com/Miosa-osa/miosa/tree/main/sdks/adk-typescript).

---

## Termination

`agent.run()` returns when:

- The model emits an `end_turn` with no further tool calls (normal completion)
- A `stop_sequence` is hit
- `maxIterations` is reached (default 10)  -  safety guard against runaway loops
- The provider throws (returned as `stopReason: "error"`)

```typescript
const result = await agent.run({ prompt: "...", maxIterations: 20 });
if (result.stopReason === "max_iterations") {
  console.warn("Agent didn't finish in 20 turns");
}
```

---

## Quick comparison

| | `@miosa/adk` | Anthropic Claude Agent SDK | OpenAI Agents SDK | Google ADK |
|--|--|--|--|--|
| Tool-call loop | ✓ | ✓ | ✓ | ✓ |
| MIOSA tools built-in | **✓** |  -  |  -  |  -  |
| Anthropic provider | ✓ | ✓ |  -  |  -  |
| OpenAI provider | (BYO) |  -  | ✓ |  -  |
| Sub-agents | (roadmap) | ✓ | ✓ | ✓ |
| Memory | (roadmap) | ✓ | (basic) | ✓ |
| Cost | free | free | free | free |

The ADK is intentionally small. If you want MIOSA-as-execution-substrate
with a clean agent loop, you're in the right place.

---

## What's coming next

- **Python ADK** (`pip install miosa-adk`)  -  same surface, Python ergonomics.
- **More providers**  -  first-party OpenAI, Gemini, Ollama.
- **Sub-agents**  -  spawn child agents with scoped tool subsets.
- **Memory**  -  built-in conversation memory with TTL + summarization.
- **Streaming output**  -  token-by-token via provider.streamStep.

Open an issue at <https://github.com/Miosa-osa/miosa/issues> if there's
something you need sooner.

---

# 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  -  command service 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).

---

# Audit Log API

URL: https://miosa.ai/docs/api-reference/audit-log
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/audit-log
Source: src/routes/docs/api-reference/audit-log/+page.md
Description: Retrieve a cursor-paginated audit log of all actions taken within your tenant.

The audit log records all significant actions performed within your tenant  -  resource creation and deletion, API key usage, settings changes, and more. Results are cursor-paginated and ordered newest-first.

Base path: `/api/v1/audit-log`

Audit events are immutable. There is no write API. The log is append-only and retained for 90 days on Pro plans, 365 days on Enterprise.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/audit-log` | Fetch recent audit events |

---

## List Audit Events

**`GET /api/v1/audit-log`**

### Auth

```
Authorization: Bearer msk_...
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `limit` | integer | No | `50` | Events per page (max `100`) |
| `after` | string | No |  -  | Cursor from previous response's `next_cursor` |
| `type` | string | No |  -  | Filter by event type prefix (e.g. `sandbox.`) |
| `actor_id` | string | No |  -  | Filter by actor user ID |
| `resource_type` | string | No |  -  | Filter by resource type (e.g. `sandbox`) |
| `resource_id` | string | No |  -  | Filter by resource ID |

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "id": "evt_01hwxyz...",
      "type": "sandbox.created",
      "actor": {
        "type": "api_key",
        "id": "user_clinic_42"
      },
      "resource": {
        "type": "sandbox",
        "id": "sbx_abc123"
      },
      "ts": "2026-05-26T10:14:23Z",
      "metadata": {
        "image": "debian-12-sandbox-v8",
        "workspace_id": "ws_01hwxyz..."
      }
    }
  ],
  "next_cursor": "MjAyNi0wNS0yNlQxMDoxNDoyM1o"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `data[].id` | string | Unique event ID |
| `data[].type` | string | Dot-namespaced event type |
| `data[].actor.type` | string | `"user"` or `"api_key"` |
| `data[].actor.id` | string | User ID or `external_user_id` for API key actors |
| `data[].resource.type` | string | Resource type (e.g. `sandbox`, `computer`, `webhook`) |
| `data[].resource.id` | string | Resource ID |
| `data[].ts` | string | ISO 8601 timestamp |
| `data[].metadata` | object | Event-specific detail fields |
| `next_cursor` | string | Opaque cursor; omitted when no more pages |

### Common Event Types

| Type | Trigger |
|------|---------|
| `sandbox.created` | Sandbox provisioned |
| `sandbox.destroyed` | Sandbox deleted |
| `sandbox.exec` | `POST /exec` called |
| `computer.created` | Computer provisioned |
| `computer.stopped` | Computer stopped |
| `computer.deleted` | Computer deleted |
| `snapshot.created` | Snapshot initiated |
| `api_key.created` | API key minted |
| `api_key.deleted` | API key revoked |
| `tenant.preview_domain.set` | Preview domain configured |
| `webhook.created` | Outgoing webhook created |
| `quota.upserted` | Per-user quota set |
| `settings.updated` | Tenant settings changed |

Use the `type` filter with a prefix to narrow events (e.g. `type=sandbox.` returns all sandbox events).

---

## Pagination

Audit events are returned newest-first. To page forward:

1. Issue the initial request without `after`.
2. If `next_cursor` is present, re-issue with `after={next_cursor}`.
3. Stop when `next_cursor` is absent.

Cursors are opaque base64url strings encoding a timestamp. Do not parse or construct them.

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 |  -  | Invalid cursor format |

---

## Examples

```bash
# First page
curl "https://api.miosa.ai/api/v1/audit-log?limit=50&type=sandbox." \
  -H "Authorization: Bearer msk_live_..."

# Next page
curl "https://api.miosa.ai/api/v1/audit-log?limit=50&after=MjAyNi0wNS0yNlQxMDoxNDoyM1o" \
  -H "Authorization: Bearer msk_live_..."

# Filter by resource
curl "https://api.miosa.ai/api/v1/audit-log?resource_type=computer&resource_id=cmp_xyz789" \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Page through all sandbox events in the last page
cursor = None
while True:
    page = client.audit_log.list(
        type="sandbox.",
        limit=100,
        after=cursor,
    )
    for event in page.data:
        print(event.type, event.resource.id, event.ts)
    if not page.next_cursor:
        break
    cursor = page.next_cursor
```

```typescript

const client = new Miosa();

let cursor: string | undefined;

do {
  const page = await client.auditLog.list({
    type: 'sandbox.',
    limit: 100,
    after: cursor,
  });

  for (const event of page.data) {
    console.log(event.type, event.resource.id, event.ts);
  }

  cursor = page.nextCursor;
} while (cursor);
```

---

# 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 with a Linux desktop, streamed desktop access, and APIs for exec, files, apps, metrics, and desktop control. 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.computer.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"
}
```

`sandbox_url` is a legacy preview field on the Computer response. Use `desktop_url` for the desktop stream and the `/computers/{id}/urls` endpoint for short-lived desktop and terminal URLs.

### 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 Desktop Stream Credentials

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

Returns credentials for direct desktop streaming access.

### Response  -  `200 OK`
```json
{
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "ws_url": "wss://my-computer.computer.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 desktop 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.computer.miosa.ai/desktop/index.html",
  "stream_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "terminal_url": "wss://my-computer.computer.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.

### Response  -  `200 OK`

Response 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` | Computer command service unavailable |

---

## 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 computer command service 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 computer command service |

---

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

---

# Egress (Security) API

URL: https://miosa.ai/docs/api-reference/egress
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/egress
Source: src/routes/docs/api-reference/egress/+page.md
Description: API reference for the MIOSA Egress credential vault, network allowlist, OAuth Connect, and audit log.

The Egress API powers the **Security** tab on every Computer and Sandbox: encrypted credential vault, OAuth Connect, network allowlist with audit-only / enforce modes, and a live-tail audit log.

Base path: `/api/v1/egress`

All endpoints require `Authorization: Bearer &lt;msk_*&gt;`. See [Authentication](/docs/authentication). For higher-level access, use the [SDKs](/docs/sdks/egress).

For the architecture overview, walkthroughs, and white-label patterns, see the [Security guides](/docs/security).

---

## Secrets

### Create a secret

**`POST /api/v1/egress/secrets`**

Stores an encrypted credential and optionally binds it to a resource as an environment variable. The raw value is encrypted with ChaCha20-Poly1305 and never returned again.

```bash
curl -X POST https://api.miosa.ai/api/v1/egress/secrets \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai_key",
    "value": "sk-proj-...",
    "type": "api_key",
    "scope": "user",
    "expose_as_env": "OPENAI_API_KEY"
  }'
```

Required body fields: `name`, `value`, `type`, `scope`.

| Field | Values | Notes |
|---|---|---|
| `type` | `api_key`, `oauth_connect`, `oauth_machine` | OAuth flows are usually initiated via `/oauth/start` instead. |
| `scope` | `tenant`, `workspace`, `user`, `external_user`, `external_workspace` | The 5-tier scoping model. |
| `expose_as_env` | shell-safe upper-snake-case | If set, auto-creates a binding. |

Optional scoping fields based on `scope`: `workspace_id`, `owner_user_id`, `external_user_id`, `external_workspace_id`.

Returns `201 Created` with `{data: <public_secret>, binding: <binding_or_null>}`. The `data.preview` is the first-6 + last-4 of the value; the full value is never returned.

### List secrets

**`GET /api/v1/egress/secrets`**

Query params: `scope`, `workspace_id`, `owner_user_id`, `external_user_id`, `external_workspace_id`.

Returns metadata only (no values).

### Get a secret

**`GET /api/v1/egress/secrets/:id`**  -  metadata for one secret.

### Rotate

**`PATCH /api/v1/egress/secrets/:id`**

Re-encrypts with a new value. The bound `placeholder_token` does not change; every sandbox using it picks up the new value on its next outbound request.

```json
{ "value": "sk-proj-new-value", "expires_at": "2026-12-31T00:00:00Z" }
```

### Delete

**`DELETE /api/v1/egress/secrets/:id`**

---

## Bindings

A binding links a secret to a Computer or Sandbox and surfaces it as an environment variable (or opaque header token).

### Create a binding

**`POST /api/v1/egress/bindings`**

```json
{
  "secret_id": "<uuid>",
  "resource_id": "<computer-or-sandbox-id>",
  "resource_type": "sandbox",
  "exposure": "env_var",
  "expose_as_env": "OPENAI_API_KEY"
}
```

Returns the binding including its `placeholder_token`  -  the opaque `miosa-tok-…` value the workload sees in env.

### List + delete

- `GET /api/v1/egress/bindings?resource_id=<id>&resource_type=sandbox`
- `DELETE /api/v1/egress/bindings/:id`

---

## OAuth Connect

### List provider catalog

**`GET /api/v1/egress/oauth/providers`**  -  returns providers visible to the calling tenant (platform defaults merged with tenant overrides). No client secrets exposed.

### Start an OAuth flow

**`POST /api/v1/egress/oauth/start`**

```json
{
  "provider": "github",
  "expose_as_env": "GITHUB_TOKEN",
  "scope": "user",
  "owner_user_id": "<uuid>"
}
```

Returns `{authorize_url, state}`. Open `authorize_url` in a browser; the user approves; the upstream redirects to `/api/v1/egress/oauth/callback?code=&state=`. On success the tokens are encrypted into a new `oauth_connect` secret + binding.

### Status

**`GET /api/v1/egress/oauth/status?state=<state>`**  -  poll while the user is completing the flow. Returns `pending`, `complete`, or `failed`.

### Admin: tenant-override providers (white-label)

- `POST /api/v1/egress/oauth/admin/providers`  -  register your own OAuth app credentials so end-users see your brand on the consent screen.
- `DELETE /api/v1/egress/oauth/admin/providers/:id`

Requires admin (`msk_a_*`) credentials.

---

## Network policies + allowlist

### Policies

- `GET /api/v1/egress/policies`  -  list (optionally filter by `resource_id`)
- `POST /api/v1/egress/policies`  -  create
- `GET /api/v1/egress/policies/:id`
- `PATCH /api/v1/egress/policies/:id`  -  set `mode` (`audit_only` / `enforce`), `default_action` (`allow` / `deny`)

Each Computer or Sandbox resolves the policy in this order: resource override → tenant default. Tenant default starts in `audit_only` mode.

### Allowlist rules

- `GET /api/v1/egress/allowlist?policy_id=<uuid>`
- `POST /api/v1/egress/allowlist`
- `DELETE /api/v1/egress/allowlist/:id`

```json
{
  "policy_id": "<uuid>",
  "pattern": "*.openai.com",
  "kind": "wildcard",
  "method": "POST",
  "path_glob": "/v1/*",
  "action": "allow",
  "warn_only": false,
  "priority": 100
}
```

Pattern kinds: `exact` (literal host), `wildcard` (`*.example.com`), `cidr` (IP literal targets only).

---

## Audit log

### Query

**`GET /api/v1/egress/audit`**

Query params: `resource_id`, `host`, `action` (`allow`/`reject`/`stub`/`error`), `since` (relative like `1h` / `7d` or ISO timestamp), `until`, `limit` (default 100, max 1000), `external_user_id`, `external_workspace_id`.

Each row includes the full identity chain (`tenant_id`, `workspace_id`, `owner_user_id`, `external_user_id`, `external_workspace_id`), request metadata (`host`, `method`, `path`, `sni`, `mode`, `remote_addr`), outcome (`action`, `rejected_by`, `status_code`, `duration_ms`, `bytes_in`, `bytes_out`, `error_message`), and the transform trace JSONB (`request_transforms`, `response_transforms`, `mcp`).

### Get a single event

**`GET /api/v1/egress/audit/:id`**

### Allowlist suggestions

**`GET /api/v1/egress/audit/suggestions?resource_id=<id>`**  -  returns the hosts a resource has contacted recently, ranked by frequency. The basis for the one-click "Lock down with selected as allowlist" UX.

### Live tail (WebSocket)

**`wss://api.miosa.ai/api/v1/egress/audit/resource/:resource_id?token=<jwt>`**

Subprotocol: `miosa-egress-audit-v1`. Pushes `{"type":"audit_event","data":{...}}` frames in real time as outbound requests are recorded.

Tenant-scoped variant (admin only): `wss://api.miosa.ai/api/v1/egress/audit/tenant/:tenant_id?token=<jwt>`.

---

## Rate limits + retention

| Scope | Limit |
|---|---|
| All `/egress/*` endpoints | 300 req/min per API key |
| Audit retention | 90 days for every tenant; longer on enterprise |
| Audit live-tail (WebSocket) | unlimited; does not count against REST quota |

---

## Errors

Same envelope as the rest of the API  -  `{"error": "...", "details": ...}` with the appropriate status code.

| Status | When |
|---|---|
| `400` | invalid body, unknown scope, malformed env var name |
| `401` | missing / invalid credential |
| `403` | role does not allow the operation (e.g., creating tenant-scoped secret as a non-admin) |
| `404` | secret / binding / policy / event not found in this tenant |
| `409` | secret name collision within scope (unique partial index) |
| `422` | scope ↔ identity column mismatch (e.g., scope=user without owner_user_id) |

---

## SDK shortcut

All endpoints above are wrapped by the [Egress SDK reference](/docs/sdks/egress) with idiomatic methods in Python, TypeScript, Go, Java, and Elixir.

---

# 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 computer command service 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 | computer command service 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 computer 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 /workspace", "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 /workspace && 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(\"/workspace\"):\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 `/workspace`, `/home`, `/root`, `/tmp`, `/opt`, and `/srv`.

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

The computer must be in `"running"` status. All operations go through the computer command service.

---

## 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: `/workspace/` |

### Response  -  `201 Created`
```json
{
  "success": true,
  "file": {
    "path": "/workspace/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=/workspace/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: `/workspace` |

### 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": "/workspace"
}
```

### 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=/workspace" \
  -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=/workspace/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": "/workspace/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": "/workspace/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": "/workspace/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": "/workspace/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 `/workspace`, `/home`, `/root`, `/tmp`, `/opt`, or `/srv`
3. **Rejection**  -  Paths outside these prefixes return `403 FORBIDDEN_PATH`

This prevents path traversal attacks. For example, `/workspace/../../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 computer command service and restricted to allowed paths.

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

**Allowed paths:** `/workspace`, `/home`, `/root`, `/tmp`, `/opt`, `/srv`

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: '/workspace/hello.py',
  content: 'print("Hello from MIOSA")',
});

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

// Download it back
const content = await client.files.download(computerId, '/workspace/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: `/workspace/` |

### Response  -  `201 Created`
```json
{
  "success": true,
  "file": {
    "path": "/workspace/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=/workspace/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": "/workspace/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": "/workspace/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: `/workspace` |

### 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": "/workspace"
}
```
```bash
curl "https://api.miosa.ai/api/v1/computers/{id}/files?path=/workspace" \
  -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=/workspace/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": "/workspace/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": "/workspace/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": "/workspace/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": "/workspace/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": "/workspace/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=/workspace/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": "/workspace/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": "/workspace/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": "/workspace/old.txt", "destination": "/workspace/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": "/workspace/app.py", "destination": "/workspace/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": "/workspace/template.py", "destination": "/workspace/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": "/workspace/template.py", "destination": "/workspace/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": "/workspace/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": "/workspace/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 `/workspace`, `/home`, `/root`, `/tmp`, `/opt`, or `/srv`
3. **Rejection**  -  Paths outside these prefixes return `403 FORBIDDEN_PATH`

`/workspace/../../etc/passwd` expands to `/etc/passwd` and is rejected.

---

## Common Recipes

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

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

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

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

---

# Invites API

URL: https://miosa.ai/docs/api-reference/invites
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/invites
Source: src/routes/docs/api-reference/invites/+page.md
Description: API reference for the workspace invite and org invite flows  -  send, list, revoke, preview, and accept email invitations.

MIOSA has two parallel invite flows:

- **Workspace invites**  -  invite a user to a specific workspace. If the email already belongs to an org member, the user is added directly (no email sent). If not, an invite email is dispatched and accepting it creates both the `tenant_members` and `workspace_members` rows atomically.
- **Org invites**  -  invite a user to join the org (tenant) without pre-selecting a workspace. The accept step only creates the `tenant_members` row.

Both flows produce opaque tokens. The `GET /invites/:token` and `GET /workspace-invites/:token` preview endpoints are **public**  -  they can be called without an API key to render a landing page before the user signs in.

---

## Workspace Invite Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/workspaces/{id}/invites` | Required | Send a workspace invite |
| `GET` | `/workspaces/{id}/invites` | Required | List pending invites |
| `DELETE` | `/workspaces/{id}/invites/{invite_id}` | Required | Revoke an invite |
| `GET` | `/workspace-invites/{token}` | None (public) | Preview invite details |
| `POST` | `/workspace-invites/{token}/accept` | Required | Accept the invite |

## Org Invite Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/tenants/{id}/invites` | Required (admin/owner) | Send an org invite |
| `GET` | `/tenants/{id}/invites` | Required (admin/owner) | List pending org invites |
| `DELETE` | `/tenants/{id}/invites/{invite_id}` | Required (admin/owner) | Revoke an org invite |
| `GET` | `/invites/{token}` | None (public) | Preview org invite details |
| `POST` | `/invites/{token}/accept` | Required | Accept the org invite |

---

## Workspace Invite Flow

### Send Workspace Invite

**`POST /api/v1/workspaces/{id}/invites`**

Sends an invite email and returns the invite record. If the `email` already belongs to a tenant member the user is added directly (response `type = "added"`, no email sent).

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Email address to invite |
| `role` | string | Yes | `owner`, `admin`, `member`, or `viewer` |

#### Response  -  `201 Created` (new invite)

```json
{
  "type": "invited",
  "data": {
    "id": "inv_abc123",
    "workspace_id": "ws-uuid",
    "tenant_id": "ten-uuid",
    "email": "alice@example.com",
    "role": "member",
    "invited_by": "usr_owner",
    "expires_at": "2026-05-29T09:00:00Z",
    "accepted_at": null,
    "inserted_at": "2026-05-22T09:00:00Z"
  }
}
```

#### Response  -  `200 OK` (existing member added directly)

```json
{
  "type": "added",
  "data": {
    "user_id": "usr_def456",
    "workspace_id": "ws-uuid",
    "role": "member",
    "joined_at": "2026-05-22T09:00:00Z",
    "added_by": "usr_owner"
  }
}
```


```bash
curl -X POST https://api.miosa.ai/api/v1/workspaces/{id}/invites \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "role": "member"}'
```


```typescript

const client = new Miosa();

const result = await client.workspaceInvites.create('ws-uuid', {
  email: 'alice@example.com',
  role: 'member',
});
// result.type === 'invited' | 'added'
```


```python

client = miosa.Miosa()

result = client.workspace_invites.create("ws-uuid", "alice@example.com", "member")
print(result["type"])  # "invited" or "added"
```


```go
result, err := client.WorkspaceInvites.Create(ctx, "ws-uuid", miosa.CreateWorkspaceInviteInput{
    Email: "alice@example.com",
    Role:  "member",
})
```


```elixir
{:ok, result} = Miosa.WorkspaceInvites.create(client, "ws-uuid", "alice@example.com", "member")
IO.inspect(result["type"])
```


```java
Map<String,Object> result = miosa.workspaceInvites().create("ws-uuid", "alice@example.com", "member");
String type = (String) result.get("type"); // "invited" or "added"
```


---

### List Workspace Invites

**`GET /api/v1/workspaces/{id}/invites`**

Returns all pending workspace invites (excludes accepted and revoked).

#### Response  -  `200 OK`

```json
{
  "data": [
    {
      "id": "inv_abc123",
      "workspace_id": "ws-uuid",
      "tenant_id": "ten-uuid",
      "email": "alice@example.com",
      "role": "member",
      "invited_by": "usr_owner",
      "expires_at": "2026-05-29T09:00:00Z",
      "accepted_at": null,
      "inserted_at": "2026-05-22T09:00:00Z"
    }
  ]
}
```


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


```typescript
const invites = await client.workspaceInvites.list('ws-uuid');
```


```python
invites = client.workspace_invites.list("ws-uuid")
```


```go
invites, err := client.WorkspaceInvites.List(ctx, "ws-uuid")
```


```elixir
{:ok, invites} = Miosa.WorkspaceInvites.list(client, "ws-uuid")
```


```java
List<Map<String,Object>> invites = miosa.workspaceInvites().list("ws-uuid");
```


---

### Revoke Workspace Invite

**`DELETE /api/v1/workspaces/{id}/invites/{invite_id}`**

Revokes a pending invite. Returns `409` if the invite was already accepted.

#### Response  -  `200 OK`

```json
{ "invite_id": "inv_abc123", "revoked": true }
```


```bash
curl -X DELETE https://api.miosa.ai/api/v1/workspaces/{id}/invites/{invite_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```


```typescript
await client.workspaceInvites.revoke('ws-uuid', 'inv_abc123');
```


```python
client.workspace_invites.revoke("ws-uuid", "inv_abc123")
```


```go
_, err := client.WorkspaceInvites.Revoke(ctx, "ws-uuid", "inv_abc123")
```


```elixir
{:ok, _} = Miosa.WorkspaceInvites.revoke(client, "ws-uuid", "inv_abc123")
```


```java
miosa.workspaceInvites().revoke("ws-uuid", "inv_abc123");
```


---

### Preview Workspace Invite (public)

**`GET /api/v1/workspace-invites/{token}`**

Returns invite metadata without requiring authentication. Use this to render the pre-auth landing page.

#### Response  -  `200 OK`

```json
{
  "data": {
    "workspace_name": "Dr. Smith Clinic",
    "role": "member",
    "expires_at": "2026-05-29T09:00:00Z",
    "expired": false,
    "accepted": false
  }
}
```


```bash
curl https://api.miosa.ai/api/v1/workspace-invites/{token}
```


```typescript
const preview = await client.workspaceInvites.preview(token);
if (!preview.expired) {
  // show accept button
}
```


```python
preview = client.workspace_invites.preview(token)
if not preview["expired"]:
    pass  # show accept button
```


```go
preview, err := client.WorkspaceInvites.Preview(ctx, token)
```


```elixir
{:ok, preview} = Miosa.WorkspaceInvites.preview(client, token)
unless preview["expired"], do: ...
```


```java
Map<String,Object> preview = miosa.workspaceInvites().preview(token);
```


---

### Accept Workspace Invite

**`POST /api/v1/workspace-invites/{token}/accept`**

Accepts the invite on behalf of the authenticated user. If the user is new to the org, a `tenant_members` row is created atomically alongside the `workspace_members` row.

The caller's API key email must match the invite email (case-insensitive).

#### Response  -  `200 OK`

```json
{
  "accepted": true,
  "workspace_id": "ws-uuid",
  "tenant_id": "ten-uuid",
  "role": "member"
}
```

#### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_TOKEN` | Token not found or expired |
| 400 | `REVOKED` | Invite was revoked |
| 422 | `EMAIL_MISMATCH` | Authenticated user's email differs from invite email |


```bash
curl -X POST https://api.miosa.ai/api/v1/workspace-invites/{token}/accept \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```


```typescript
const result = await client.workspaceInvites.accept(token);
console.log('joined workspace:', result.workspaceId);
```


```python
result = client.workspace_invites.accept(token)
print("joined workspace:", result["workspace_id"])
```


```go
result, err := client.WorkspaceInvites.Accept(ctx, token)
```


```elixir
{:ok, result} = Miosa.WorkspaceInvites.accept(client, token)
IO.puts("joined workspace: #{result["workspace_id"]}")
```


```java
Map<String,Object> result = miosa.workspaceInvites().accept(token);
```


---

## Org Invite Flow

Org invites grant membership in the tenant (org) without assigning a specific workspace.
Write operations require `admin` or `owner` role.

### Send Org Invite

**`POST /api/v1/tenants/{id}/invites`**

Dispatches an invite email. The response includes an `invite_url` that is host-aware  -  on white-label tenants it uses the tenant's custom domain.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Email address to invite |
| `role` | string | Yes | `owner`, `admin`, or `member` |

#### Response  -  `201 Created`

```json
{
  "data": {
    "invite_id": "inv_xyz789",
    "email": "bob@example.com",
    "role": "member",
    "expires_at": "2026-05-29T09:00:00Z",
    "invite_url": "https://app.miosa.ai/invites/eyJ..."
  }
}
```


```bash
curl -X POST https://api.miosa.ai/api/v1/tenants/{id}/invites \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@example.com", "role": "member"}'
```


```typescript
const invite = await client.orgInvites.create(tenantId, {
  email: 'bob@example.com',
  role: 'member',
});
console.log('invite URL:', invite.inviteUrl);
```


```python
invite = client.org_invites.create(tenant_id, "bob@example.com", "member")
print("invite URL:", invite["invite_url"])
```


```go
invite, err := client.OrgInvites.Create(ctx, tenantID, miosa.CreateOrgInviteInput{
    Email: "bob@example.com",
    Role:  "member",
})
```


```elixir
{:ok, invite} = Miosa.OrgInvites.create(client, tenant_id, "bob@example.com", "member")
IO.puts("invite URL: #{invite["invite_url"]}")
```


```java
Map<String,Object> invite = miosa.orgInvites().create(tenantId, "bob@example.com", "member");
System.out.println("invite URL: " + invite.get("invite_url"));
```


---

### List Org Invites

**`GET /api/v1/tenants/{id}/invites`**

Returns all pending org invites.


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


```typescript
const invites = await client.orgInvites.list(tenantId);
```


```python
invites = client.org_invites.list(tenant_id)
```


```go
invites, err := client.OrgInvites.List(ctx, tenantID)
```


```elixir
{:ok, invites} = Miosa.OrgInvites.list(client, tenant_id)
```


```java
List<Map<String,Object>> invites = miosa.orgInvites().list(tenantId);
```


---

### Revoke Org Invite

**`DELETE /api/v1/tenants/{id}/invites/{invite_id}`**

Revokes a pending org invite. Returns `409` if the invite was already accepted.


```bash
curl -X DELETE https://api.miosa.ai/api/v1/tenants/{id}/invites/{invite_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```


```typescript
await client.orgInvites.revoke(tenantId, inviteId);
```


```python
client.org_invites.revoke(tenant_id, invite_id)
```


```go
_, err := client.OrgInvites.Revoke(ctx, tenantID, inviteID)
```


```elixir
{:ok, _} = Miosa.OrgInvites.revoke(client, tenant_id, invite_id)
```


```java
miosa.orgInvites().revoke(tenantId, inviteId);
```


---

### Preview Org Invite (public)

**`GET /api/v1/invites/{token}`**

Returns invite metadata without authentication.

#### Response  -  `200 OK`

```json
{
  "data": {
    "email": "bob@example.com",
    "tenant_name": "Acme Corp",
    "role": "member",
    "expires_at": "2026-05-29T09:00:00Z",
    "expired": false,
    "accepted": false
  }
}
```


```bash
curl https://api.miosa.ai/api/v1/invites/{token}
```


```typescript
const preview = await client.orgInvites.preview(token);
console.log('invited to org:', preview.tenantName);
```


```python
preview = client.org_invites.preview(token)
print("invited to org:", preview["tenant_name"])
```


```go
preview, err := client.OrgInvites.Preview(ctx, token)
```


```elixir
{:ok, preview} = Miosa.OrgInvites.preview(client, token)
IO.inspect(preview["tenant_name"])
```


```java
Map<String,Object> preview = miosa.orgInvites().preview(token);
```


---

### Accept Org Invite

**`POST /api/v1/invites/{token}/accept`**

Accepts an org invite on behalf of the authenticated user. Creates a `tenant_members` row.

The caller's API key email must match the invite email (case-insensitive).

#### Response  -  `200 OK`

```json
{
  "accepted": true,
  "tenant_id": "ten-uuid",
  "tenant": {
    "id": "ten-uuid",
    "name": "Acme Corp"
  }
}
```

#### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `invalid_token` | Token not found or expired |
| 422 | `EMAIL_MISMATCH` | Session email differs from invite email |


```bash
curl -X POST https://api.miosa.ai/api/v1/invites/{token}/accept \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```


```typescript
const result = await client.orgInvites.accept(token);
console.log('joined org:', result.tenantId);
```


```python
result = client.org_invites.accept(token)
print("joined org:", result["tenant_id"])
```


```go
result, err := client.OrgInvites.Accept(ctx, token)
```


```elixir
{:ok, result} = Miosa.OrgInvites.accept(client, token)
IO.puts("joined org: #{result["tenant_id"]}")
```


```java
Map<String,Object> result = miosa.orgInvites().accept(token);
```


---

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_TOKEN` / `invalid_token` | Token not found, expired, or revoked |
| 400 | `REVOKED` | Invite was explicitly revoked |
| 409 | `ALREADY_ACCEPTED` | Cannot revoke an invite that was already accepted |
| 422 | `EMAIL_MISMATCH` | Authenticated user's email does not match the invite email |
| 422 | `MISSING_EMAIL` | `email` field missing from request body |

---

## See also

- [Workspace Members API](/docs/api-reference/members)  -  manage the roster directly (requires prior org membership)
- [Workspaces API](/docs/api-reference/workspaces)  -  workspace CRUD
- [Error Codes](/docs/api-reference/errors)  -  full error reference

---

# Workspace Members API

URL: https://miosa.ai/docs/api-reference/members
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/members
Source: src/routes/docs/api-reference/members/+page.md
Description: API reference for managing workspace member rosters  -  add, remove, and update roles for users inside a workspace.

Workspace members are the user roster for a specific workspace. A user must already be an org member (`tenant_members` row) before they can be added to a workspace. The last `owner` in a workspace cannot be removed until another member is promoted to owner.

Base path: `/api/v1/workspaces/:id/members`

To invite a new user who is not yet an org member, use the [Workspace Invites API](/docs/api-reference/invites) instead. Accepting a workspace invite automatically creates the `tenant_members` row when the user is new to the org.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/workspaces/{id}/members` | List workspace members |
| `POST` | `/workspaces/{id}/members` | Add an existing org member to the workspace |
| `PATCH` | `/workspaces/{id}/members/{user_id}` | Update a member's role |
| `DELETE` | `/workspaces/{id}/members/{user_id}` | Remove a member |

---

## Roles

| Role | Description |
|------|-------------|
| `owner` | Full admin including transfer and deletion |
| `admin` | Can manage members and resources |
| `member` | Can create and manage resources |
| `viewer` | Read-only access |

---

## List Members

**`GET /api/v1/workspaces/{id}/members`**

Returns all members of the workspace.

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "user_id": "usr_abc123",
      "email": "alice@example.com",
      "name": "Alice",
      "avatar_url": null,
      "role": "owner",
      "joined_at": "2026-05-01T10:00:00Z",
      "added_by": null
    },
    {
      "user_id": "usr_def456",
      "email": "bob@example.com",
      "name": "Bob",
      "avatar_url": null,
      "role": "member",
      "joined_at": "2026-05-10T14:00:00Z",
      "added_by": "usr_abc123"
    }
  ]
}
```


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


```typescript

const client = new Miosa();

const members = await client.workspaceMembers.list('ws-uuid');
console.log(members);
```


```python

client = miosa.Miosa()
members = client.workspace_members.list("ws-uuid")
print(members)
```


```go

client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))
members, err := client.WorkspaceMembers.List(ctx, "ws-uuid")
```


```elixir
client = Miosa.client("msk_u_...")
{:ok, members} = Miosa.WorkspaceMembers.list(client, "ws-uuid")
```


```java
MiosaClient miosa = new MiosaClient("msk_u_...");
List<Map<String,Object>> members = miosa.workspaceMembers().list("ws-uuid");
```


---

## Add Member

**`POST /api/v1/workspaces/{id}/members`**

Adds an existing org member to the workspace with the given role.

The user must already hold a `tenant_members` row for this org. If they are not yet an org member, send a workspace invite via `POST /workspaces/{id}/invites` instead  -  accepting the invite creates the org membership atomically.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | UUID | Yes | The user's ID  -  must already be a tenant member |
| `role` | string | Yes | `owner`, `admin`, `member`, or `viewer` |

### Response  -  `201 Created`

```json
{
  "data": {
    "user_id": "usr_def456",
    "workspace_id": "ws-uuid",
    "role": "member",
    "joined_at": "2026-05-22T09:00:00Z",
    "added_by": "usr_abc123"
  }
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 422 | `NOT_TENANT_MEMBER` | User is not a member of the parent org |
| 422 | `MISSING_USER_ID` | `user_id` field missing |
| 422 | `MISSING_ROLE` | `role` field missing |
| 409 |  -  | User is already a workspace member |


```bash
curl -X POST https://api.miosa.ai/api/v1/workspaces/{id}/members \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_def456", "role": "member"}'
```


```typescript
const record = await client.workspaceMembers.add('ws-uuid', {
  userId: 'usr_def456',
  role: 'member',
});
```


```python
record = client.workspace_members.add("ws-uuid", user_id="usr_def456", role="member")
```


```go
record, err := client.WorkspaceMembers.Add(ctx, "ws-uuid", miosa.AddWorkspaceMemberInput{
    UserID: "usr_def456",
    Role:   "member",
})
```


```elixir
{:ok, record} = Miosa.WorkspaceMembers.add(client, "ws-uuid", "usr_def456", "member")
```


```java
Map<String,Object> record = miosa.workspaceMembers().add("ws-uuid", "usr_def456", "member");
```


---

## Update Member Role

**`PATCH /api/v1/workspaces/{id}/members/{user_id}`**

Changes a workspace member's role.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `role` | string | Yes | New role: `owner`, `admin`, `member`, or `viewer` |

### Response  -  `200 OK`

Updated workspace member record (same shape as the add response).

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 |  -  | User is not a member of this workspace |
| 422 | `MISSING_ROLE` | `role` field missing |


```bash
curl -X PATCH https://api.miosa.ai/api/v1/workspaces/{id}/members/{user_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'
```


```typescript
const updated = await client.workspaceMembers.updateRole('ws-uuid', 'usr_def456', {
  role: 'admin',
});
```


```python
updated = client.workspace_members.update_role("ws-uuid", "usr_def456", role="admin")
```


```go
updated, err := client.WorkspaceMembers.UpdateRole(ctx, "ws-uuid", "usr_def456",
    miosa.UpdateWorkspaceMemberRoleInput{Role: "admin"})
```


```elixir
{:ok, updated} = Miosa.WorkspaceMembers.update_role(client, "ws-uuid", "usr_def456", "admin")
```


```java
Map<String,Object> updated = miosa.workspaceMembers().updateRole("ws-uuid", "usr_def456", "admin");
```


---

## Remove Member

**`DELETE /api/v1/workspaces/{id}/members/{user_id}`**

Removes a user from the workspace. This does not remove them from the parent org.

### Response  -  `200 OK`

```json
{ "deleted": true }
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 |  -  | User is not a member of this workspace |
| 409 | `LAST_OWNER` | Cannot remove the last workspace owner  -  promote another member first |


```bash
curl -X DELETE https://api.miosa.ai/api/v1/workspaces/{id}/members/{user_id} \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```


```typescript
await client.workspaceMembers.remove('ws-uuid', 'usr_def456');
```


```python
client.workspace_members.remove("ws-uuid", "usr_def456")
```


```go
err := client.WorkspaceMembers.Remove(ctx, "ws-uuid", "usr_def456")
```


```elixir
{:ok, _} = Miosa.WorkspaceMembers.remove(client, "ws-uuid", "usr_def456")
```


```java
miosa.workspaceMembers().remove("ws-uuid", "usr_def456");
```


---

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 403 |  -  | Workspace belongs to a different tenant |
| 404 |  -  | Workspace or user not found |
| 409 | `LAST_OWNER` | Refusing to remove the sole workspace owner |
| 422 | `NOT_TENANT_MEMBER` | User must join the org before joining the workspace |
| 422 | `MISSING_USER_ID` | `user_id` body field is required |
| 422 | `MISSING_ROLE` | `role` body field is required |

---

## See also

- [Workspace Invites API](/docs/api-reference/invites)  -  invite users by email (creates org membership on accept)
- [Workspaces API](/docs/api-reference/workspaces)  -  workspace CRUD
- [Error Codes](/docs/api-reference/errors)  -  full error reference

---

# 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 microVM 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 /workspace/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": "/workspace/projects",
  "entries": [
    {
      "name": "my-app",
      "path": "/workspace/projects/my-app",
      "size": 0,
      "is_dir": true,
      "modified_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

---

## Terminal

### Issue a terminal ticket

**`POST /api/v1/opencomputers/hosts/{id}/terminal/ticket`**

Returns a short-lived WebSocket authentication ticket. Connect to `ws_url`
immediately using the ticket as a query parameter.
```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

---

# Preview Tokens API

URL: https://miosa.ai/docs/api-reference/preview-tokens
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/preview-tokens
Source: src/routes/docs/api-reference/preview-tokens/+page.md
Description: Generate short-lived signed tokens for iframe embedding without exposing an API key.

Preview tokens (`mp_*`) are short-lived signed credentials that allow you to embed a running sandbox in an `<iframe>` from a third-party frontend without exposing your `msk_*` API key to the browser.

Base path: `/api/v1/sandboxes/{id}/preview-token`

Preview tokens are single-resource. Each token is scoped to the sandbox it was minted for. Tokens expire after at most 24 hours.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/sandboxes/{id}/preview-token` | Mint a preview token |

---

## Mint a Preview Token

**`POST /api/v1/sandboxes/{id}/preview-token`**

Generates a signed preview token tied to the sandbox. The returned `url` is ready to use as an iframe `src`.

### Auth

Requires an API key or JWT with the `previews:write` scope.

```
Authorization: Bearer msk_...
```

### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `expires_in` | integer | No | `3600` | Token TTL in seconds (max `86400`) |
| `scope` | string | No | `"read"` | `"read"` or `"interact"` |

```json
{
  "expires_in": 3600,
  "scope": "read"
}
```

### Response  -  `200 OK`

```json
{
  "token": "mp_eyJhbGciOiJIUzI1NiJ9...",
  "url": "https://sbx-abc123.sandboxes.miosa.ai?mt=mp_eyJ...",
  "expires_at": "2026-05-26T04:00:00Z",
  "scope": "read"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `token` | string | Signed preview token (`mp_<base64url>`) |
| `url` | string | Iframe-ready URL with token pre-embedded as `?mt=` query param |
| `expires_at` | string | ISO 8601 expiry timestamp |
| `scope` | string | `"read"` or `"interact"` |

### Scopes

| Scope | Description |
|-------|-------------|
| `read` | View-only. Mouse and keyboard input are blocked. |
| `interact` | Full mouse/keyboard input forwarded into the sandbox. |

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `sandbox_not_found` | Sandbox does not exist or belongs to a different tenant |
| 403 | `forbidden` | Tenant mismatch |
| 422 | `invalid_scope` | `scope` is not `"read"` or `"interact"` |

---

## Examples

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/preview-token \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600, "scope": "read"}'
```

```python

client = miosa.Miosa()

token = client.sandboxes.preview_token(
    "sbx_abc123",
    expires_in=3600,
    scope="read",
)

print(token.url)  # embed this in your frontend
```

```typescript

const client = new Miosa();

const token = await client.sandboxes.previewToken('sbx_abc123', {
  expiresIn: 3600,
  scope: 'read',
});

// Pass token.url to your frontend  -  safe to expose in the browser
console.log(token.url);
```

---

## Token Format

Preview tokens use the prefix `mp_` followed by a base64url-encoded signed payload. The token is consumed by the sandbox proxy when passed as the `?mt=` query parameter. Do not parse the token body  -  treat it as opaque.

---

## Iframe Embedding

```html
<!-- Read-only embed  -  no API key in the browser -->
<iframe
  src="https://sbx-abc123.sandboxes.miosa.ai?mt=mp_eyJ..."
  width="1280"
  height="800"
  allow="clipboard-read; clipboard-write"
></iframe>
```

The token is verified by the sandbox proxy on every request during the token's lifetime. Once it expires, the iframe will show an access-denied page.

---

# 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

---

# Quotas API

URL: https://miosa.ai/docs/api-reference/quotas
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/quotas
Source: src/routes/docs/api-reference/quotas/+page.md
Description: Set per-end-user resource limits for white-label multi-tenant deployments.

Quotas let you cap how many sandboxes an individual end-user of your product can create and run. They are keyed by `external_user_id`  -  the same opaque identifier you pass when creating sandboxes on behalf of your users.

Base path: `/api/v1/quotas/external/{external_user_id}`

Quotas are enforced at sandbox creation time. Setting a quota does not affect sandboxes already running. Deleting a quota removes all limits for that user.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/quotas/external/{external_user_id}` | Get quota and current usage |
| `PUT` | `/api/v1/quotas/external/{external_user_id}` | Create or update a quota |
| `DELETE` | `/api/v1/quotas/external/{external_user_id}` | Remove quota (unlimited) |

---

## Get Quota

**`GET /api/v1/quotas/external/{external_user_id}`**

Returns the configured limits and live usage counters for the user.

### Auth

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK`

```json
{
  "data": {
    "external_user_id": "user_clinic_42",
    "limits": {
      "max_sandboxes": 10,
      "max_concurrent": 3,
      "max_storage_gb": 50,
      "max_credit_cents": 5000
    },
    "usage": {
      "total_sandboxes": 4,
      "concurrent": 1
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `limits.max_sandboxes` | integer\|null | Lifetime sandbox creation limit |
| `limits.max_concurrent` | integer\|null | Max sandboxes running simultaneously |
| `limits.max_storage_gb` | integer\|null | Total attached storage cap in GiB |
| `limits.max_credit_cents` | integer\|null | Spend cap in cents (platform credits) |
| `usage.total_sandboxes` | integer | Total sandboxes created by this user |
| `usage.concurrent` | integer | Currently running sandboxes |

A `null` limit means no cap is applied for that dimension.

---

## Set Quota

**`PUT /api/v1/quotas/external/{external_user_id}`**

Creates or replaces the quota. All limit fields are optional  -  omit a field to leave it uncapped.

### Request Body

```json
{
  "max_sandboxes": 10,
  "max_concurrent": 3,
  "max_storage_gb": 50,
  "max_credit_cents": 5000
}
```

### Response  -  `200 OK`

Same shape as GET response.

---

## Delete Quota

**`DELETE /api/v1/quotas/external/{external_user_id}`**

Removes all limits for the user. Future sandbox creation is governed only by your tenant plan.

### Response  -  `204 No Content`

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `not_found` | No quota exists for this `external_user_id` (GET/DELETE) |
| 422 | validation errors | A limit value is non-integer or negative |

---

## Examples

```bash
# Set
curl -X PUT https://api.miosa.ai/api/v1/quotas/external/user_clinic_42 \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"max_sandboxes": 10, "max_concurrent": 3}'

# Get
curl https://api.miosa.ai/api/v1/quotas/external/user_clinic_42 \
  -H "Authorization: Bearer msk_live_..."

# Remove
curl -X DELETE https://api.miosa.ai/api/v1/quotas/external/user_clinic_42 \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Set quota when user signs up
client.quotas.set("user_clinic_42", max_sandboxes=10, max_concurrent=3)

# Check quota + usage
quota = client.quotas.get("user_clinic_42")
print(quota.usage.concurrent)

# Remove limits
client.quotas.delete("user_clinic_42")
```

```typescript

const client = new Miosa();

// Set
await client.quotas.set('user_clinic_42', {
  maxSandboxes: 10,
  maxConcurrent: 3,
  maxStorageGb: 50,
});

// Get
const quota = await client.quotas.get('user_clinic_42');
console.log(quota.usage.concurrent);

// Remove
await client.quotas.delete('user_clinic_42');
```

---

# 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

---

# Sandbox Env API

URL: https://miosa.ai/docs/api-reference/sandbox-env
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandbox-env
Source: src/routes/docs/api-reference/sandbox-env/+page.md
Description: CRUD for per-sandbox environment variables, encrypted at rest.

The sandbox env API manages a key-value store of environment variables attached to a sandbox. Variables are encrypted at rest and injected into the sandbox process environment on start. The API never returns plaintext values  -  only key names and metadata.

Base path: `/api/v1/sandboxes/{id}/env`

Variable names must match `[A-Z][A-Z0-9_]*`  -  uppercase letters, digits, and underscores, starting with a letter. This mirrors POSIX shell environment variable conventions.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/sandboxes/{id}/env` | List all env vars (names only, no values) |
| `PUT` | `/api/v1/sandboxes/{id}/env` | Bulk set or update env vars |
| `DELETE` | `/api/v1/sandboxes/{id}/env/{key}` | Delete a single env var |

---

## List Env Vars

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

Returns all variable names. Values are never returned.

### Auth

Requires `sandboxes:read` scope.

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK`

```json
{
  "data": [
    { "key": "DATABASE_URL", "encrypted": true },
    { "key": "API_SECRET", "encrypted": true },
    { "key": "LOG_LEVEL", "encrypted": false }
  ]
}
```

---

## Set Env Vars

**`PUT /api/v1/sandboxes/{id}/env`**

Bulk upsert. Existing keys are updated; new keys are created. Keys not present in the request are left unchanged.

### Auth

Requires `sandboxes:write` scope.

```
Authorization: Bearer msk_...
```

### Request Body

```json
{
  "vars": [
    { "key": "DATABASE_URL", "value": "postgres://...", "encrypted": true },
    { "key": "LOG_LEVEL", "value": "debug" }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vars[].key` | string | Yes | Variable name (`[A-Z][A-Z0-9_]*`) |
| `vars[].value` | string | Yes | Variable value |
| `vars[].encrypted` | boolean | No | Store encrypted at rest (default: `true`) |

### Response  -  `200 OK`

```json
{
  "data": [
    { "key": "DATABASE_URL", "encrypted": true },
    { "key": "LOG_LEVEL", "encrypted": false }
  ]
}
```

---

## Delete Env Var

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

Removes a single variable.

### Response  -  `200 OK`

```json
{
  "deleted": true,
  "name": "LOG_LEVEL"
}
```

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_ID` | Sandbox ID is not a valid UUID |
| 400 | `invalid vars` | `vars` missing or a key fails name validation |
| 404 | `NOT_FOUND` | Sandbox does not exist or wrong tenant |
| 404 | `NOT_FOUND` | Key does not exist (on DELETE) |

---

## Examples

```bash
# Set
curl -X PUT https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/env \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vars": [
      {"key": "DATABASE_URL", "value": "postgres://user:pass@host/db"},
      {"key": "LOG_LEVEL", "value": "info"}
    ]
  }'

# List
curl https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/env \
  -H "Authorization: Bearer msk_live_..."

# Delete
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/env/LOG_LEVEL \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Set
client.sandboxes.env.set("sbx_abc123", {
    "DATABASE_URL": "postgres://user:pass@host/db",
    "LOG_LEVEL": "info",
})

# List (names only)
keys = client.sandboxes.env.list("sbx_abc123")

# Delete one
client.sandboxes.env.delete("sbx_abc123", "LOG_LEVEL")
```

```typescript

const client = new Miosa();

// Set
await client.sandboxes.env.set('sbx_abc123', {
  DATABASE_URL: 'postgres://user:pass@host/db',
  LOG_LEVEL: 'info',
});

// List
const { data } = await client.sandboxes.env.list('sbx_abc123');

// Delete
await client.sandboxes.env.delete('sbx_abc123', 'LOG_LEVEL');
```

---

# Sandbox Files (Advanced) API

URL: https://miosa.ai/docs/api-reference/sandbox-files-advanced
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandbox-files-advanced
Source: src/routes/docs/api-reference/sandbox-files-advanced/+page.md
Description: File tree traversal, batch write, and SSE file-watch for IDE-grade sandbox file operations.

These advanced file operations extend the core [Files API](/docs/api-reference/files) with IDE-oriented capabilities: recursive tree listing, atomic batch writes, and a live file-change event stream.

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

These routes use `:sandbox_id` as the path parameter internally but are accessed as `/sandboxes/{id}/files/...`  -  the `{id}` segment is the sandbox UUID.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/sandboxes/{id}/files/tree` | Recursive file tree |
| `POST` | `/api/v1/sandboxes/{id}/files/write-many` | Batch write multiple files |
| `GET` | `/api/v1/sandboxes/{id}/files/watch` | SSE stream of file-change events |

---

## File Tree

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

Returns a recursive directory listing up to a configurable depth. Useful for populating an IDE file-explorer panel.

### Auth

```
Authorization: Bearer msk_...
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `path` | string | `/workspace` | Root directory to list |
| `depth` | integer | `3` | Max traversal depth (1-10) |
| `include_hidden` | boolean | `false` | Include dot-files and dot-directories |

### Response  -  `200 OK`

```json
{
  "data": {
    "path": "/workspace",
    "type": "directory",
    "children": [
      {
        "name": "src",
        "path": "/workspace/src",
        "type": "directory",
        "children": [
          {
            "name": "index.ts",
            "path": "/workspace/src/index.ts",
            "type": "file",
            "size": 1842,
            "modified_at": "2026-05-26T09:12:01Z"
          }
        ]
      },
      {
        "name": "package.json",
        "path": "/workspace/package.json",
        "type": "file",
        "size": 512,
        "modified_at": "2026-05-25T18:00:00Z"
      }
    ]
  }
}
```

---

## Batch Write

**`POST /api/v1/sandboxes/{id}/files/write-many`**

Writes multiple files in a single request. All writes are applied atomically from the guest's perspective  -  either all succeed or an error is returned for the failing file.

Maximum 50 files per request. Files larger than 90 KB should be uploaded individually via `POST /files/write`.

### Request Body

```json
{
  "files": [
    {
      "path": "/workspace/src/index.ts",
      "content": "export const hello = () => 'world';\n",
      "encoding": "utf8"
    },
    {
      "path": "/workspace/src/utils.ts",
      "content": "ZXhwb3J0IGZ1bmN0aW9uIG5vb3AoKSB7fQo=",
      "encoding": "base64"
    }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `files[].path` | string | Yes | Absolute path inside the sandbox |
| `files[].content` | string | Yes | File content (UTF-8 text or base64-encoded binary) |
| `files[].encoding` | string | No | `"utf8"` (default) or `"base64"` |

### Response  -  `200 OK`

```json
{
  "data": {
    "written": 2,
    "paths": [
      "/workspace/src/index.ts",
      "/workspace/src/utils.ts"
    ]
  }
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_BODY` | `files` is missing or not an array |
| 400 | `TOO_MANY_FILES` | More than 50 files in one request |
| 400 | `INVALID_PATH` | A path contains a null byte or traverses outside the sandbox |

---

## File Watch (SSE)

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

Streams file-system change events as SSE. Useful for syncing editor state in real time.

### Auth

```
Authorization: Bearer msk_...
```

(Browser `EventSource` cannot set this header  -  use a server-side client or a scoped session token.)

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `path` | string | `/workspace` | Directory to watch |

### Response  -  `200 OK` (`text/event-stream`)

```
id: wev_001
event: file.changed
data: {"path":"/workspace/src/index.ts","event":"modified","ts":"2026-05-26T10:14:23Z"}

id: wev_002
event: file.changed
data: {"path":"/workspace/src/new-file.ts","event":"created","ts":"2026-05-26T10:14:24Z"}

: heartbeat
```

**Event values for `data.event`:**

| Value | Trigger |
|-------|---------|
| `created` | New file or directory |
| `modified` | File content changed |
| `deleted` | File or directory removed |
| `renamed` | File moved or renamed |

---

## Examples

```bash
# File tree (depth 2)
curl "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/files/tree?depth=2" \
  -H "Authorization: Bearer msk_live_..."

# Batch write
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/files/write-many \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"path": "/workspace/hello.ts", "content": "console.log(\"hello\");\n"}
    ]
  }'

# File watch (SSE)
curl -N -H "Authorization: Bearer msk_live_..." \
  -H "Accept: text/event-stream" \
  "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/files/watch?path=/workspace/src"
```

```python

client = miosa.Miosa()

# Tree
tree = client.sandboxes.files.tree("sbx_abc123", path="/workspace", depth=3)

# Batch write
client.sandboxes.files.write_many("sbx_abc123", [
    {"path": "/workspace/index.ts", "content": "export {};"},
    {"path": "/workspace/utils.ts", "content": "export function noop() {}"},
])
```

```typescript

const client = new Miosa();

// File tree
const tree = await client.sandboxes.files.tree('sbx_abc123', {
  path: '/workspace',
  depth: 3,
  includeHidden: false,
});

// Batch write
await client.sandboxes.files.writeMany('sbx_abc123', [
  { path: '/workspace/index.ts', content: 'export {};' },
  { path: '/workspace/utils.ts', content: 'export function noop() {}' },
]);
```

---

# Sandbox Processes API

URL: https://miosa.ai/docs/api-reference/sandbox-processes
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandbox-processes
Source: src/routes/docs/api-reference/sandbox-processes/+page.md
Description: Start, monitor, and stream logs for long-running background processes inside sandboxes.

The processes API lets you launch long-running background commands inside a sandbox and inspect their output  -  useful for starting dev servers, watchers, or any process that runs beyond a single exec call.

Base path: `/api/v1/sandboxes/{id}/processes`

Processes are managed by the sandbox runtime and survive for the lifetime of the sandbox. They are not preserved across snapshots or forks.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/sandboxes/{id}/processes` | Start a process |
| `GET` | `/api/v1/sandboxes/{id}/processes` | List processes |
| `GET` | `/api/v1/sandboxes/{id}/processes/{pid}` | Get process status |
| `DELETE` | `/api/v1/sandboxes/{id}/processes/{pid}` | Stop a process |
| `GET` | `/api/v1/sandboxes/{id}/processes/{pid}/logs` | Fetch recent log lines |
| `GET` | `/api/v1/sandboxes/{id}/processes/{pid}/stream` | SSE live log stream |

---

## Start a Process

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

### Auth

```
Authorization: Bearer msk_...
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cmd` | string | Yes | Command to run (passed to `/bin/sh -c`) |
| `cwd` | string | No | Working directory (default: `/workspace`) |
| `env` | object | No | Additional environment variables |
| `name` | string | No | Human-readable label |

```json
{
  "cmd": "npm run dev -- --port 3000",
  "cwd": "/workspace",
  "name": "dev-server"
}
```

### Response  -  `201 Created`

```json
{
  "data": {
    "pid": "proc_01hwxyz...",
    "name": "dev-server",
    "cmd": "npm run dev -- --port 3000",
    "cwd": "/workspace",
    "status": "running",
    "started_at": "2026-05-26T10:14:23Z",
    "exited_at": null,
    "exit_code": null
  }
}
```

---

## List Processes

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

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "pid": "proc_01hwxyz...",
      "name": "dev-server",
      "status": "running",
      "started_at": "2026-05-26T10:14:23Z",
      "exited_at": null,
      "exit_code": null
    }
  ]
}
```

---

## Get Process Status

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

### Response  -  `200 OK`

```json
{
  "data": {
    "pid": "proc_01hwxyz...",
    "name": "dev-server",
    "cmd": "npm run dev -- --port 3000",
    "cwd": "/workspace",
    "status": "exited",
    "started_at": "2026-05-26T10:14:23Z",
    "exited_at": "2026-05-26T10:22:01Z",
    "exit_code": 0
  }
}
```

**Process status values:**

| Status | Description |
|--------|-------------|
| `running` | Process is alive |
| `exited` | Process exited normally |
| `killed` | Process was stopped via DELETE |
| `error` | Process failed to start |

---

## Stop a Process

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

Sends `SIGTERM` followed by `SIGKILL` after a grace period.

### Response  -  `204 No Content`

---

## Fetch Logs

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

Returns the last N lines of stdout+stderr.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tail` | integer | `200` | Number of lines to return |

### Response  -  `200 OK`

```json
{
  "data": {
    "lines": [
      "  > Local:   http://localhost:3000",
      "  > Network: http://0.0.0.0:3000",
      "  ready in 743ms"
    ]
  }
}
```

---

## Live Log Stream (SSE)

**`GET /api/v1/sandboxes/{id}/processes/{pid}/stream`**

Streams stdout+stderr as SSE. Uses `text/event-stream`  -  requires Bearer token auth.

```
id: log_001
event: log
data: {"line":"  ready in 743ms","ts":"2026-05-26T10:14:24Z"}

: heartbeat
```

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_ID` | Sandbox ID is not a valid UUID |
| 404 | `NOT_FOUND` | Sandbox or process does not exist |
| 409 | `SANDBOX_NOT_RUNNING` | Sandbox must be in `running` state to start processes |
| 500 | `PROCESS_START_FAILED` | Runtime failed to spawn the process |

---

## Examples

```bash
# Start
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"cmd": "npm run dev -- --port 3000", "name": "dev-server"}'

# List
curl https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes \
  -H "Authorization: Bearer msk_live_..."

# Logs
curl "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes/proc_01hwxyz/logs?tail=50" \
  -H "Authorization: Bearer msk_live_..."

# Stop
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes/proc_01hwxyz \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Start a dev server
proc = client.sandboxes.processes.start(
    "sbx_abc123",
    cmd="npm run dev -- --port 3000",
    name="dev-server",
)

# Wait a moment then check logs
time.sleep(3)
logs = client.sandboxes.processes.logs("sbx_abc123", proc.pid, tail=50)
for line in logs:
    print(line)

# Stop
client.sandboxes.processes.stop("sbx_abc123", proc.pid)
```

```typescript

const client = new Miosa();

// Start
const proc = await client.sandboxes.processes.start('sbx_abc123', {
  cmd: 'npm run dev -- --port 3000',
  name: 'dev-server',
});

// Poll status
let status = proc.status;
while (status === 'running') {
  await new Promise(r => setTimeout(r, 2000));
  const updated = await client.sandboxes.processes.get('sbx_abc123', proc.pid);
  status = updated.status;
}

// Logs
const { data } = await client.sandboxes.processes.logs('sbx_abc123', proc.pid);
console.log(data.lines.join('\n'));
```

---

# Sandbox Shares API

URL: https://miosa.ai/docs/api-reference/sandbox-shares
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandbox-shares
Source: src/routes/docs/api-reference/sandbox-shares/+page.md
Description: Create and manage public share URLs for sandboxes.

Sandbox shares are publicly accessible URLs that give read-only access to a running sandbox. Unlike preview tokens, share URLs are not scoped to an iframe and do not require the recipient to hold any credentials.

Share tokens use the prefix `ms_` followed by a base64url-encoded payload. The public URL pattern is:

```
https://{sandbox-id}.sandboxes.miosa.ai?ms=ms_<token>
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/sandboxes/{id}/shares` | Create a share URL |
| `GET` | `/api/v1/sandboxes/{id}/shares` | List active shares |
| `DELETE` | `/api/v1/sandboxes/{id}/shares/{share_id}` | Revoke a share |

---

## Create a Share

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

Creates a public share link. The `share_url` field is safe to distribute  -  it contains the token as a query parameter.

### Auth

```
Authorization: Bearer msk_...
```

### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `expires_in` | integer | No | `3600` | TTL in seconds |
| `scope` | string | No | `"read"` | Must be `"read"` (only supported value) |

```json
{
  "expires_in": 86400
}
```

### Response  -  `201 Created`

```json
{
  "share_id": "shr_01hx9m7n3k...",
  "share_url": "https://sbx-abc123.sandboxes.miosa.ai?ms=ms_eyJ...",
  "expires_at": "2026-05-27T12:00:00Z",
  "scope": "read"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `share_id` | string | Opaque share identifier used to revoke |
| `share_url` | string | Publicly accessible URL with token embedded |
| `expires_at` | string | ISO 8601 expiry, or `null` for no expiry |
| `scope` | string | Always `"read"` |

---

## List Shares

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

Returns all active (non-revoked, non-expired) shares for the sandbox.

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "share_id": "shr_01hx9m7n3k...",
      "share_url": "https://sbx-abc123.sandboxes.miosa.ai?ms=ms_eyJ...",
      "expires_at": "2026-05-27T12:00:00Z",
      "scope": "read"
    }
  ]
}
```

---

## Revoke a Share

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

Immediately invalidates the share. Any visitor using the share URL will receive a 403 after revocation.

### Response  -  `204 No Content`

No response body.

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `sandbox_not_found` | Sandbox does not exist or wrong tenant |
| 403 | `forbidden` | Tenant mismatch |
| 404 | `not_found` | Share ID does not exist (on DELETE) |
| 422 | `invalid_scope` | `scope` value is not `"read"` |

---

## Examples

```bash
# Create
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/shares \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 86400}'

# List
curl https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/shares \
  -H "Authorization: Bearer msk_live_..."

# Revoke
curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/shares/shr_01hx9m7n3k \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Create
share = client.sandboxes.shares.create("sbx_abc123", expires_in=86400)
print(share.share_url)

# List
shares = client.sandboxes.shares.list("sbx_abc123")

# Revoke
client.sandboxes.shares.delete("sbx_abc123", share.share_id)
```

```typescript

const client = new Miosa();

// Create
const share = await client.sandboxes.shares.create('sbx_abc123', {
  expiresIn: 86400,
});
console.log(share.shareUrl);

// List
const shares = await client.sandboxes.shares.list('sbx_abc123');

// Revoke
await client.sandboxes.shares.delete('sbx_abc123', share.shareId);
```

---

# Sandbox Templates API

URL: https://miosa.ai/docs/api-reference/sandbox-templates
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/sandbox-templates
Source: src/routes/docs/api-reference/sandbox-templates/+page.md
Description: Browse the template marketplace and launch sandboxes from pre-built images.

Sandbox templates are pre-built images with toolchains, dependencies, and configuration baked in. Launching from a template is faster than installing packages at runtime and ensures reproducible environments.

Templates are read-only marketplace items managed by MIOSA. To build your own custom templates, see the [Templates guide](/docs/develop/templates).

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/sandbox-templates` | List available templates |
| `GET` | `/api/v1/sandbox-templates/{id}` | Get a specific template |
| `POST` | `/api/v1/sandboxes` | Create sandbox from a template (via `template_id`) |

---

## List Templates

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

Returns all templates available to your tenant, including official MIOSA templates and any custom templates you have built.

### Auth

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "id": "tpl_debian12",
      "name": "Debian 12 (Bookworm)",
      "slug": "debian-12-sandbox-v8",
      "description": "Debian Bookworm with Node 20, Python 3.11, Go 1.22, and Rust 1.78 pre-installed.",
      "tags": ["debian", "node", "python", "go", "official"],
      "memory_mb": 4096,
      "vcpus": 2,
      "created_at": "2026-05-11T00:00:00Z",
      "is_official": true
    },
    {
      "id": "tpl_nextjs",
      "name": "Next.js 14",
      "slug": "nextjs-14",
      "description": "Next.js 14 App Router starter with Tailwind CSS.",
      "tags": ["nextjs", "react", "typescript"],
      "memory_mb": 4096,
      "vcpus": 2,
      "created_at": "2026-04-01T00:00:00Z",
      "is_official": true
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Template ID |
| `name` | string | Human-readable template name |
| `slug` | string | Short identifier used in the `image` field |
| `description` | string | What is pre-installed |
| `tags` | string[] | Searchable tags |
| `memory_mb` | integer | Default sandbox memory allocation |
| `vcpus` | integer | Default vCPU count |
| `is_official` | boolean | MIOSA-maintained template |

---

## Get Template

**`GET /api/v1/sandbox-templates/{id}`**

Returns a single template by ID.

### Response  -  `200 OK`

Same shape as a single item from the list response.

---

## Create Sandbox from Template

Use the standard sandbox creation endpoint with the template `slug` as the `image` field:

**`POST /api/v1/sandboxes`**

```json
{
  "image": "debian-12-sandbox-v8",
  "memory_mb": 4096,
  "vcpus": 2
}
```

See the [Sandboxes API](/docs/api-reference/sandboxes) for the full sandbox creation reference.

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `not_found` | Template ID does not exist |

---

## Examples

```bash
# List templates
curl https://api.miosa.ai/api/v1/sandbox-templates \
  -H "Authorization: Bearer msk_live_..."

# Get one template
curl https://api.miosa.ai/api/v1/sandbox-templates/tpl_debian12 \
  -H "Authorization: Bearer msk_live_..."

# Create sandbox from template
curl -X POST https://api.miosa.ai/api/v1/sandboxes \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"image": "debian-12-sandbox-v8"}'
```

```python

client = miosa.Miosa()

# Browse templates
templates = client.sandbox_templates.list()
for t in templates:
    print(t.slug, "-", t.description)

# Launch from template
sandbox = client.sandboxes.create(image="debian-12-sandbox-v8")
```

```typescript

const client = new Miosa();

// Browse
const templates = await client.sandboxTemplates.list();
for (const t of templates) {
  console.log(t.slug, '-', t.description);
}

// Launch
const sandbox = await client.sandboxes.create({
  image: 'debian-12-sandbox-v8',
});
```

---

# 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 isolated microVMs.

Sandboxes are ephemeral isolated 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 root filesystem 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 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`. The latest verified production run measured the standard client-owned lifecycle at **947 ms p50 command-ready TTI** and the production run path at **512 ms p50 command-ready TTI** across 100 sandboxes at concurrency 10. See [Benchmarks](/docs/benchmarks/) for methodology.

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

---

## Create and Run

**`POST /api/v1/sandboxes/run`**

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

This is the production fast path used by MIOSA's current sandbox benchmark: **512 ms p50**, **992 ms p95**, **1.300 s p99** command-ready TTI across 100 sandboxes at concurrency 10.

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

### Request Body

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | First command to execute after the sandbox reaches `running`. |
| `cwd` | string | No | Working directory for the command. Defaults to `/workspace`. |
| `timeout` | integer | No | Command timeout in milliseconds. |
| `wait_timeout_ms` | integer | No | Max time to wait for sandbox readiness before returning `504 SANDBOX_READY_TIMEOUT`. |

### Response  -  `201 Created`

```json
{
  "data": {
    "id": "sbx_01j9xr2t4fk8me3n5q",
    "state": "running",
    "ready": true,
    "template_id": "miosa-sandbox",
    "cpu_count": 1,
    "memory_mb": 1024,
    "boot_path": "warm",
    "boot_ms": 34
  },
  "exec": {
    "stdout": "2\n",
    "stderr": "",
    "exit_code": 0
  },
  "timings": {
    "server_wait_and_exec_ms": 512
  }
}
```

### Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `MISSING_PARAM` | `command` is missing. |
| 400 | `INVALID_TEMPLATE` | `template_id` is not recognized. |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits to provision the VM. |
| 409 | `SANDBOX_LIMIT_EXCEEDED` | Tenant has reached the concurrent sandbox limit. |
| 409 | `SANDBOX_NOT_RUNNING` | The sandbox failed to reach a running state for exec. |
| 502 | `SANDBOX_BOOT_FAILED` | VM boot failed before the command could run. |
| 502 | `AGENT_UNAVAILABLE` | The sandbox agent was not reachable for exec. |
| 504 | `SANDBOX_READY_TIMEOUT` | The sandbox did not become ready before `wait_timeout_ms`. |

---

## 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 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 command 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 computer command service. 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: '/workspace/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": "/workspace/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: `/workspace`) |
| `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": "/workspace/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": "/workspace/app/server",
    "env": {"PORT": "3000", "NODE_ENV": "production"},
    "cwd": "/workspace/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: '/workspace/app/server.js',
  content: serverJsContent,
});

// Register and start
const svc = await client.services.create(computerId, {
  name: 'node-app',
  command: 'node /workspace/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 microVM 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` | VM 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}")
```

---

# Tenant Branding API

URL: https://miosa.ai/docs/api-reference/tenant-branding
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/tenant-branding
Source: src/routes/docs/api-reference/tenant-branding/+page.md
Description: Customize the logo, name, and colors shown on sandbox 404 and 502 error pages.

The branding API controls the appearance of proxy-generated error pages (404, 502, gateway timeout) served within your custom preview domain. Set your logo, product name, support URL, and primary accent color so end-users see your brand  -  not MIOSA's.

Base path: `/api/v1/tenant/branding`

Branding changes are served immediately from cache. There is no propagation delay.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/tenant/branding` | Get current branding |
| `PUT` | `/api/v1/tenant/branding` | Set or replace branding |
| `DELETE` | `/api/v1/tenant/branding` | Reset to MIOSA defaults |

---

## Get Branding

**`GET /api/v1/tenant/branding`**

### Auth

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK`

```json
{
  "branding": {
    "logo_url": "https://cdn.cliniciq.com/logo.png",
    "name": "ClinicIQ",
    "support_url": "https://cliniciq.com/support",
    "primary_color": "#0066FF"
  }
}
```

Returns `{"branding": null}` if no custom branding has been set.

---

## Set Branding

**`PUT /api/v1/tenant/branding`**

Replaces all branding fields. Omitted fields are cleared to their defaults.

### Request Body

Wrap fields under a `"branding"` key.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `logo_url` | string | No | HTTPS URL to your logo image |
| `name` | string | No | Product or company name |
| `support_url` | string | No | Link shown on error pages for user support |
| `primary_color` | string | No | Hex color for CTA buttons (e.g. `"#0066FF"`) |

```json
{
  "branding": {
    "logo_url": "https://cdn.cliniciq.com/logo.png",
    "name": "ClinicIQ",
    "support_url": "https://cliniciq.com/support",
    "primary_color": "#0066FF"
  }
}
```

### Response  -  `200 OK`

```json
{
  "branding": {
    "logo_url": "https://cdn.cliniciq.com/logo.png",
    "name": "ClinicIQ",
    "support_url": "https://cliniciq.com/support",
    "primary_color": "#0066FF"
  }
}
```

---

## Delete Branding

**`DELETE /api/v1/tenant/branding`**

Resets all branding to MIOSA defaults. Error pages will show the MIOSA logo and color scheme.

### Response  -  `200 OK`

```json
{
  "branding": null
}
```

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 404 | `tenant not found` | Tenant does not exist |
| 422 | validation error | A field failed validation (e.g. invalid URL, invalid hex color) |

---

## Examples

```bash
# Set branding
curl -X PUT https://api.miosa.ai/api/v1/tenant/branding \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "branding": {
      "logo_url": "https://cdn.cliniciq.com/logo.png",
      "name": "ClinicIQ",
      "support_url": "https://cliniciq.com/support",
      "primary_color": "#0066FF"
    }
  }'

# Get
curl https://api.miosa.ai/api/v1/tenant/branding \
  -H "Authorization: Bearer msk_live_..."

# Reset
curl -X DELETE https://api.miosa.ai/api/v1/tenant/branding \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

client.tenant.set_branding(
    logo_url="https://cdn.cliniciq.com/logo.png",
    name="ClinicIQ",
    support_url="https://cliniciq.com/support",
    primary_color="#0066FF",
)

branding = client.tenant.get_branding()
print(branding.name)
```

```typescript

const client = new Miosa();

await client.tenant.setBranding({
  logoUrl: 'https://cdn.cliniciq.com/logo.png',
  name: 'ClinicIQ',
  supportUrl: 'https://cliniciq.com/support',
  primaryColor: '#0066FF',
});

const branding = await client.tenant.getBranding();
console.log(branding?.name);
```

---

# Tenant Events (SSE) API

URL: https://miosa.ai/docs/api-reference/tenant-events
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/tenant-events
Source: src/routes/docs/api-reference/tenant-events/+page.md
Description: Subscribe to a real-time server-sent event stream of all tenant-wide platform events.

The tenant events stream delivers real-time Server-Sent Events (SSE) for all activity across your tenant  -  sandbox lifecycle changes, deployments, webhook deliveries, and more. Subscribe once and receive events for all your resources.

Base path: `/api/v1/events/stream`

This endpoint uses `text/event-stream` (SSE). Set `Accept: text/event-stream` on your request, or use a native `EventSource` client.

The `Authorization` header cannot be set by browser `EventSource`. Use a server-side client or pass an SSE ticket obtained from `POST /api/v1/auth/sse-ticket` for browser usage.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/events/stream` | Open tenant-wide SSE event stream |

---

## Open Event Stream

**`GET /api/v1/events/stream`**

Upgrades to an SSE stream. The connection stays open until the client disconnects or the server closes it. A `: heartbeat` comment is sent every 15 seconds to keep the connection alive through proxies.

### Auth

```
Authorization: Bearer msk_...
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `types` | string | No | Comma-separated glob patterns to filter events (e.g. `sandbox.*,webhook.delivered`) |

### Response  -  `200 OK` (`text/event-stream`)

Each event is a standard SSE frame:

```
id: evt_01hwxyz...
event: sandbox.ready
data: {"type":"sandbox.ready","id":"sbx_abc123","status":"running","tenant_id":"...","ts":"2026-05-26T10:14:23Z"}

id: evt_01hwyza...
event: deployment.succeeded
data: {"type":"deployment.succeeded","id":"dep_xyz456","url":"https://my-app.miosa.app","ts":"2026-05-26T10:15:01Z"}

: heartbeat
```

### Event Shape

All events share a common envelope:

```json
{
  "type": "sandbox.ready",
  "id": "sbx_abc123",
  "tenant_id": "ten_...",
  "ts": "2026-05-26T10:14:23Z"
}
```

Additional fields vary by event type (see table below).

---

## Event Types

### Sandbox Events

| Type | Description | Extra Fields |
|------|-------------|-------------|
| `sandbox.created` | Sandbox provisioned | `image`, `workspace_id` |
| `sandbox.ready` | Sandbox reached `running` status | `status` |
| `sandbox.error` | Sandbox failed to start | `error`, `reason` |
| `sandbox.destroyed` | Sandbox deleted |  -  |
| `sandbox.paused` | Sandbox vCPUs suspended |  -  |
| `sandbox.resumed` | Sandbox vCPUs resumed |  -  |

### Computer Events

| Type | Description | Extra Fields |
|------|-------------|-------------|
| `computer.created` | Computer provisioned | `size`, `workspace_id` |
| `computer.running` | Computer reached `running` status |  -  |
| `computer.stopped` | Computer stopped |  -  |
| `computer.deleted` | Computer deleted |  -  |

### Deployment Events

| Type | Description | Extra Fields |
|------|-------------|-------------|
| `deployment.build_started` | Build job enqueued | `version_id` |
| `deployment.succeeded` | Build completed and promoted | `url`, `version_id` |
| `deployment.failed` | Build or promotion failed | `error` |
| `deployment.rollback` | Version rolled back | `from_version`, `to_version` |

### Webhook Events

| Type | Description | Extra Fields |
|------|-------------|-------------|
| `webhook.delivered` | Outgoing webhook POST succeeded | `webhook_id`, `status_code` |
| `webhook.failed` | Outgoing webhook POST failed | `webhook_id`, `attempt`, `error` |

### Filtering with `types`

Pass a comma-separated list of glob patterns. The `*` wildcard matches any suffix segment:

```
?types=sandbox.*           # all sandbox events
?types=sandbox.*,computer.running
?types=deployment.succeeded,deployment.failed
```

An empty `types` parameter (or no parameter) delivers all events.

---

## Reconnection

On disconnect, reconnect using the `Last-Event-ID` header set to the last `id` you received. The server will resume from that cursor, replaying up to 60 seconds of backlogged events.

```
GET /api/v1/events/stream
Authorization: Bearer msk_...
Last-Event-ID: evt_01hwxyz...
```

---

## Examples

```bash
# All events
curl -N -H "Authorization: Bearer msk_live_..." \
  -H "Accept: text/event-stream" \
  "https://api.miosa.ai/api/v1/events/stream"

# Sandbox events only
curl -N -H "Authorization: Bearer msk_live_..." \
  -H "Accept: text/event-stream" \
  "https://api.miosa.ai/api/v1/events/stream?types=sandbox.*"
```

```python

headers = {
    "Authorization": "Bearer msk_live_...",
    "Accept": "text/event-stream",
}

with httpx.stream("GET", "https://api.miosa.ai/api/v1/events/stream",
                  params={"types": "sandbox.*"}, headers=headers) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):

            event = json.loads(line[5:].strip())
            print(event["type"], event["id"])
```

```typescript
// Server-side (Node.js / Deno)  -  EventSource doesn't support custom headers in browsers

const es = new EventSource(
  'https://api.miosa.ai/api/v1/events/stream?types=sandbox.*',
  { headers: { Authorization: 'Bearer msk_live_...' } }
);

es.addEventListener('sandbox.ready', (e) => {
  const data = JSON.parse(e.data);
  console.log('Sandbox ready:', data.id);
});

es.addEventListener('sandbox.error', (e) => {
  const data = JSON.parse(e.data);
  console.error('Sandbox failed:', data.id, data.error);
});

es.onerror = () => es.close();
```

---

# Tenant Preview Domain API

URL: https://miosa.ai/docs/api-reference/tenant-preview-domain
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/tenant-preview-domain
Source: src/routes/docs/api-reference/tenant-preview-domain/+page.md
Description: Configure a custom apex domain for sandbox preview URLs (white-label).

The preview domain API lets you map your own apex domain (e.g. `cliniciq.com`) to sandbox preview URLs. When configured, sandboxes created under your tenant will be accessible at `{sandbox-slug}.{your-domain}` instead of the default `*.sandboxes.miosa.ai`.

**Auth note:** These endpoints accept both `msk_*` API keys and JWT tokens. This matters for white-label integrations where you programmatically manage the domain from a backend service.

Only apex domains are accepted (e.g. `cliniciq.com`, not `app.cliniciq.com` or `https://cliniciq.com`). Wildcard and subdomain inputs are rejected with `422 invalid_domain`.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/tenant/preview-domain` | Get current domain and verification status |
| `PUT` | `/api/v1/tenant/preview-domain` | Set or replace the preview domain |
| `POST` | `/api/v1/tenant/preview-domain/verify` | Recheck DNS verification |
| `DELETE` | `/api/v1/tenant/preview-domain` | Remove the custom domain |

---

## Get Preview Domain

**`GET /api/v1/tenant/preview-domain`**

Returns the configured domain and its DNS verification status.

### Auth

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK` (domain configured)

```json
{
  "preview_domain": "cliniciq.com",
  "status": "configured",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.cliniciq.com",
    "value": "proxy.sandboxes.miosa.ai"
  }
}
```

### Response  -  `200 OK` (not configured)

```json
{
  "preview_domain": null,
  "default_domain": "sandboxes.miosa.ai",
  "status": "not_configured",
  "dns_instructions": null
}
```

| Field | Type | Description |
|-------|------|-------------|
| `preview_domain` | string\|null | Configured apex domain, or `null` |
| `default_domain` | string | Fallback domain used when no custom domain is set |
| `status` | string | `"not_configured"`, `"pending_dns"`, or `"configured"` |
| `dns_instructions` | object\|null | CNAME record to add at your DNS registrar |

---

## Set Preview Domain

**`PUT /api/v1/tenant/preview-domain`**

Sets or replaces the custom preview domain. DNS verification is asynchronous  -  status transitions from `pending_dns` to `configured` once the CNAME resolves correctly.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `preview_domain` | string | Yes | Apex domain (e.g. `"cliniciq.com"`) |

```json
{
  "preview_domain": "cliniciq.com"
}
```

### Response  -  `200 OK`

```json
{
  "preview_domain": "cliniciq.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.cliniciq.com",
    "value": "proxy.sandboxes.miosa.ai"
  }
}
```

### DNS Setup

Add a wildcard CNAME at your registrar:

| Type | Name | Value |
|------|------|-------|
| `CNAME` | `*` (or `*.cliniciq.com`) | `proxy.sandboxes.miosa.ai` |

---

## Verify DNS

**`POST /api/v1/tenant/preview-domain/verify`**

Triggers an immediate DNS re-check. Returns the current verification status without waiting for the background poller.

### Response  -  `200 OK`

```json
{
  "preview_domain": "cliniciq.com",
  "status": "configured",
  "dns_status": "verified"
}
```

---

## Delete Preview Domain

**`DELETE /api/v1/tenant/preview-domain`**

Removes the custom domain. Sandbox preview URLs revert to `*.sandboxes.miosa.ai`.

### Response  -  `200 OK`

```json
{
  "preview_domain": null,
  "status": "removed"
}
```

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `preview_domain is required` | Missing body field |
| 422 | `invalid_domain` | Protocol prefix, wildcard, path, or subdomain detected |
| 404 | `tenant not found` | Tenant does not exist |

---

## Examples

```bash
# Set
curl -X PUT https://api.miosa.ai/api/v1/tenant/preview-domain \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"preview_domain": "cliniciq.com"}'

# Verify
curl -X POST https://api.miosa.ai/api/v1/tenant/preview-domain/verify \
  -H "Authorization: Bearer msk_live_..."

# Get
curl https://api.miosa.ai/api/v1/tenant/preview-domain \
  -H "Authorization: Bearer msk_live_..."

# Delete
curl -X DELETE https://api.miosa.ai/api/v1/tenant/preview-domain \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Set
result = client.tenant.set_preview_domain("cliniciq.com")
print(result.dns_instructions)

# Poll until verified

while True:
    domain = client.tenant.get_preview_domain()
    if domain.status == "configured":
        break
    time.sleep(30)
    client.tenant.verify_preview_domain()
```

```typescript

const client = new Miosa();

// Set
const result = await client.tenant.setPreviewDomain('cliniciq.com');
console.log(result.dnsInstructions);

// Get
const domain = await client.tenant.getPreviewDomain();
console.log(domain.status); // "pending_dns" | "configured"

// Force re-check
await client.tenant.verifyPreviewDomain();

// Remove
await client.tenant.deletePreviewDomain();
```

---

# Usage Rollup API

URL: https://miosa.ai/docs/api-reference/usage-rollup
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/usage-rollup
Source: src/routes/docs/api-reference/usage-rollup/+page.md
Description: Aggregate sandbox compute usage and spend by external user, project, or workspace.

The usage rollup endpoint aggregates metered usage across sandboxes and computers, grouped by an identifier of your choice. Use it to build per-user billing dashboards, enforce spend policies, or attribute costs to projects.

Base path: `/api/v1/usage`

Results are limited to 1000 rows per request. For high-cardinality tenants, narrow the period or use a more specific `group_by`.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/usage` | Aggregate usage for a period |

---

## Get Usage Rollup

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

### Auth

```
Authorization: Bearer msk_...
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `group_by` | string | No | `external_user_id` | Dimension to aggregate by |
| `period` | string | No | `30d` | Predefined period or `custom` |
| `start` | string | No |  -  | ISO 8601 start (required when `period=custom`) |
| `end` | string | No |  -  | ISO 8601 end (required when `period=custom`) |

**`group_by` values:**

| Value | Description |
|-------|-------------|
| `external_user_id` | Group by the `external_user_id` you set on sandboxes |
| `external_project_id` | Group by `external_project_id` |
| `workspace_id` | Group by MIOSA workspace |

**`period` values:**

| Value | Description |
|-------|-------------|
| `7d` | Last 7 days |
| `30d` | Last 30 days |
| `mtd` | Month-to-date (calendar month, resets on the 1st) |
| `custom` | Arbitrary range  -  requires `start` and `end` |

### Response  -  `200 OK`

```json
{
  "period_start": "2026-04-26T00:00:00Z",
  "period_end": "2026-05-26T00:00:00Z",
  "results": [
    {
      "external_user_id": "user_clinic_42",
      "sandbox_seconds": 14400,
      "computer_seconds": 0,
      "storage_gb_hours": 2.5,
      "credit_cents": 312
    },
    {
      "external_user_id": "user_clinic_99",
      "sandbox_seconds": 3600,
      "computer_seconds": 7200,
      "storage_gb_hours": 0.0,
      "credit_cents": 108
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `period_start` | string | ISO 8601 start of aggregation window |
| `period_end` | string | ISO 8601 end of aggregation window |
| `results[].{group_by}` | string | Value of the grouping dimension |
| `results[].sandbox_seconds` | number | vCPU-seconds used by sandboxes |
| `results[].computer_seconds` | number | vCPU-seconds used by computers |
| `results[].storage_gb_hours` | number | GiB-hours of attached storage |
| `results[].credit_cents` | number | Total cost in platform credit cents |

Results are ordered by `credit_cents` descending.

---

## Errors

| Status | Code | Cause |
|--------|------|-------|
| 422 | `invalid group_by` | `group_by` is not one of the accepted values |
| 422 | `invalid period` | `period` is not one of the accepted values |
| 422 | `invalid_custom_range` | `start` or `end` is missing or not valid ISO 8601 when `period=custom` |

---

## Examples

```bash
# 30-day rollup by user
curl "https://api.miosa.ai/api/v1/usage?group_by=external_user_id&period=30d" \
  -H "Authorization: Bearer msk_live_..."

# Custom range
curl "https://api.miosa.ai/api/v1/usage?group_by=external_user_id&period=custom&start=2026-05-01T00:00:00Z&end=2026-05-26T00:00:00Z" \
  -H "Authorization: Bearer msk_live_..."

# Group by project
curl "https://api.miosa.ai/api/v1/usage?group_by=external_project_id&period=mtd" \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

# Monthly rollup per user
results = client.usage.rollup(
    group_by="external_user_id",
    period="30d",
)

for row in results:
    print(f"{row.external_user_id}: {row.credit_cents / 100:.2f} USD")
```

```typescript

const client = new Miosa();

const { results } = await client.usage.rollup({
  groupBy: 'external_user_id',
  period: '30d',
});

for (const row of results) {
  console.log(`${row.externalUserId}: $${(row.creditCents / 100).toFixed(2)}`);
}
```

---

# 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

---

# Webhooks API

URL: https://miosa.ai/docs/api-reference/webhooks
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/api-reference/webhooks
Source: src/routes/docs/api-reference/webhooks/+page.md
Description: Subscribe to platform lifecycle events via outgoing HTTP callbacks with HMAC signature verification.

Webhooks fire outgoing HTTP POST requests to your endpoint when platform events occur  -  sandbox lifecycle changes, deployment completions, billing events, and more. Each delivery is signed with HMAC-SHA256 so you can verify authenticity.

Base path: `/api/v1/webhooks`

The webhook `secret` is returned **only once**  -  in the response to `POST /webhooks`. Store it immediately in a secure location. It cannot be retrieved later (only a masked preview is shown afterward).

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/webhooks` | List all webhooks |
| `POST` | `/api/v1/webhooks` | Create a webhook |
| `GET` | `/api/v1/webhooks/{id}` | Get a webhook |
| `PATCH` | `/api/v1/webhooks/{id}` | Update a webhook |
| `DELETE` | `/api/v1/webhooks/{id}` | Delete a webhook |
| `POST` | `/api/v1/webhooks/{id}/test` | Send a test delivery |
| `GET` | `/api/v1/webhooks/{id}/deliveries` | List delivery attempts |

---

## List Webhooks

**`GET /api/v1/webhooks`**

### Auth

```
Authorization: Bearer msk_...
```

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "id": "wh_01hwxyz...",
      "name": "My Webhook",
      "url": "https://api.myapp.com/hooks/miosa",
      "events": ["sandbox.created", "sandbox.destroyed"],
      "secret_preview": "sk_live_••••••••abcd",
      "retry_count": 3,
      "created_at": "2026-05-01T00:00:00Z",
      "updated_at": "2026-05-01T00:00:00Z"
    }
  ]
}
```

---

## Create a Webhook

**`POST /api/v1/webhooks`**

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | HTTPS endpoint to POST events to |
| `name` | string | No | Human-readable label |
| `events` | string[] | No | Event type filter; empty = all events |
| `headers` | object | No | Extra headers to include in deliveries |
| `retry_count` | integer | No | Number of retries on failure (0-10, default `3`) |
| `metadata` | object | No | Arbitrary key-value metadata |

```json
{
  "url": "https://api.myapp.com/hooks/miosa",
  "name": "Sandbox lifecycle",
  "events": ["sandbox.created", "sandbox.ready", "sandbox.error", "sandbox.destroyed"],
  "retry_count": 3
}
```

### Response  -  `201 Created`

```json
{
  "data": {
    "id": "wh_01hwxyz...",
    "name": "Sandbox lifecycle",
    "url": "https://api.myapp.com/hooks/miosa",
    "events": ["sandbox.created", "sandbox.ready", "sandbox.error", "sandbox.destroyed"],
    "secret": "sk_live_abc123def456...",
    "secret_preview": "sk_live_••••••••3456",
    "retry_count": 3,
    "created_at": "2026-05-26T10:14:23Z",
    "updated_at": "2026-05-26T10:14:23Z"
  }
}
```

The `secret` field appears only in this response. Save it securely.

---

## Update a Webhook

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

Partial update  -  include only fields you want to change.

### Request Body

Same fields as create, all optional.

### Response  -  `200 OK`

Webhook object without the `secret` field.

---

## Delete a Webhook

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

### Response  -  `204 No Content`

---

## Send a Test Delivery

**`POST /api/v1/webhooks/{id}/test`**

Sends a synthetic `webhook.test` event to the configured URL to verify connectivity and signature verification.

### Response  -  `200 OK`

```json
{
  "delivered": true,
  "status_code": 200,
  "duration_ms": 143
}
```

---

## List Deliveries

**`GET /api/v1/webhooks/{id}/deliveries`**

Returns recent delivery attempts with status codes and timing.

### Response  -  `200 OK`

```json
{
  "data": [
    {
      "id": "del_01hwyza...",
      "event_type": "sandbox.ready",
      "status": "delivered",
      "status_code": 200,
      "attempt": 1,
      "duration_ms": 98,
      "delivered_at": "2026-05-26T10:14:24Z"
    },
    {
      "id": "del_01hwyzb...",
      "event_type": "sandbox.created",
      "status": "failed",
      "status_code": 500,
      "attempt": 3,
      "duration_ms": 5012,
      "delivered_at": "2026-05-26T10:14:20Z"
    }
  ]
}
```

---

## Signature Verification

Every delivery includes an `X-Miosa-Signature` header. Verify it on your server before trusting the payload:

```
X-Miosa-Signature: sha256=<hex_digest>
```

Compute the expected signature:

```
hmac = HMAC-SHA256(secret, raw_request_body_bytes)
expected = "sha256=" + hex(hmac)
assert constant_time_equals(expected, request.headers["X-Miosa-Signature"])
```

Always compare signatures using a constant-time function to prevent timing attacks. Never use `==` for string comparison.

### Example verification (Python)

```python

def verify_signature(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)
```

### Example verification (TypeScript)

```typescript

function verifySignature(secret: string, body: Buffer, header: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}
```

---

## Retry Policy

Failed deliveries are retried with exponential backoff:

| Attempt | Delay |
|---------|-------|
| 2 | 30 seconds |
| 3 | 5 minutes |
| 4+ | Up to `retry_count` × 10 minutes (capped at 6 hours) |

A delivery is considered failed if your endpoint returns a non-2xx status code or does not respond within 30 seconds. Set `retry_count: 0` to disable retries.

---

## Subscribed Event Types

| Event | Description |
|-------|-------------|
| `sandbox.created` | Sandbox created |
| `sandbox.ready` | Sandbox reached `running` |
| `sandbox.error` | Sandbox failed to start |
| `sandbox.destroyed` | Sandbox deleted |
| `computer.created` | Computer created |
| `computer.running` | Computer reached `running` |
| `computer.stopped` | Computer stopped |
| `computer.deleted` | Computer deleted |
| `deployment.succeeded` | Build succeeded and promoted |
| `deployment.failed` | Build or promotion failed |
| `deployment.rollback` | Rollback triggered |
| `billing.credit_low` | Credit balance below threshold |
| `billing.credit_exhausted` | Credit balance reached zero |
| `webhook.test` | Synthetic test delivery |

Subscribe to all events by omitting the `events` field. Subscribe to a subset by listing specific event types.

---

## Examples

```bash
# Create
curl -X POST https://api.miosa.ai/api/v1/webhooks \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.myapp.com/hooks/miosa",
    "events": ["sandbox.created", "sandbox.destroyed"]
  }'

# Test
curl -X POST https://api.miosa.ai/api/v1/webhooks/wh_01hwxyz/test \
  -H "Authorization: Bearer msk_live_..."

# Deliveries
curl https://api.miosa.ai/api/v1/webhooks/wh_01hwxyz/deliveries \
  -H "Authorization: Bearer msk_live_..."
```

```python

client = miosa.Miosa()

hook = client.webhooks.create(
    url="https://api.myapp.com/hooks/miosa",
    events=["sandbox.created", "sandbox.destroyed"],
    retry_count=3,
)

# Save hook.secret securely  -  only available now
print(hook.secret)

# Test
result = client.webhooks.test(hook.id)
print(result.delivered, result.status_code)
```

```typescript

const client = new Miosa();

const hook = await client.webhooks.create({
  url: 'https://api.myapp.com/hooks/miosa',
  events: ['sandbox.created', 'sandbox.ready', 'sandbox.destroyed'],
  retryCount: 3,
});

// Store hook.secret in your secrets manager  -  only returned once
console.log(hook.secret);

// Test connectivity
const result = await client.webhooks.test(hook.id);
console.log(result.delivered, result.statusCode);
```

---

# 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_* workspace key] -->|server-side only| API[MIOSA API calls]
    MSK -->|mints via POST /api/v1/browser-tokens| BT[Browser token - scoped + short-lived]
    BT -->|browser only| EP[Specific sandbox endpoint]
    MSK -->|mints via POST /api/v1/auth/sse-ticket| ST[SSE ticket - single use]
    ST -->|EventSource| SS[SSE stream]
    MSK -->|mints via POST /api/v1/sandboxes/:id/preview-token| MP[mp_ Preview token]
    MP -->|iframe embed - no msk_ exposed| Preview[MiosaPreview component]
    MSK -->|mints via POST /api/v1/sandboxes/:id/shares| MS[ms_ Share token]
    MS -->|URL param - public read-only| ShareURL[Public share URL]

## 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, hosted model routing. 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.

## Preview tokens

Preview tokens (`mp_<base64url>`) are short-lived signed tokens for embedding a sandbox preview in an `<iframe>` without exposing an `msk_*` key to the browser.

Your backend mints a preview token server-side and passes it to the `` UI component. The component includes it automatically  -  no `Authorization` header needed in browser code.

### Minting a preview token

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/preview-token \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'
```
```json
{
  "data": {
    "token": "mp_eyJhbGciOiJFZERTQSIs...",
    "expires_at": "2026-05-25T13:00:00Z",
    "sandbox_id": "sbx_abc123"
  }
}
```

```python
from miosa import Miosa

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

preview = client.sandboxes.create_preview_token(
    sandbox_id="sbx_abc123",
    expires_in=3600,
)
# Pass preview.token to the browser  -  never the msk_ key.
```

```typescript

const miosa = new Miosa({ apiKey: 'msk_u_...' });

const preview = await miosa.sandboxes.createPreviewToken('sbx_abc123', {
  expiresIn: 3600,
});
// Pass preview.token to the browser  -  never the msk_ key.
```

In the browser, pass the token to the `` component:
```html

```

See [`` and other UI components](/docs/ui-components) and the [Preview Tokens API reference](/docs/api-reference/preview-tokens) for the full component API and token validation spec.

- **Format:** `mp_<base64url>`  -  signed, not opaque; do not attempt to decode.
- **TTL:** Default 1 hour; configurable via `expires_in` (max 24 hours).
- **Scope:** Read-only access to the specific sandbox's preview port. Cannot create or mutate resources.
- **Revocation:** Preview tokens cannot be individually revoked. Destroying the sandbox invalidates all outstanding tokens for it.

---

## Share tokens

Share tokens (`ms_<base64url>`) turn a sandbox preview into a public read-only URL that anyone with the link can visit  -  no MIOSA account required.

### Minting a share URL

```bash
curl -X POST https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/shares \
  -H "Authorization: Bearer msk_u_..." \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 86400}'
```
```json
{
  "data": {
    "token": "ms_eyJhbGciOiJFZERTQSIs...",
    "url": "https://5173-sbx-abc123.sandbox.miosa.app?token=ms_eyJhbGciOiJFZERTQSIs...",
    "expires_at": "2026-05-26T00:00:00Z",
    "sandbox_id": "sbx_abc123"
  }
}
```

```python
from miosa import Miosa

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

share = client.sandboxes.create_share(
    sandbox_id="sbx_abc123",
    expires_in=86400,
)
print(share.url)  # Hand this URL to the end user.
```

```typescript

const miosa = new Miosa({ apiKey: 'msk_u_...' });

const share = await miosa.sandboxes.createShare('sbx_abc123', {
  expiresIn: 86400,
});
console.log(share.url); // Hand this URL to the end user.
```

- **Format:** `ms_<base64url>`  -  the token IS the URL query parameter (`?ms=ms_...`).
- **Access:** Public, read-only, unauthenticated  -  anyone with the URL can view the preview.
- **TTL:** Set via `expires_in` in seconds. No maximum enforced; omit for a non-expiring share.
- **Revocation:** `DELETE /api/v1/sandboxes/:id/shares/:token` revokes immediately.

See the [Sandbox Shares API reference](/docs/api-reference/sandbox-shares) and [Integrations: Preview Tokens](/docs/integrations/preview-tokens).

---

## Token comparison

| | `msk_*` API key | JWT | Browser token | `mp_` Preview token | `ms_` Share token |
|---|---|---|---|---|---|
| **Scope** | Full workspace | User session | Single sandbox | Single sandbox preview | Single sandbox preview |
| **TTL** | Until revoked | ~1 h (refresh 7 d) | Configurable (default 1 h) | Configurable (default 1 h) | Configurable |
| **How to mint** | Dashboard or `POST /api/v1/api-keys` | `POST /api/v1/auth/login` | `POST /api/v1/browser-tokens` | `POST /api/v1/sandboxes/:id/preview-token` | `POST /api/v1/sandboxes/:id/shares` |
| **Who uses it** | Server | Server / browser (UI) | Browser | Browser / iframe | Anyone (unauthenticated) |
| **Can revoke** | Yes | No (short TTL) | No (short TTL) | No | Yes |
| **Creates resources** | Yes | Yes | No | No | No |

---

## White-label auth note

The `tenant.preview_domain.*` and `tenant.branding.*` configuration endpoints accept **both** `msk_*` API keys and JWTs. These are the only tenant-level config routes accessible with an API key  -  all other tenant administration routes require a JWT from an admin session.

```bash
# Setting a preview domain with an API key (allowed)
curl -X PUT https://api.miosa.ai/api/v1/tenant/preview-domain \
  -H "Authorization: Bearer msk_a_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "preview.yourdomain.com"}'

# Fetching tenant branding with an API key (allowed)
curl https://api.miosa.ai/api/v1/tenant/branding \
  -H "Authorization: Bearer msk_a_..."
```

See the [Tenant Preview Domain](/docs/api-reference/tenant-preview-domain) and [Tenant Branding](/docs/api-reference/tenant-branding) API references for the full configuration spec.

---

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

---

# Benchmarks

URL: https://miosa.ai/docs/benchmarks
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/benchmarks
Source: src/routes/docs/benchmarks/+page.md
Description: MIOSA sandbox benchmark results, competitive provider comparison, and capability matrix.

# Benchmarks

<section class="bench-screen" aria-label="MIOSA benchmark overview">
  <div class="bench-topline">
    <div>
      <p class="bench-kicker">Production sandbox benchmark</p>
      <h2>100 sandbox lifecycles, measured through the production API path.</h2>
      <p>
        These numbers include API authentication, admission checks, scheduling, VM readiness,
        a command probe inside the sandbox, and cleanup. They are not kernel-only boot timings.
        The production lane uses `POST /api/v1/sandboxes/run`, which combines create, server-side
        readiness, and first exec into one durable production request.
      </p>
    </div>
    <div class="bench-proof">
      <span class="proof-status">Verified 2026-06-09 UTC</span>
      <strong>100 / 100</strong>
      <span>successful create -> ready -> exec -> destroy lifecycles</span>
    </div>
  </div>

  <div class="bench-kpis" aria-label="Latest MIOSA result">
    <div><span>Success</span><strong>100%</strong><em>0 failures</em></div>
    <div><span>Command-ready p50</span><strong>512ms</strong><em>production run path</em></div>
    <div><span>Command-ready p95</span><strong>0.992s</strong><em>10-way burst</em></div>
    <div><span>Command-ready p99</span><strong>1.300s</strong><em>all warm path</em></div>
    <div><span>Total run</span><strong>24s</strong><em>100 samples</em></div>
  </div>
</section>

## Latest verified run

| Parameter | Value |
|---|---:|
| Samples | `100` |
| Client concurrency | `10` |
| Batch pace | `0.5s` |
| Template | `miosa-sandbox` |
| Size | `xs` |
| Mode | `run` (`POST /api/v1/sandboxes/run`) |
| Regions requested | `us-mia`, `us-east`, `us-west` |
| Successful lifecycles | `100 / 100` |
| Admission rejections | `0` |
| Total elapsed | `24s` |

### MIOSA latency split

Production run path:

| Phase | p50 | p95 | p99 | Min | Max |
|---|---:|---:|---:|---:|---:|
| Command-ready TTI | `512ms` | `0.992s` | `1.300s` | `295ms` | `1.331s` |
| VM boot slice | `95ms` | `253ms` | `253ms` | `30ms` | `312ms` |

Previous standard public path, kept as a baseline:

| Phase | p50 | p95 | p99 | Min | Max |
|---|---:|---:|---:|---:|---:|
| Create request | `287ms` | `348ms` | `353ms` | `218ms` | `356ms` |
| Ready/running | `589ms` | `1.005s` | `1.246s` | `477ms` | `1.246s` |
| Command-ready TTI | `947ms` | `1.333s` | `1.348s` | `762ms` | `1.610s` |
| VM boot slice | `101ms` | `253ms` | `524ms` | `31ms` | `524ms` |

### What is making the number slower?

The VM path is fast. In the production run, all `100 / 100` samples used the warm
path and the reported boot slice had a `95ms` median. The standard path was slower
because it used three public round trips: create, poll readiness, then exec.

| Component | Median | What it includes |
|---|---:|---|
| Fused command-ready path | `512ms` | Auth, workspace admission, scheduling, server-side wait, first command, response |
| Previous standard path | `947ms` | Create response, external readiness polling, separate exec request |
| Round-trip removed by fusion | `~434ms` | Public polling plus second public exec call |
| Reported warm boot | `95ms` | The actual VM boot slice reported by the fleet |

So the first optimization target was not raw boot. It was create/status/exec round
trips. The `run` endpoint removes that waste while keeping the same durable
sandbox lifecycle underneath.

### Optimization path

The benchmark exposes three separate public lanes. MIOSA should publish all three,
because each answers a different buyer question.

| Lane | Current p50 | What it proves | Immediate target |
|---|---:|---|---:|
| VM-ready | `95ms` | warm sandbox runtime is assigned and ready | `<100ms` sustained |
| Standard API-ready | `589ms` | public API create has produced a running sandbox | `<400ms` |
| Standard command-ready | `947ms` | first command succeeds through the legacy multi-request baseline | `<800ms` |
| Fused command-ready | `512ms` | first command succeeds through one durable request | `<500ms` |

The engineering cuts are concrete:

| Cut | Expected impact | Why it works |
|---|---:|---|
| `create_and_wait` API/SDK path | `50-150ms` | removes external GET polling and returns only when the server has committed running state |
| `create_and_exec` benchmark/API path | `434ms measured` | removes external polling and the separate public exec POST |
| Admission-path caching | `100-180ms` | avoids repeat template, policy, plan, credit-balance, and scheduler reads for hot API keys |
| Region-local control plane / benchmark routing | `200-350ms` in far regions | avoids us-west control-plane round trips when the VM already boots locally |
| Warm-pool guardrails | tail reduction | keeps the `99/100` warm hit rate at `100/100` and removes the cold `5.322s` outlier |

### Fast without fragile

The fastest version of MIOSA should not skip billing, policy, cleanup, or durable
placement. It should move those checks to the right boundary and avoid repeating
them on every hot sandbox.

| Layer | Keep durable | Make faster |
|---|---|---|
| Admission | API key, workspace, plan, policy, credits, idempotency all remain enforced | cache the effective policy/template/credit admission result for short TTLs per API key and workspace |
| Placement | persist sandbox row and `node_id` before exposing a route | allocate from an in-memory reservation ledger first, then write-through to Postgres/outbox |
| Boot | warm-pool claim remains the default, cold boot remains fallback | keep per-region warm pools ready for burst traffic |
| Readiness | only mark running after route registration and command health pass | push readiness over PubSub/SSE instead of external 50ms GET polling |
| First command | command still runs with auth and timeout | fuse `create -> wait -> exec` inside the selected host so the first command is not a second public API round trip |
| Cleanup | destroy, release reservation, stop billing, and revoke routes stay mandatory | make cleanup idempotent and janitor-backed so failed requests do not hold resources |
| Scale | each host keeps local runtime truth; control plane keeps durable truth | route creates to region-local controllers and replicate fleet state asynchronously |

Target shape: the public API has the `run` endpoint today. The SDK wrapper
should expose the same fast lane next:

```ts
await miosa.sandboxes.createAndWait({ template: "miosa-sandbox", region: "auto" })
await miosa.sandboxes.run({ template: "miosa-sandbox", command: "echo ok" })
```

`createAndWait` publishes API-ready latency. `run` publishes command-ready latency.
Both use the same durable sandbox lifecycle underneath; the difference is that the
server owns the wait loop and can execute the first command node-local.

### Region split

| Region | Samples | Success | TTI p50 | TTI p95 | TTI p99 |
|---|---:|---:|---:|---:|---:|
| `us-east` | `33` | `100%` | `328ms` | `644ms` | `684ms` |
| `us-mia` | `34` | `100%` | `506ms` | `815ms` | `859ms` |
| `us-west` | `33` | `100%` | `934ms` | `1.257s` | `1.331s` |

The public number to compare is command-ready TTI. It answers: "when can my
agent run code inside the sandbox?" Boot slice is lower, but boot slice alone
does not include API, auth, scheduling, readiness polling, or the first command.

## Command-ready leaderboard

The external provider values below are from the supplied ComputeSDK-style benchmark
view. MIOSA is inserted by measured p50 command-ready TTI from the production
production `run` path, not isolated as a vanity row. Lower is better.

<section class="provider-board" aria-label="Provider leaderboard">
  <article class="provider-card"><div class="rank">1</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=declaw.ai&amp;sz=64" alt="" /></span><span>Declaw</span></div><div class="provider-score"><strong>0.49s</strong><span>p50 TTI · score 94.9</span></div></article>
  <article class="provider-card miosa"><div class="rank">2</div><div class="provider-name"><span class="logo-well miosa-mark"><img src="/osa-orb-96.png" alt="" /></span><span>MIOSA</span></div><div class="provider-score"><strong>0.512s</strong><span>p50 production run path</span></div></article>
  <article class="provider-card"><div class="rank">3</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=northflank.com&amp;sz=64" alt="" /></span><span>Northflank</span></div><div class="provider-score"><strong>0.54s</strong><span>p50 TTI · score 94.4</span></div></article>
  <article class="provider-card"><div class="rank">4</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=daytona.io&amp;sz=64" alt="" /></span><span>Daytona</span></div><div class="provider-score"><strong>0.58s</strong><span>p50 TTI · score 74.3</span></div></article>
  <article class="provider-card"><div class="rank">5</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=e2b.dev&amp;sz=64" alt="" /></span><span>E2B</span></div><div class="provider-score"><strong>0.64s</strong><span>p50 TTI · score 92.7</span></div></article>
  <article class="provider-card"><div class="rank">6</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=modal.com&amp;sz=64" alt="" /></span><span>Modal</span></div><div class="provider-score"><strong>0.67s</strong><span>p50 TTI · score 92.8</span></div></article>
  <article class="provider-card"><div class="rank">7</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=vercel.com&amp;sz=64" alt="" /></span><span>Vercel</span></div><div class="provider-score"><strong>0.72s</strong><span>p50 TTI · score 90.7</span></div></article>
  <article class="provider-card"><div class="rank">8</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=archil.com&amp;sz=64" alt="" /></span><span>Archil</span></div><div class="provider-score"><strong>0.75s</strong><span>p50 TTI · score 91.8</span></div></article>
  <article class="provider-card"><div class="rank">9</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=runloop.ai&amp;sz=64" alt="" /></span><span>Runloop</span></div><div class="provider-score"><strong>0.81s</strong><span>p50 TTI · score 84.6</span></div></article>
  <article class="provider-card"><div class="rank">10</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=cloudflare.com&amp;sz=64" alt="" /></span><span>Cloudflare</span></div><div class="provider-score"><strong>1.84s</strong><span>p50 TTI · score 78.3</span></div></article>
  <article class="provider-card"><div class="rank">11</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=blaxel.ai&amp;sz=64" alt="" /></span><span>Blaxel</span></div><div class="provider-score"><strong>1.87s</strong><span>p50 TTI · score 80.1</span></div></article>
  <article class="provider-card"><div class="rank">12</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=codesandbox.io&amp;sz=64" alt="" /></span><span>CodeSandbox</span></div><div class="provider-score"><strong>7.32s</strong><span>p50 TTI · score 16.4</span></div></article>
  <article class="provider-card"><div class="rank">13</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=tensorlake.ai&amp;sz=64" alt="" /></span><span>Tensorlake</span></div><div class="provider-score"><strong>15.22s</strong><span>p50 TTI · score 0.0</span></div></article>
  <article class="provider-card"><div class="rank">14</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=upstash.com&amp;sz=64" alt="" /></span><span>Upstash</span></div><div class="provider-score"><strong>17.01s</strong><span>p50 TTI · score 0.0</span></div></article>
</section>

<section class="provider-board" aria-label="GUI-computer providers not yet timed">
  <article class="provider-card"><div class="rank"> - </div><div class="provider-name"><span class="logo-well"><img src="/integrations/orgo.png" alt="" /></span><span>Orgo</span></div><div class="provider-score"><strong>0.27s</strong><span>warm-pool boot · 2.09s desktop-ready (measured)</span></div></article>
  <article class="provider-card"><div class="rank"> - </div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=agentcomputer.ai&amp;sz=64" alt="" /></span><span>AgentComputer</span></div><div class="provider-score"><strong>n/a</strong><span>not yet timed</span></div></article>
  <article class="provider-card"><div class="rank"> - </div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=ascii.dev&amp;sz=64" alt="" /></span><span>ascii Box</span></div><div class="provider-score"><strong>n/a</strong><span>not yet timed</span></div></article>
</section>

The cards above are GUI-computer providers (different category from the sandbox
TTI leaderboard). Orgo's numbers are measured by MIOSA directly; AgentComputer
and ascii Box aren't timed yet. Full pricing + capability breakdown on the
<a href="/docs/integrations/comparison">Provider Comparison</a> page.

## Benchmark placements

The benchmark screenshots expose separate tabs for median, P95, P99, and composite
score. MIOSA's raw latency placement is measured. The composite score below is
labeled as an estimate because the external benchmark app does not publish its
exact scoring formula; the estimate is anchored against the supplied provider
score table and should be treated as directional until MIOSA is added to their
official dataset.

<section class="metric-tabs" aria-label="Benchmark placements by metric">
  <input id="metric-median" name="metric-tab" type="radio" checked />
  <input id="metric-p95" name="metric-tab" type="radio" />
  <input id="metric-p99" name="metric-tab" type="radio" />
  <input id="metric-composite" name="metric-tab" type="radio" />
  <div class="metric-tablist" role="tablist" aria-label="Benchmark metric">
    <label for="metric-median">Median TTI</label>
    <label for="metric-p95">P95 TTI</label>
    <label for="metric-p99">P99 TTI</label>
    <label for="metric-composite">Composite</label>
  </div>

  <div class="metric-panel metric-panel--median" role="tabpanel" aria-label="Median TTI placement">
    <div class="placement-summary"><strong>MIOSA rank: #2</strong><span>0.512s p50 production run path · 100/100 success</span></div>
    <div class="bar-chart" aria-label="Median TTI horizontal bar chart">
      <div class="bar-row"><span>1 Declaw</span><div><i style="width:2.9%"></i><b>0.49s</b></div><em>100/100</em></div>
      <div class="bar-row miosa"><span>2 MIOSA</span><div><i style="width:3.0%"></i><b>0.512s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>3 Northflank</span><div><i style="width:3.2%"></i><b>0.54s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>4 Daytona</span><div><i style="width:3.4%"></i><b>0.58s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>5 E2B</span><div><i style="width:3.8%"></i><b>0.64s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>6 Modal</span><div><i style="width:3.9%"></i><b>0.67s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>7 Vercel</span><div><i style="width:4.2%"></i><b>0.72s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>8 Archil</span><div><i style="width:4.4%"></i><b>0.75s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>9 Runloop</span><div><i style="width:4.8%"></i><b>0.81s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>10 Cloudflare</span><div><i style="width:10.8%"></i><b>1.84s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>11 Blaxel</span><div><i style="width:11.0%"></i><b>1.87s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>12 CodeSandbox</span><div><i style="width:43.0%"></i><b>7.32s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>13 Tensorlake</span><div><i style="width:89.5%"></i><b>15.22s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>14 Upstash</span><div><i style="width:100%"></i><b>17.01s</b></div><em>100/100</em></div>
    </div>
  </div>

  <div class="metric-panel metric-panel--p95" role="tabpanel" aria-label="P95 TTI placement">
    <div class="placement-summary"><strong>MIOSA rank: #6</strong><span>0.992s p95 production run path · tail is the next optimization target</span></div>
    <div class="bar-chart" aria-label="P95 TTI horizontal bar chart">
      <div class="bar-row"><span>1 Declaw</span><div><i style="width:2.3%"></i><b>0.54s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>2 Northflank</span><div><i style="width:2.5%"></i><b>0.59s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>3 Modal</span><div><i style="width:3.3%"></i><b>0.78s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>4 E2B</span><div><i style="width:3.5%"></i><b>0.83s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>5 Archil</span><div><i style="width:3.8%"></i><b>0.90s</b></div><em>100/100</em></div>
      <div class="bar-row miosa"><span>6 MIOSA</span><div><i style="width:4.2%"></i><b>0.992s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>7 Vercel</span><div><i style="width:5.1%"></i><b>1.20s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>8 Blaxel</span><div><i style="width:8.7%"></i><b>2.07s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>9 Cloudflare</span><div><i style="width:11.1%"></i><b>2.62s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>10 Runloop</span><div><i style="width:11.1%"></i><b>2.64s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>11 Daytona</span><div><i style="width:23.3%"></i><b>5.52s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>12 CodeSandbox</span><div><i style="width:41.8%"></i><b>9.90s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>13 Tensorlake</span><div><i style="width:66.5%"></i><b>15.76s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>14 Upstash</span><div><i style="width:100%"></i><b>23.71s</b></div><em>100/100</em></div>
    </div>
  </div>

  <div class="metric-panel metric-panel--p99" role="tabpanel" aria-label="P99 TTI placement">
    <div class="placement-summary"><strong>MIOSA rank: #6</strong><span>1.300s p99 production run path · west-region tail is visible here</span></div>
    <div class="bar-chart" aria-label="P99 TTI horizontal bar chart">
      <div class="bar-row"><span>1 Declaw</span><div><i style="width:2.3%"></i><b>0.54s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>2 Northflank</span><div><i style="width:2.5%"></i><b>0.61s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>3 Modal</span><div><i style="width:3.3%"></i><b>0.79s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>4 Archil</span><div><i style="width:3.9%"></i><b>0.94s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>5 E2B</span><div><i style="width:3.9%"></i><b>0.94s</b></div><em>100/100</em></div>
      <div class="bar-row miosa"><span>6 MIOSA</span><div><i style="width:5.4%"></i><b>1.300s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>7 Vercel</span><div><i style="width:5.6%"></i><b>1.35s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>8 Blaxel</span><div><i style="width:9.8%"></i><b>2.35s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>9 Runloop</span><div><i style="width:11.0%"></i><b>2.64s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>10 Cloudflare</span><div><i style="width:11.3%"></i><b>2.72s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>11 Daytona</span><div><i style="width:23.3%"></i><b>5.58s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>12 CodeSandbox</span><div><i style="width:44.0%"></i><b>10.54s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>13 Tensorlake</span><div><i style="width:65.9%"></i><b>15.81s</b></div><em>100/100</em></div>
      <div class="bar-row"><span>14 Upstash</span><div><i style="width:100%"></i><b>23.98s</b></div><em>100/100</em></div>
    </div>
  </div>

  <div class="metric-panel metric-panel--composite" role="tabpanel" aria-label="Composite score placement">
    <div class="placement-summary"><strong>MIOSA estimated score: 92.4</strong><span>directional rank: #5, between E2B/Modal/Archil and Vercel</span></div>
    <div class="provider-board provider-board--compact" aria-label="Composite score leaderboard">
      <article class="provider-card"><div class="rank">1</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=declaw.ai&amp;sz=64" alt="" /></span><span>Declaw</span></div><div class="provider-score"><strong>94.9</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">2</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=northflank.com&amp;sz=64" alt="" /></span><span>Northflank</span></div><div class="provider-score"><strong>94.4</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">3</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=modal.com&amp;sz=64" alt="" /></span><span>Modal</span></div><div class="provider-score"><strong>92.8</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">4</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=e2b.dev&amp;sz=64" alt="" /></span><span>E2B</span></div><div class="provider-score"><strong>92.7</strong><span>Composite</span></div></article>
      <article class="provider-card miosa"><div class="rank">5</div><div class="provider-name"><span class="logo-well miosa-mark"><img src="/osa-orb-96.png" alt="" /></span><span>MIOSA</span></div><div class="provider-score"><strong>~92.4</strong><span>Estimated</span></div></article>
      <article class="provider-card"><div class="rank">6</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=archil.com&amp;sz=64" alt="" /></span><span>Archil</span></div><div class="provider-score"><strong>91.8</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">7</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=vercel.com&amp;sz=64" alt="" /></span><span>Vercel</span></div><div class="provider-score"><strong>90.7</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">8</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=runloop.ai&amp;sz=64" alt="" /></span><span>Runloop</span></div><div class="provider-score"><strong>84.6</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">9</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=blaxel.ai&amp;sz=64" alt="" /></span><span>Blaxel</span></div><div class="provider-score"><strong>80.1</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">10</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=cloudflare.com&amp;sz=64" alt="" /></span><span>Cloudflare</span></div><div class="provider-score"><strong>78.3</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">11</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=daytona.io&amp;sz=64" alt="" /></span><span>Daytona</span></div><div class="provider-score"><strong>74.3</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">12</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=codesandbox.io&amp;sz=64" alt="" /></span><span>CodeSandbox</span></div><div class="provider-score"><strong>16.4</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">13</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=tensorlake.ai&amp;sz=64" alt="" /></span><span>Tensorlake</span></div><div class="provider-score"><strong>0.0</strong><span>Composite</span></div></article>
      <article class="provider-card"><div class="rank">14</div><div class="provider-name"><span class="logo-well"><img src="https://www.google.com/s2/favicons?domain=upstash.com&amp;sz=64" alt="" /></span><span>Upstash</span></div><div class="provider-score"><strong>0.0</strong><span>Composite</span></div></article>
    </div>
    <p class="score-note">Composite score is estimated because the external benchmark does not publish the exact formula. MIOSA's measured inputs are 0.512s median, 0.992s p95, 1.300s p99, and 100% success.</p>
  </div>
</section>

## Detailed metrics

| Provider | Score | Median TTI | P95 TTI | P99 TTI | Success |
|---|---:|---:|---:|---:|---:|
| Declaw | `94.9` | `0.49s` | `0.54s` | `0.54s` | `100%` |
| MIOSA production path | `~92.4 est.` | `0.512s` | `0.992s` | `1.300s` | `100%` |
| Northflank | `94.4` | `0.54s` | `0.59s` | `0.61s` | `100%` |
| Daytona | `74.3` | `0.58s` | `5.52s` | `5.58s` | `100%` |
| E2B | `92.7` | `0.64s` | `0.83s` | `0.94s` | `100%` |
| Modal | `92.8` | `0.67s` | `0.78s` | `0.79s` | `100%` |
| Vercel | `90.7` | `0.72s` | `1.20s` | `1.35s` | `100%` |
| Archil | `91.8` | `0.75s` | `0.90s` | `0.94s` | `100%` |
| Runloop | `84.6` | `0.81s` | `2.64s` | `2.64s` | `100%` |
| Legacy create / poll / exec baseline | n/a | `0.947s` | `1.333s` | `1.348s` | `100%` |
| Cloudflare | `78.3` | `1.84s` | `2.62s` | `2.72s` | `100%` |
| Blaxel | `80.1` | `1.87s` | `2.07s` | `2.35s` | `100%` |
| CodeSandbox | `16.4` | `7.32s` | `9.90s` | `10.54s` | `100%` |
| Tensorlake | `0.0` | `15.22s` | `15.76s` | `15.81s` | `100%` |
| Upstash | `0.0` | `17.01s` | `23.71s` | `23.98s` | `100%` |

## Capability matrix

Speed is only one axis. MIOSA's product surface is broader than "spawn a headless
sandbox and exec a command."

<section class="capability-views" aria-label="Capability comparison views">
  <div class="capability-summary">
    <article><span>Fast sandbox lane</span><strong>#2</strong><em>median TTI placement</em></article>
    <article><span>Tail latency</span><strong>#6</strong><em>P95/P99 placement</em></article>
    <article><span>Platform breadth</span><strong>11/13</strong><em>capability rows covered</em></article>
    <article><span>GPU options</span><strong>H100</strong><em>available by plan</em></article>
  </div>

  <div class="capability-lanes" aria-label="Capability grouped view">
    <article>
      <h3>Runtime lane</h3>
      <p>Headless sandbox, files, previews, snapshots, and first command execution.</p>
      <div class="lane-meter"><span style="width:92%"></span></div>
      <strong>MIOSA competes directly here.</strong>
    </article>
    <article>
      <h3>Platform lane</h3>
      <p>Desktop VM, deploy/release plane, managed data, white-label embedding, BYOC.</p>
      <div class="lane-meter lane-meter--lead"><span style="width:95%"></span></div>
      <strong>This is the differentiation layer.</strong>
    </article>
    <article>
      <h3>Enterprise lane</h3>
      <p>Compliance posture, GPU/H100 options, and mature enterprise procurement story.</p>
      <div class="lane-meter lane-meter--gap"><span style="width:58%"></span></div>
      <strong>This is where incumbents still have air.</strong>
    </article>
  </div>

  <div class="matrix-hint">
    <span>Full provider matrix</span>
    <em>Scroll horizontally for Daytona, CodeSandbox, and Upstash. Teal = yes, amber = partial, gray = no.</em>
  </div>
  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
  <div class="capability-scroll" role="region" aria-label="Capability matrix" tabindex="0">
    <table>
      <thead>
        <tr>
          <th>Capability</th>
          <th>MIOSA</th>
          <th>Declaw</th>
          <th>Northflank</th>
          <th>Modal</th>
          <th>E2B</th>
          <th>Vercel</th>
          <th>Daytona</th>
          <th>CodeSandbox</th>
          <th>Upstash</th>
        </tr>
      </thead>
      <tbody>
        <tr><th>Headless sandbox create/exec</th><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td></tr>
        <tr><th>Filesystem API</th><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="partial">PARTIAL</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td></tr>
        <tr><th>Port preview URLs</th><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="partial">PARTIAL</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="partial">PARTIAL</td></tr>
        <tr><th>Snapshot/fork/resume</th><td class="yes">YES</td><td class="yes">YES</td><td class="partial">PARTIAL</td><td class="partial">PARTIAL</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="yes">YES</td><td class="partial">PARTIAL</td></tr>
        <tr><th>Full desktop/browser VM</th><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="partial">PARTIAL</td><td class="no">NO</td></tr>
        <tr><th>Managed deploy/release plane</th><td class="yes">YES</td><td class="no">NO</td><td class="yes">YES</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td></tr>
        <tr><th>Managed Postgres/Redis/storage</th><td class="yes">YES</td><td class="no">NO</td><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="no">NO</td><td class="partial">Redis/Vector</td></tr>
        <tr><th>White-label tenant embedding</th><td class="yes">YES</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td></tr>
        <tr><th>BYOC / customer-owned fleet</th><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="no">NO</td></tr>
        <tr><th>MCP/agent tool surface</th><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="partial">PARTIAL</td><td class="no">NO</td><td class="partial">PARTIAL</td></tr>
        <tr><th>Multi-language SDKs</th><td>5</td><td>TS/Py</td><td>TS</td><td>Py</td><td>TS/Py</td><td>TS/Py</td><td>TS/Py/Go/Java/Ruby</td><td>TS</td><td>TS</td></tr>
        <tr><th>GPU story</th><td class="yes">H100</td><td class="no">NO</td><td class="no">NO</td><td class="yes">YES</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td><td class="no">NO</td></tr>
        <tr><th>Compliance public posture</th><td class="yes">Compliant</td><td class="partial">Limited</td><td>Enterprise</td><td>Enterprise</td><td>SOC2</td><td>SOC2</td><td>Enterprise</td><td>Enterprise</td><td>Enterprise</td></tr>
      </tbody>
    </table>
  </div>

</section>

### What this means

- If a buyer only cares about raw median headless sandbox TTI, the category is tight.
- If a buyer needs desktops, browser automation, white-label embedding, deploys, data, and BYOC in the same platform, MIOSA is no longer competing on a one-column sandbox table.
- If a buyer needs GPU today, MIOSA can support GPU/H100 options while keeping the same platform surface.

## Provider coverage

This page tracks the providers shown in the benchmark screenshots plus the providers
exposed by ComputeSDK's current provider list. Some vendors are broader platforms,
some are narrow sandbox APIs, and some expose sandboxes as one feature in a larger
developer-cloud product.

| Provider | Category | Strongest public angle | MIOSA comparison note |
|---|---|---|---|
| MIOSA | Sandbox + desktop + deploy + data platform | Full lifecycle platform for agents and white-label SaaS | Broader platform surface than a headless sandbox-only provider |
| Declaw | Security-oriented sandbox | Fast TTI plus policy/security positioning | Strong security story; no public desktop/deploy/data plane equivalent |
| Northflank | Developer cloud with sandboxes | Persistent app/runtime platform plus sandbox execution | Strong deploy platform; less agent/desktop-specific |
| Modal | Serverless compute/GPU | GPU and Python-function workflow | Strong GPU story; sandbox is not a white-label desktop platform |
| E2B | AI code execution sandbox | Mature AI-agent sandbox API | Strong headless agent sandbox; limited platform breadth |
| Archil | Sandbox/storage-oriented provider | Fast benchmark row and storage-first positioning | Less public breadth than MIOSA's computers/deploy/data surface |
| Vercel | Frontend platform plus sandbox | Distribution, OIDC, polished DX | Strong existing-account funnel; sandbox is headless and region-limited in public docs |
| Runloop | Devbox/sandbox provider | Long-lived devboxes and snapshots | Strong devbox framing; no comparable white-label/data plane |
| Blaxel | Agent platform and sandbox | Agent hosting, batch jobs, sandbox console | Strong agent platform/compliance posture; narrower managed data/deploy surface |
| Cloudflare | Edge platform sandbox | Edge distribution and developer ecosystem | Strong edge ecosystem; sandbox is one product within Cloudflare |
| Daytona | OSS/open sandbox platform | Open-source breadth and fast code-to-exec positioning | Strong OSS story; MIOSA adds managed data, deploys, desktops, white-label |
| CodeSandbox | Cloud dev environment | Browser IDE, previews, devbox UX | Strong interactive IDE; weaker benchmark row in supplied data |
| Tensorlake | AI-native sandbox | AI/RL tooling and sandbox filesystem benchmarks | Strong AI-lab framing; no public desktop/deploy/data platform equivalent |
| Upstash | Serverless data plus Box | Redis/Vector/QStash adjacency and built-in agent tooling | Strong data brand; Box is newer and JS/TS-centered |
| HopX | Cloud sandbox API | Multi-language code execution and desktop automation docs | Lower benchmark visibility; overlaps sandbox APIs more than platform plane |
| Namespace | Build/devbox platform | Builders, devboxes, macOS/CI style workloads | Strong CI/build niche; different buyer motion from MIOSA agent platform |

## Benchmark notes

The published MIOSA result is the clean 100/100 production lifecycle run after
deploying `POST /api/v1/sandboxes/run` on 2026-06-09 UTC. The older standard
path is also shown so the optimization is auditable instead of hidden. Setup
failures from under-scoped keys or insufficient plan concurrency are not counted
as fleet performance.

## How to reproduce

Use a workspace and API key with enough sandbox concurrency for the test shape:

```bash
export MIOSA_API_KEY="msk_..."
export API_URL="https://api.miosa.ai"
export BENCH_WORKSPACE_ID="your-workspace-uuid"

./scripts/bench-continuous.sh \
  --samples 100 \
  --concurrent 10 \
  --pace 0.5 \
  --template miosa-sandbox \
  --size xs \
  --mode run \
  --output bench-results/MIOSA-100-sandbox.tsv \
  --html bench-results/MIOSA-100-sandbox.html
```

Use `--mode standard` to reproduce the legacy create / poll / exec baseline.
Use `--mode run` to reproduce the production command-ready lane. The
benchmark deletes successful samples unless `--keep` is passed.

## Sources and current research

- [ComputeSDK introduction](https://docs.computesdk.com/) for the provider set and abstraction shape.
- [Daytona docs](https://www.daytona.io/docs/) for Daytona's current sandbox positioning and SDK breadth.
- [Tensorlake homepage](https://www.tensorlake.ai/) for Tensorlake's published sandbox/filesystem benchmark positioning.
- [HopX docs](https://docs.hopx.ai/) for HopX sandbox/code-execution capabilities.
- [Blaxel docs](https://docs.blaxel.ai/) for Blaxel sandbox/agent platform positioning.
- [Northflank sandboxes docs](https://northflank.com/docs/v1/application/sandboxes/sandboxes-on-northflank) for Northflank sandbox behavior.
- Internal competitive notes under `docs/audits/providers/` for the first-pass capability matrix.

<style>
  :global(.doc-article .bench-screen) {
    border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
    border-radius: 12px;
    padding: 1.35rem;
    background:
      radial-gradient(circle at 88% 12%, color-mix(in srgb, #16c79a 12%, transparent), transparent 32%),
      linear-gradient(180deg, color-mix(in srgb, currentColor 6%, transparent), transparent),
      color-mix(in srgb, currentColor 3%, transparent);
    margin: 1.5rem 0 2rem;
  }

  :global(.doc-article .bench-topline) {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 250px;
    gap: 1.15rem;
    align-items: stretch;
  }

  :global(.doc-article .bench-kicker) {
    margin: 0 0 0.5rem;
    font-size: 0.75rem;
    font-weight: 700;
    letter-spacing: 0.08em;
    text-transform: uppercase;
    color: color-mix(in srgb, currentColor 62%, transparent);
  }

  :global(.doc-article .bench-topline h2) {
    margin: 0 0 0.6rem;
    max-width: 720px;
    font-size: clamp(2rem, 4vw, 2.9rem);
    line-height: 1.02;
    letter-spacing: 0;
  }

  :global(.doc-article .bench-topline p) {
    max-width: 780px;
  }

  :global(.doc-article .bench-proof) {
    border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
    border-radius: 12px;
    padding: 1.1rem;
    display: flex;
    flex-direction: column;
    justify-content: center;
    gap: 0.35rem;
    background:
      linear-gradient(180deg, color-mix(in srgb, #16c79a 8%, transparent), transparent),
      color-mix(in srgb, currentColor 4%, transparent);
  }

  :global(.doc-article .proof-status) {
    font-size: 0.75rem;
    color: color-mix(in srgb, currentColor 62%, transparent);
  }

  :global(.doc-article .bench-proof strong) {
    font-size: 2.15rem;
    line-height: 1;
  }

  :global(.doc-article .bench-proof span:last-child) {
    font-size: 0.85rem;
    color: color-mix(in srgb, currentColor 70%, transparent);
  }

  :global(.doc-article .bench-kpis) {
    display: grid;
    grid-template-columns: 1.05fr repeat(3, 1.15fr) 0.95fr;
    gap: 0.7rem;
    margin-top: 1.05rem;
  }

  :global(.doc-article .bench-kpis div) {
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 10px;
    padding: 0.85rem;
    background: color-mix(in srgb, currentColor 4%, transparent);
    min-width: 0;
  }

  :global(.doc-article .bench-kpis div:nth-child(2)) {
    border-color: color-mix(in srgb, #16c79a 40%, currentColor 10%);
    background:
      linear-gradient(180deg, color-mix(in srgb, #16c79a 9%, transparent), transparent),
      color-mix(in srgb, currentColor 4%, transparent);
  }

  :global(.doc-article .bench-kpis span),
  :global(.doc-article .bench-kpis em) {
    display: block;
    font-size: 0.72rem;
    color: color-mix(in srgb, currentColor 60%, transparent);
    font-style: normal;
  }

  :global(.doc-article .bench-kpis strong) {
    display: block;
    margin: 0.15rem 0;
    font-size: 1.55rem;
    letter-spacing: 0;
  }

  :global(.doc-article table) {
    display: table !important;
    width: 100%;
    max-width: 100%;
    table-layout: auto;
    white-space: normal;
    box-sizing: border-box;
    font-size: 0.86rem;
  }

  :global(.doc-article table th),
  :global(.doc-article table td) {
    white-space: normal;
    vertical-align: top;
  }

  :global(.doc-article table td:first-child) {
    white-space: normal;
    width: 28%;
  }

  :global(.doc-article .provider-board) {
    display: grid;
    grid-template-columns: repeat(2, minmax(0, 1fr));
    gap: 0.6rem;
    margin: 1rem 0 2.25rem;
  }

  :global(.doc-article .provider-board--compact) {
    margin-bottom: 0.75rem;
  }

  :global(.doc-article .provider-board--compact .provider-card) {
    min-height: 52px;
    grid-template-columns: 30px minmax(0, 1fr) 110px;
  }

  :global(.doc-article .provider-card) {
    display: grid;
    grid-template-columns: 34px minmax(0, 1fr) 128px;
    align-items: center;
    gap: 0.75rem;
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 8px;
    padding: 0.72rem 0.8rem;
    background: color-mix(in srgb, currentColor 4%, transparent);
    min-height: 64px;
  }

  :global(.doc-article .provider-card.miosa) {
    background: color-mix(in srgb, currentColor 6%, transparent);
    border-color: color-mix(in srgb, currentColor 18%, transparent);
  }

  :global(.doc-article .rank) {
    color: color-mix(in srgb, currentColor 58%, transparent);
    font-variant-numeric: tabular-nums;
  }

  :global(.doc-article .provider-name) {
    display: flex;
    align-items: center;
    gap: 0.55rem;
    min-width: 0;
    font-weight: 700;
  }

  :global(.doc-article .logo-well) {
    width: 38px;
    height: 38px;
    border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
    border-radius: 8px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
    flex: 0 0 auto;
    background: color-mix(in srgb, currentColor 7%, transparent);
  }

  :global(.doc-article .logo-well img) {
    width: 24px;
    height: 24px;
    object-fit: contain;
    display: block;
  }

  :global(.doc-article .miosa-mark img) {
    width: 31px;
    height: 31px;
  }

  :global(.doc-article .score-note) {
    margin: 0.7rem 0 0;
    font-size: 0.82rem;
    color: color-mix(in srgb, currentColor 68%, transparent);
  }

  :global(.doc-article .provider-score) {
    text-align: right;
    font-variant-numeric: tabular-nums;
  }

  :global(.doc-article .provider-score strong),
  :global(.doc-article .provider-score span) {
    display: block;
  }

  :global(.doc-article .provider-score strong) {
    line-height: 1.1;
  }

  :global(.doc-article .provider-score span) {
    font-size: 0.68rem;
    color: color-mix(in srgb, currentColor 58%, transparent);
  }

  :global(.doc-article .metric-tabs) {
    margin: 1rem 0 2.25rem;
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 12px;
    background: color-mix(in srgb, currentColor 3%, transparent);
    overflow: hidden;
  }

  :global(.doc-article .metric-tabs > input) {
    position: absolute;
    opacity: 0;
    pointer-events: none;
  }

  :global(.doc-article .metric-tablist) {
    display: flex;
    gap: 0.35rem;
    padding: 0.55rem;
    border-bottom: 1px solid color-mix(in srgb, currentColor 9%, transparent);
    background: color-mix(in srgb, currentColor 5%, transparent);
    overflow-x: auto;
  }

  :global(.doc-article .metric-tablist label) {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-height: 34px;
    padding: 0 0.85rem;
    border-radius: 999px;
    font-size: 0.86rem;
    font-weight: 650;
    color: color-mix(in srgb, currentColor 72%, transparent);
    cursor: pointer;
    white-space: nowrap;
  }

  :global(.doc-article #metric-median:checked ~ .metric-tablist label[for='metric-median']),
  :global(.doc-article #metric-p95:checked ~ .metric-tablist label[for='metric-p95']),
  :global(.doc-article #metric-p99:checked ~ .metric-tablist label[for='metric-p99']),
  :global(.doc-article #metric-composite:checked ~ .metric-tablist label[for='metric-composite']) {
    background: color-mix(in srgb, currentColor 16%, transparent);
    color: currentColor;
  }

  :global(.doc-article .metric-panel) {
    display: none;
    padding: 1rem 1.15rem 1.2rem;
  }

  :global(.doc-article #metric-median:checked ~ .metric-panel--median),
  :global(.doc-article #metric-p95:checked ~ .metric-panel--p95),
  :global(.doc-article #metric-p99:checked ~ .metric-panel--p99),
  :global(.doc-article #metric-composite:checked ~ .metric-panel--composite) {
    display: block;
  }

  :global(.doc-article .placement-summary) {
    display: flex;
    justify-content: space-between;
    gap: 1rem;
    align-items: baseline;
    margin-bottom: 0.8rem;
    padding-bottom: 0.75rem;
    border-bottom: 1px solid color-mix(in srgb, currentColor 8%, transparent);
  }

  :global(.doc-article .placement-summary strong) {
    font-size: 1rem;
  }

  :global(.doc-article .placement-summary span) {
    color: color-mix(in srgb, currentColor 65%, transparent);
    font-size: 0.84rem;
    text-align: right;
  }

  :global(.doc-article .bar-chart) {
    display: grid;
    gap: 0.28rem;
  }

  :global(.doc-article .bar-row) {
    display: grid;
    grid-template-columns: 124px minmax(0, 1fr) 74px;
    align-items: center;
    gap: 0.6rem;
    font-size: 0.82rem;
    min-height: 31px;
  }

  :global(.doc-article .bar-row > span) {
    color: color-mix(in srgb, currentColor 72%, transparent);
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
  }

  :global(.doc-article .bar-row > div) {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 64px;
    align-items: center;
    gap: 0.5rem;
    position: relative;
    min-height: 28px;
    border-top: 1px dashed color-mix(in srgb, currentColor 10%, transparent);
    min-width: 0;
  }

  :global(.doc-article .bar-row i) {
    display: block;
    height: 16px;
    min-width: 14px;
    border-radius: 4px;
    background: color-mix(in srgb, currentColor 38%, transparent);
    max-width: 100%;
  }

  :global(.doc-article .bar-row.miosa i) {
    background: #16c79a;
    box-shadow: 0 0 0 1px color-mix(in srgb, #16c79a 45%, transparent);
  }

  :global(.doc-article .bar-row b) {
    justify-self: end;
    font-size: 0.79rem;
    font-variant-numeric: tabular-nums;
    white-space: nowrap;
    text-align: right;
  }

  :global(.doc-article .bar-row em) {
    color: color-mix(in srgb, currentColor 60%, transparent);
    font-style: normal;
    font-variant-numeric: tabular-nums;
    text-align: right;
    white-space: nowrap;
  }

  :global(.doc-article .bar-row.miosa) {
    margin: 0.06rem -0.35rem;
    padding: 0 0.35rem;
    border-radius: 8px;
    background: color-mix(in srgb, #16c79a 8%, transparent);
  }

  :global(.doc-article .bar-row.miosa > span),
  :global(.doc-article .bar-row.miosa b),
  :global(.doc-article .miosa-row td) {
    color: #16c79a;
  }

  :global(.doc-article .capability-views) {
    margin: 1rem 0 2.25rem;
  }

  :global(.doc-article .capability-summary) {
    display: grid;
    grid-template-columns: repeat(4, minmax(0, 1fr));
    gap: 0.65rem;
    margin-bottom: 0.8rem;
  }

  :global(.doc-article .capability-summary article) {
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 10px;
    padding: 0.8rem;
    background: color-mix(in srgb, currentColor 4%, transparent);
    min-width: 0;
  }

  :global(.doc-article .capability-summary span),
  :global(.doc-article .capability-summary em) {
    display: block;
    font-size: 0.72rem;
    color: color-mix(in srgb, currentColor 62%, transparent);
    font-style: normal;
  }

  :global(.doc-article .capability-summary strong) {
    display: block;
    margin: 0.15rem 0;
    font-size: 1.45rem;
    line-height: 1.1;
  }

  :global(.doc-article .capability-scroll) {
    max-width: 100%;
    overflow-x: auto;
    overscroll-behavior-x: contain;
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 10px;
    background: color-mix(in srgb, currentColor 3%, transparent);
    scrollbar-width: thin;
    scrollbar-color: color-mix(in srgb, currentColor 28%, transparent) transparent;
  }

  :global(.doc-article .matrix-hint) {
    display: flex;
    justify-content: space-between;
    gap: 0.8rem;
    align-items: center;
    margin: 0.9rem 0 0.45rem;
    color: color-mix(in srgb, currentColor 68%, transparent);
    font-size: 0.8rem;
  }

  :global(.doc-article .matrix-hint span) {
    color: currentColor;
    font-weight: 750;
  }

  :global(.doc-article .matrix-hint em) {
    font-style: normal;
    text-align: right;
  }

  :global(.doc-article .capability-scroll table) {
    min-width: 980px;
    border: 0;
    margin: 0;
    table-layout: fixed;
  }

  :global(.doc-article .capability-scroll th),
  :global(.doc-article .capability-scroll td) {
    text-align: center;
    vertical-align: middle;
    padding: 0.72rem 0.65rem;
  }

  :global(.doc-article .capability-scroll th:first-child) {
    position: sticky;
    left: 0;
    z-index: 2;
    width: 190px;
    text-align: left;
    background: color-mix(in srgb, currentColor 7%, transparent);
  }

  :global(.doc-article .capability-scroll tbody th:first-child) {
    font-weight: 600;
    color: color-mix(in srgb, currentColor 82%, transparent);
    background: color-mix(in srgb, currentColor 4%, transparent);
  }

  :global(.doc-article .capability-scroll .yes),
  :global(.doc-article .capability-scroll .partial),
  :global(.doc-article .capability-scroll .no) {
    font-weight: 750;
    font-size: 0.76rem;
  }

  :global(.doc-article .capability-scroll .yes) {
    color: #16c79a;
  }

  :global(.doc-article .capability-scroll .partial) {
    color: #d6a94f;
  }

  :global(.doc-article .capability-scroll .no) {
    color: color-mix(in srgb, currentColor 48%, transparent);
  }

  :global(.doc-article .capability-lanes) {
    display: grid;
    grid-template-columns: repeat(3, minmax(0, 1fr));
    gap: 0.75rem;
    margin-top: 0.8rem;
  }

  :global(.doc-article .capability-lanes article) {
    border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
    border-radius: 10px;
    padding: 0.9rem;
    background: color-mix(in srgb, currentColor 4%, transparent);
  }

  :global(.doc-article .capability-lanes h3) {
    margin: 0 0 0.35rem;
    font-size: 0.98rem;
  }

  :global(.doc-article .capability-lanes p) {
    margin: 0 0 0.75rem;
    font-size: 0.82rem;
    color: color-mix(in srgb, currentColor 68%, transparent);
  }

  :global(.doc-article .capability-lanes strong) {
    display: block;
    margin-top: 0.65rem;
    font-size: 0.8rem;
  }

  :global(.doc-article .lane-meter) {
    height: 8px;
    overflow: hidden;
    border-radius: 999px;
    background: color-mix(in srgb, currentColor 12%, transparent);
  }

  :global(.doc-article .lane-meter span) {
    display: block;
    height: 100%;
    border-radius: inherit;
    background: color-mix(in srgb, currentColor 48%, transparent);
  }

  :global(.doc-article .lane-meter--lead span) {
    background: #16c79a;
  }

  :global(.doc-article .lane-meter--gap span) {
    background: #d6a94f;
  }

  @media (max-width: 860px) {
    :global(.doc-article .bench-topline),
    :global(.doc-article .provider-board) {
      grid-template-columns: 1fr;
    }

    :global(.doc-article .bench-kpis) {
      grid-template-columns: repeat(2, minmax(0, 1fr));
    }

    :global(.doc-article .capability-summary),
    :global(.doc-article .capability-lanes) {
      grid-template-columns: repeat(2, minmax(0, 1fr));
    }

    :global(.doc-article .placement-summary) {
      display: block;
    }

    :global(.doc-article .placement-summary span) {
      display: block;
      margin-top: 0.3rem;
      text-align: left;
    }

    :global(.doc-article .matrix-hint) {
      display: block;
    }

    :global(.doc-article .matrix-hint em) {
      display: block;
      margin-top: 0.25rem;
      text-align: left;
    }

  }

  @media (max-width: 560px) {
    :global(.doc-article .bench-topline h2) {
      font-size: 1.9rem;
    }

    :global(.doc-article .bench-kpis) {
      grid-template-columns: 1fr;
    }

    :global(.doc-article .capability-summary),
    :global(.doc-article .capability-lanes) {
      grid-template-columns: 1fr;
    }

    :global(.doc-article .provider-card) {
      grid-template-columns: 24px minmax(0, 1fr);
    }

    :global(.doc-article .provider-score) {
      grid-column: 2;
      text-align: left;
    }

    :global(.doc-article .bar-row) {
      grid-template-columns: 96px minmax(0, 1fr);
    }

    :global(.doc-article .bar-row em) {
      display: none;
    }
  }
</style>

---

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

---

## June 9, 2026

### Production V1 backend and verified sandbox benchmark

The unified V1 backend is live in production on `release/v1`. Production health checks passed after deployment.

MIOSA also ran verified production sandbox benchmarks through the real HTTP API: `100` sandboxes, concurrency `10`, `xs` `miosa-sandbox` instances, create -> ready -> exec -> destroy. Result: `100 / 100` completed successfully, `0` capacity rejections. The production run path (`POST /api/v1/sandboxes/run`) measured `512ms` p50, `992ms` p95, and `1.300s` p99 command-ready TTI. The standard client-owned lifecycle measured `947ms` p50, `1.333s` p95, and `1.348s` p99. See [Benchmarks →](/docs/benchmarks/)

## 1.1.0  -  White-label integration release (2026-05-26)

This release completes the five-phase white-label integration track. Every feature below is additive  -  no breaking changes, no migration steps required.

### Phase 1  -  Foundation

- **Sandbox slug + external attribution at create.** `POST /v1/sandboxes` accepts `slug`, `external_user_id`, `external_project_id`, and an arbitrary `metadata` map. Attribution fields are stored as opaque strings and appear on all list/read responses.
- **`sandbox.update` PATCH.** Slug, metadata, and attribution can be updated after create without a restart.
- **Preview tokens (`mp_*`).** Short-lived signed tokens for embedding a sandbox preview inside your own product's iframe. Your `msk_*` key never leaves the server. See [Browser Tokens →](/docs/platform/browser-tokens/)
- **Webhook subscriptions for sandbox lifecycle.** Subscribe to `sandbox.created`, `sandbox.started`, `sandbox.suspended`, `sandbox.resumed`, `sandbox.destroyed`, and `sandbox.error` over HTTPS webhook delivery. See [Events →](/docs/api-reference/events/)
- **Branded 404/502 pages.** The platform renders your tenant logo and color on error pages shown to end users.
- **Tenant preview-domain CRUD.** Register and verify a custom domain that your end users see in the browser address bar instead of MIOSA fallback preview domains. See [Custom Domains →](/docs/deploy/domains/)
- **Tenant branding CRUD.** Upload a logo and accent color. Applied to 4xx/5xx pages and preview chrome.

### Phase 2  -  Editor primitives

- **File tree.** `GET /v1/sandboxes/:id/files` returns a recursive directory listing with size, mtime, and type.
- **`write_many`.** Write multiple files in a single API call  -  useful for agent code-gen that produces many files at once.
- **File-change SSE.** Subscribe to `file.changed` events on a sandbox to stream editor state to a browser in real time.
- **Sandbox env vars CRUD.** Set, list, and delete environment variables on a running sandbox without reboot. Variables are available to new exec calls immediately.
- **Long-running processes.** Start a named process, list running processes, stream logs, and stop by name  -  without managing a detached exec manually.
- **Sandbox templates.** Author reusable sandbox starting images with a BuildSpec file. Publish to your organization's private catalog or the public catalog.
- **Snapshot fork.** Fork a sandbox from a named snapshot  -  creates a new running sandbox pre-seeded with a checkpoint of another sandbox's state.

### Phase 3  -  Multi-tenant

- **Usage rollup by `external_user_id`.** `GET /v1/usage` accepts `group_by=external_user_id`  -  returns compute-seconds and storage-bytes per attributed user. Useful for per-customer cost chargeback.
- **Audit log.** Every mutation in your workspace is recorded: who called what, when, from which IP, with which resource IDs. `GET /v1/audit-log` with date range and resource filters.
- **Per-user quotas.** Set sandbox concurrency and compute-minute caps per `external_user_id` through the tenant quota API.
- **Tenant-wide events SSE.** A single SSE stream (`GET /v1/events`) that carries lifecycle events across all sandboxes in your workspace  -  for dashboards that need to reflect fleet state without polling.

### Phase 4  -  Sharing

- **Share URLs (`ms_*`).** Mint a public read-only share URL for a sandbox preview. Share tokens are revocable, expiring, and optionally password-protected.
- **Per-end-user custom domains.** Attach a custom domain to an individual sandbox preview scoped to one `external_user_id`  -  so each customer can have `app.theirdomain.com` pointing at their sandbox.

### Phase 5  -  UI component packages

Drop-in React, Vue, and Svelte components that embed a MIOSA sandbox preview, terminal, file tree, or usage chart inside your own product UI. Components handle token minting, SSE reconnect, and error states.

| Package | npm |
|---------|-----|
| `@miosa/react` | [npmjs.com/package/@miosa/react](https://www.npmjs.com/package/@miosa/react) |
| `@miosa/vue` | [npmjs.com/package/@miosa/vue](https://www.npmjs.com/package/@miosa/vue) |
| `@miosa/svelte` | [npmjs.com/package/@miosa/svelte](https://www.npmjs.com/package/@miosa/svelte) |

Available components: `MiosaPreview`, `MiosaTerminal`, `MiosaFileTree`, `MiosaUsage`.

See [UI Components →](/docs/ui-components/)

### Package versions

| Package | Registry | Version |
|---------|----------|---------|
| `miosa` (Python) | [pypi.org/project/miosa](https://pypi.org/project/miosa/) | **1.1.0** |
| `@miosa/sdk` (TypeScript) | [npmjs.com/package/@miosa/sdk](https://www.npmjs.com/package/@miosa/sdk) | **1.1.0** |
| `miosa` (Elixir) | [hex.pm/packages/miosa](https://hex.pm/packages/miosa) | **1.1.0** |
| `github.com/Miosa-osa/miosa-go` (Go) | [pkg.go.dev/github.com/Miosa-osa/miosa-go](https://pkg.go.dev/github.com/Miosa-osa/miosa-go) | **v0.4.0** |
| `ai.miosa:miosa-sdk` (Java) | [central.sonatype.com](https://central.sonatype.com/artifact/ai.miosa/miosa-sdk) | **0.4.0** |
| `@miosa/react` / `@miosa/vue` / `@miosa/svelte` | npm | **0.2.0** |

### Breaking changes

None. The 1.1.0 release is purely additive across all SDK packages and the REST API.

### Migration notes

No migration required. Existing integrations continue to work without changes.

---

## May 19 - 25, 2026

### Auto-snapshot on custom template create

`POST /v1/sandbox-templates` now enqueues a background Oban job that boots the template once and captures its memory snapshot immediately after the template row is committed. For customer-defined templates, the first boot on the build host lands on the snapshot-restore path (~47 ms p50 in benchmarks) rather than the 500-1500 ms cold-boot path. End-to-end production verification is in progress.

### Eager snapshot distribution across the fleet

After a template snapshot is built, the platform replicates it across the fleet in parallel. The intent is that the first user in any region hits the warm path, not just the region where the template was created. Distribution failures are non-fatal  -  an on-demand replication fallback remains in place.

### Fixed: `sandbox_expose` MCP tool returned broken URLs

The MCP tool was hand-rolling `https://<slug>.<domain>:<port>` URLs that the proxy does not route. It also skipped proxy cache registration, so the slug→VM-IP route was never wired. The fix uses the preview URL resolver for the canonical URL shape and registers the route through the proxy cache. Deployed 2026-05-25.

---

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

### Computer tunnels

The computer command service 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.

  All commands below are live in `@miosa/cli@1.0.1` unless marked **[planned]**.

## 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 /workspace
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
```

---

### Logs

#### `miosa logs &lt;name-or-id&gt; [--follow] [--since duration] [--lines n]`

Stream or tail logs from a computer, sandbox, or deployment.

```bash
miosa logs dev-box
miosa logs dev-box --follow
miosa logs my-app --since 1h --lines 200
```

| Flag | Description |
|---|---|
| `--follow` | Keep streaming new log lines |
| `--since &lt;duration&gt;` | Show logs from the past N hours/minutes, e.g. `30m`, `2h` |
| `--lines &lt;n&gt;` | Number of historical lines to show (default: 100) |

---

### Environment

#### `miosa env list &lt;name-or-id&gt;`

List environment variables for a computer or deployment.

```bash
miosa env list dev-box
miosa env list my-app
```

#### `miosa env set &lt;name-or-id&gt; KEY=VALUE [KEY=VALUE...]`

Set one or more environment variables.

```bash
miosa env set dev-box DATABASE_URL=postgres://...
miosa env set my-app NODE_ENV=production PORT=8080
```

#### `miosa env unset &lt;name-or-id&gt; KEY [KEY...]`

Remove environment variables.

```bash
miosa env unset dev-box DATABASE_URL
```

---

### Scaling

#### `miosa scale &lt;name-or-id&gt; [--size size] [--replicas n]`

Scale a computer or deployment.

```bash
miosa scale dev-box --size large
miosa scale my-app --replicas 3
```

| Flag | Description |
|---|---|
| `--size &lt;size&gt;` | `small`, `medium`, `large` |
| `--replicas &lt;n&gt;` | Number of replicas (deployments only) |

---

### Rollback

#### `miosa rollback &lt;name-or-id&gt; [--version id] [--to-release id]`

Roll a deployment back to a previous version or release.

```bash
miosa rollback my-app
miosa rollback my-app --version ver_abc123
miosa rollback my-app --to-release rel_xyz789
```

---

### Releases

#### `miosa releases list &lt;name-or-id&gt;`

List all releases for a deployment.

```bash
miosa releases list my-app
miosa releases list my-app --json
```

#### `miosa releases get &lt;name-or-id&gt; &lt;release-id&gt;`

Show metadata for a specific release.

```bash
miosa releases get my-app rel_abc123
```

---

### Builds

#### `miosa builds list &lt;name-or-id&gt;`

List build history for a deployment.

```bash
miosa builds list my-app
```

#### `miosa builds get &lt;name-or-id&gt; &lt;build-id&gt;`

Show build details and output.

```bash
miosa builds get my-app bld_abc123
```

#### `miosa builds logs &lt;name-or-id&gt; &lt;build-id&gt; [--follow]`

Stream build logs.

```bash
miosa builds logs my-app bld_abc123 --follow
```

---

### Regions

#### `miosa regions list`

List all available regions with latency and capacity information.

```bash
miosa regions list
miosa regions list --json
```

#### `miosa regions get &lt;slug&gt;`

Show details for a specific region.

```bash
miosa regions get us-east-ny
```

---

### Teams

#### `miosa teams list`

List all teams in the current tenant.

```bash
miosa teams list
```

#### `miosa teams create &lt;name&gt;`

Create a new team.

```bash
miosa teams create backend-infra
```

#### `miosa teams members &lt;team&gt;`

List members of a team.

```bash
miosa teams members backend-infra
```

#### `miosa teams add &lt;team&gt; &lt;user-email&gt;`

Add a user to a team.

```bash
miosa teams add backend-infra alice@example.com
```

#### `miosa teams remove &lt;team&gt; &lt;user-email&gt;`

Remove a user from a team.

```bash
miosa teams remove backend-infra alice@example.com
```

---

### Billing

#### `miosa billing status`

Show current credit balance, plan, and usage this period.

```bash
miosa billing status
```

#### `miosa billing usage [--window window]`

Show compute usage for a time window.

```bash
miosa billing usage
miosa billing usage --window 30d
```

---

### Templates

#### `miosa templates list`

List all available computer and sandbox templates.

```bash
miosa templates list
miosa templates list --json
```

#### `miosa templates get &lt;slug&gt;`

Show details for a template.

```bash
miosa templates get miosa-desktop
```

---

### 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 storage objects list &lt;bucket&gt; [--prefix prefix]`

List objects in a bucket.

```bash
miosa storage objects list my-bucket
miosa storage objects list my-bucket --prefix uploads/
```

#### `miosa storage objects upload &lt;bucket&gt; &lt;local-path&gt; &lt;key&gt;`

Upload a file to a bucket.

```bash
miosa storage objects upload my-bucket ./dist/app.js dist/app.js
```

#### `miosa storage objects download &lt;bucket&gt; &lt;key&gt; [local-path]`

Download an object from a bucket.

```bash
miosa storage objects download my-bucket dist/app.js ./app.js
```

#### `miosa storage objects delete &lt;bucket&gt; &lt;key&gt;`

Delete an object from a bucket.

```bash
miosa storage objects delete my-bucket dist/app.js
```

#### `miosa storage objects url &lt;bucket&gt; &lt;key&gt; [--expires duration]`

Generate a signed URL for an object.

```bash
miosa storage objects url my-bucket dist/app.js --expires 1h
```

#### `miosa databases backup &lt;name-or-id&gt; [--label label]`

Trigger a manual database backup.

```bash
miosa databases backup app-db
miosa databases backup app-db --label before-migration
```

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

To extend Claude Code with MIOSA-specific skills (sandbox, computer, deploy primitives), see [github.com/Miosa-osa/miosa-skills](https://github.com/Miosa-osa/miosa-skills) or the [Skills guide](/docs/guides/skills/).

#### `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:/workspace/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 isolated 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 isolated 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 CS as Command service
    participant X as X11 desktop

    A->>API: computer.screenshot()
    API->>CS: capture frame
    CS->>X: read screen
    X-->>CS: pixel data
    CS-->>API: PNG bytes
    API-->>A: bytes

    A->>API: computer.left_click(500, 300)
    API->>CS: inject click event
    CS->>X: send click
    X-->>CS: ack
    CS-->>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 /workspace/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("/workspace/script.py", "print('hello')")
computer.bash("python3 /workspace/script.py")
```

### `read_file(path)`

Read a file from the VM's filesystem. Returns the content as a string.

```python
content = computer.read_file("/workspace/.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 with a short-lived stream URL. Pixel streaming and input forwarding are handled by MIOSA.

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

MIOSA handles pixel streaming and input forwarding inside the iframe. The user clicks or types in the iframe and those events go to the desktop.

## What's streamed

- **Pixels**  -  encoded video 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 cloud desktop environment. Use it when you need a real GUI surface: 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 desktop 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 --> Desktop["Desktop environment"]
    Desktop -->|input| Session["Desktop session"]
    Desktop -->|frame| Stream["Pixel stream"]
    Stream -->|WebSocket| Browser["Browser iframe"]

Your code talks to the MIOSA API. MIOSA routes actions to an desktop command service. The command service 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` | The desktop environment is starting |
| `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 |
|---|---|---|---|---|
| `xs` | 1 | 2 GB | 10 GB | Lightweight headless tasks |
| `small` | 2 | 4 GB | 20 GB | **Default**  -  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 |
| `xl` | 16 | 32 GB | 200 GB | Intensive parallelism, large model weights |

GPU support for accelerated desktop and GPU-aware agent workflows is plan-dependent.

Computers ship with the OSA agent installed but disabled by default. Activate it to give your computer an desktop AI assistant that can run multi-step desktop tasks autonomously. OSA is controlled through documented MIOSA APIs.

## 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 product model for MIOSA  -  sandboxes, previews, deployments, versions, domains, data services, desktop Computers, and white-label tenancy.

# 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 → Preview while editing → Publish → Version → Deployment → Domain.** That is the product pipeline.

---

## Infrastructure model

MIOSA exposes product primitives, not raw infrastructure. You create sandboxes, previews, deployments, computers, domains, and data services. MIOSA handles placement, isolation, routing, health checks, certificates, and cleanup behind those objects.

---

## The six concrete things

### Sandbox

A **Sandbox** is a mutable isolated environment where an agent or developer builds an app. It 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://5173-abc12345.sandbox.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 the internal publish worker that runs for one publish job. It freezes the sandbox source at publish time, runs the build pipeline, stores the result, and exits.

Three build modes:

| Mode | Trigger | Output |
|------|---------|--------|
| Static packager | `/workspace` has only static files | Tarball served from MIOSA's edge |
| Auto-detect | Node/Python/Ruby/Go project detected | Dynamic release served by production runtimes |
| Dockerfile | `Dockerfile` present in `/workspace` | Dynamic release served by production runtimes |

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 server app artifact. Served by production runtimes.

[Releases reference →](/docs/deploy/releases/)

### Runtime Instance

A **Runtime Instance** is a production runtime for a dynamic deployment. It serves real traffic and is managed by MIOSA's 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 is isolated from other tenants and from the original build sandbox.

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.my-workspace.miosa.app`  -  MIOSA-managed fallback URL, instant, no DNS change needed.
- `my-app.apps.yourplatform.com`  -  tenant deployment domain for generated apps.
- `app.yourcustomer.com`  -  custom domain your customer brings; MIOSA auto-provisions a TLS certificate via Let's Encrypt.

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 desktop environments 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) | Desktop stream |
| 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/)

---

## External attribution

**External attribution** is how you map MIOSA resources to your own users, projects, and tenants without creating MIOSA accounts for them.

Three opaque string fields are accepted on every resource that supports creation:

| Field | Purpose |
|-------|---------|
| `external_user_id` | The end-user inside your system who owns or triggered this resource |
| `external_project_id` | The project, document, or workflow in your database that this resource belongs to |
| `metadata` | Arbitrary key-value map for any additional context your platform needs |

These fields are stored and returned on reads. They are filterable on list endpoints. Usage rollup (`GET /v1/usage?group_by=external_user_id`) aggregates compute and storage consumption per attributed user  -  enabling per-customer chargeback without any secondary accounting pipeline.

MIOSA never interprets or validates the content of external attribution fields. They are always stored as-is.

[Attribution reference →](/docs/platform/attribution/)

---

## Preview tokens

A **preview token** (prefix `mp_*`) is a short-lived signed token that authorizes a browser to load a sandbox preview without receiving the workspace API key.

The typical flow:

1. Your backend calls `POST /v1/preview-tokens` with the sandbox ID and a TTL (max 24 hours).
2. Your backend passes the token value to the browser  -  for example, as a page prop or a short-lived cookie.
3. The browser constructs the preview URL: `https://<slug>.sandbox.miosa.app?token=mp_...`
4. MIOSA's edge verifies the token server-side and proxies the request to the sandbox port. The token value never grants broader access.

Preview tokens are non-renewable and non-transferable. When the TTL expires the URL returns `401`. Your backend mints a new token to restore access.

[Browser Tokens reference →](/docs/platform/browser-tokens/)

---

## Share tokens

A **share token** (prefix `ms_*`) is a revocable public share URL for a sandbox preview  -  analogous to a "share link" in a document editor.

Key differences from preview tokens:

| | Preview token (`mp_*`) | Share token (`ms_*`) |
|--|------------------------|----------------------|
| Intended recipient | Your authenticated user | Anyone with the link |
| Minted by | Your backend | Your backend |
| Revocable | Yes (delete the token) | Yes (delete the token) |
| Password protection | No | Optional |
| Expiry | Required TTL | Optional |

Share tokens are useful for demos, client reviews, or collaborative previews where the recipient does not have a user account in your system. The link can be embedded as a plain URL  -  no `Authorization` header needed.

[Previews reference →](/docs/develop/previews/)

---

## Tenant preview domain

A **tenant preview domain** is a custom hostname that replaces MIOSA fallback preview domains in every sandbox preview URL your end users see.

When you register and verify a preview domain (for example, `preview.yourproduct.com`), sandbox previews for your workspace are served at:

```
https://<sandbox-slug>.preview.yourproduct.com
```

Setup is a two-step DNS verification: add a CNAME record pointing to MIOSA's edge, then call `POST /v1/tenant/preview-domain/verify`. MIOSA auto-provisions a wildcard TLS certificate via Let's Encrypt once the CNAME resolves.

One preview domain per workspace. The domain applies to all sandboxes in the workspace.

[Custom Domains reference →](/docs/deploy/domains/)

---

## Tenant branding

**Tenant branding** controls what your end users see on MIOSA-rendered pages  -  specifically 4xx and 5xx error pages displayed when a sandbox is unavailable, a preview URL is invalid, or a custom domain is not yet verified.

Configurable fields:

| Field | Description |
|-------|-------------|
| `logo_url` | HTTPS URL to your logo image (PNG or SVG, max 2 MB) |
| `accent_color` | Hex color applied to headings and buttons on error pages |
| `support_url` | Optional link shown on error pages for end-user support |

Branding is set via `PUT /v1/tenant/branding` and takes effect within 60 seconds across all edge nodes.

MIOSA's own wordmark never appears on branded error pages.

[Tenant branding API →](/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 agent** | The 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 for app builders, white-label SaaS, lead magnets, code execution, browser agents, previews, and production deploys.

# Cookbook

Practical walkthroughs for the things customers actually build on MIOSA. Each recipe starts with a product goal, then shows the sandbox, preview, deployment, domain, token, and attribution pieces involved.

---

## Agent and app building


    Full lifecycle: user prompt → agent writes files → dev server → live preview → feedback loop → publish → stable production URL.


    Run code and stream stdout to your UI in real time. Useful for graders, workflow builders, data jobs, and AI tool execution.


    Use a Computer when the task needs a real browser: screenshots, clicks, forms, login flows, and human takeover.


---

## Multi-tenant and SaaS


    Example product flow: a clinic asks for a campaign, the agent builds a landing page, previews it on the platform domain, and publishes to a durable app URL.


    Full-stack flow: generated server app, managed data intent, dynamic runtime, health check, and final deployment URL returned by the API.


    Embed a live sandbox preview in your product while the app is still changing. Your backend mints the browser-safe token.


    Tag every sandbox with your own workspace and user IDs. Query usage per tenant. Issue browser tokens. Set per-user quotas. Pull the audit log.


    Cap end-users with max_sandboxes and credit limits. Pull monthly usage rollups keyed by external_user_id. Wire into Stripe for automated invoicing.


    Completely rebrand the sandbox experience with your own domain, logo, and colors. End users never see MIOSA.


---

## Embedding and real-time


    Server mints a preview token; frontend drops it into an iframe. React, Vue, Svelte, and vanilla JS variants. Covers token TTL refresh.


    React to sandbox lifecycle events via HMAC-signed webhooks (durable, server-to-server) or the SSE stream (in-process). Idempotency patterns included.


---

## Resilience and safety


    Checkpoint a long-running task with snapshots. Fork into parallel branches for A/B experiments. Restore to a known-good state on failure.


    Inject API keys and credentials into sandboxes without exposing them in code or logs.


    Restrict what code running inside a sandbox can reach  -  egress allowlists, network policies, and audit logging.


---

## 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, iterates visually with live preview, checkpoints progress, branches experiments, shares with stakeholders, and publishes to production.

# Agent builds an app

~15 min Python TypeScript

> **Goal**: Wire an LLM agent to MIOSA so it can write code, boot a live dev server, iterate on feedback with real-time preview, checkpoint progress, branch into experiments, share with stakeholders, track usage, and finally publish to production  -  all from a single user prompt.
>
> **What you'll use**: Sandboxes, Processes, Previews, Snapshots, Shares, Deployments, Usage

## What you'll build

A full-lifecycle function `agent_app_lifecycle(prompt)` that:

1. Generates initial files with an LLM and writes them atomically
2. Boots a dev server and mints a preview token for iframe embed
3. Iterates on user feedback  -  patches files, watches the file tree, preview auto-refreshes
4. Checkpoints between iterations so experiments can branch safely
5. Forks into parallel branches for A/B comparison without losing the working version
6. Creates a shareable public URL for stakeholder review
7. Tracks usage so you can bill the end-user
8. Promotes to an immutable production deployment

The pattern is model-agnostic  -  MIOSA is the execution layer, your agent loop is the reasoning layer.

## Flow diagram

Diagram:
sequenceDiagram
    participant U as User
    participant A as Your Agent
    participant M as MIOSA Sandbox

    U->>A: "Build a dog-walking app landing page"
    A->>M: sandboxes.create(template_id="nextjs")
    A->>M: files.writeMany([page.tsx, styles.css, ...])
    M->>A: ACK
    A->>M: processes.start("pnpm run dev")
    A->>M: sbx.previewToken(expires_in=3600)
    M-->>U: iframe embed with live preview

    loop Iterate on feedback
        U->>A: "Make the hero bigger"
        A->>M: files.writeMany([updated page.tsx])
        M-->>U: Preview auto-refreshes
        A->>M: sbx.snapshots.create("v2-hero-large")
    end

    A->>M: sbx.fork() → branch sandbox
    Note over A,M: A/B experiment in parallel branch

    A->>M: sbx.previews.create(port=3000)
    A->>M: sbx.previews.share(preview_id, ttl_seconds=86400)
    M-->>U: Public stakeholder URL

    U->>A: "Ship it"
    A->>M: sbx.deploy(name="dogwalk-landing")
    M-->>U: Production URL

## 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 and write initial files

Create a Next.js sandbox. The template already has Node, pnpm, and a scaffold  -  skip `npx create-next-app`. Use `files.writeMany` to push all initial files in a single atomic call.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
ai = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# Boot the sandbox
sbx = client.sandboxes.create(
    template_id="nextjs",
    timeout_sec=3600,
    external_user_id="user-42",   # attribute usage to your end-user
)

# Ask the LLM to generate the initial file set
def generate_files(prompt: str) -> list[dict]:
    msg = ai.messages.create(
        model="claude-opus-4-5",
        max_tokens=8096,
        system=(
            "You are a Next.js developer. "
            "Return a JSON array of {path, content} objects for every file you create. "
            "Paths are relative to /workspace. Content is the full file text. "
            "No explanation, just the JSON array."
        ),
        messages=[{"role": "user", "content": prompt}],
    )

    return json.loads(msg.content[0].text)

user_prompt = "Build a landing page for a dog-walking app with a hero, feature list, and CTA."
file_list = generate_files(user_prompt)

# Write all files atomically
result = sbx.files.write_many(file_list)
print(f"Written: {[f['path'] for f in result['written']]}")
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const ai = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

// Boot the sandbox
const sbx = await client.sandboxes.create({
  templateId: 'nextjs',
  timeoutSec: 3600,
  externalUserId: 'user-42',
});

async function generateFiles(prompt: string): Promise<Array<{ path: string; content: string }>> {
  const msg = await ai.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 8096,
    system:
      'You are a Next.js developer. Return a JSON array of {path, content} objects for every file you create. ' +
      'Paths are relative to /workspace. Content is the full file text. No explanation, just the JSON array.',
    messages: [{ role: 'user', content: prompt }],
  });
  const block = msg.content[0];
  return JSON.parse(block.type === 'text' ? block.text : '[]');
}

const userPrompt = 'Build a landing page for a dog-walking app with a hero, feature list, and CTA.';
const fileList = await generateFiles(userPrompt);

// Write all files atomically
const result = await sbx.files.writeMany(fileList);
console.log('Written:', result.written.map(f => f.path));
```

## Step 3  -  Start the dev server and mint a preview token

Use `processes.start` to boot the dev server as a long-running background process. Then call `sbx.previewToken` to get a short-lived token your frontend uses in an iframe  -  no public URL required, no `msk_*` key ever reaches the browser.

```python
# Start the dev server as a long-running process
proc = sbx.processes.start(
    command="pnpm run dev --port 3000",
    name="nextjs-dev",
)
print(f"Dev server pid: {proc['pid']}")

# Mint a 1-hour preview token for iframe embed
token_info = sbx.preview_token(expires_in=3600)
print(f"Embed URL: {token_info['url']}")
# Send token_info['url'] to your frontend  -  use it as <iframe src="...">
```

```typescript
// Start the dev server as a long-running process
// (processes is available via the SDK's raw API  -  Python-first feature)
// For TypeScript, exec with background flag while processes lands:
await sbx.exec('pnpm run dev --port 3000 &', { cwd: '/workspace' });

// Mint a 1-hour preview token for iframe embed
const tokenInfo = await sbx.previewToken(3600);
console.log('Embed URL:', tokenInfo.url);
// Send tokenInfo.url to your frontend  -  use as <iframe src="...">
```

`previewToken` returns a `mp_` prefixed token embedded in the URL. It grants read-only access to the sandbox's HTTP port for the duration of the TTL. Refresh it before expiry by calling `previewToken` again  -  the new URL replaces the old one in the iframe `src`.

## Step 4  -  Iterate on feedback

When the user gives feedback, generate a patch, write it with `writeMany`, and optionally watch the file tree via SSE so your UI can reflect what changed. The preview iframe auto-refreshes because the dev server is still running.

```python
def apply_feedback(sbx, current_prompt: str, feedback: str) -> list[dict]:
    """Generate a patch from LLM feedback and write it to the sandbox."""
    # Read the current file tree to give the LLM context
    tree = sbx.files.tree("/workspace", recursive=True)

    patch_prompt = (
        f"Original request: {current_prompt}\n\n"
        f"Current file tree:\n{tree}\n\n"
        f"User feedback: {feedback}\n\n"
        "Return a JSON array of {path, content} objects for ONLY the files that need to change."
    )

    msg = ai.messages.create(
        model="claude-opus-4-5",
        max_tokens=4096,
        system="You are a Next.js developer. Return only a JSON array of {path, content} objects. No explanation.",
        messages=[{"role": "user", "content": patch_prompt}],
    )

    changed_files = json.loads(msg.content[0].text)

    # Atomic write of changed files only
    result = sbx.files.write_many(changed_files)
    return result["written"]

# Example iteration
changed = apply_feedback(sbx, user_prompt, "Make the hero section taller and use a dark background")
print(f"Patched {len(changed)} files  -  preview refreshing automatically")
```

```typescript
async function applyFeedback(
  sbx: typeof import('@miosa/sdk').Sandbox.prototype,
  currentPrompt: string,
  feedback: string,
): Promise<Array<{ path: string; size_bytes: number }>> {
  const tree = await sbx.files.tree('/workspace', 3);

  const patchPrompt =
    `Original request: ${currentPrompt}\n\n` +
    `Current file tree:\n${JSON.stringify(tree, null, 2)}\n\n` +
    `User feedback: ${feedback}\n\n` +
    'Return a JSON array of {path, content} objects for ONLY files that need to change.';

  const msg = await ai.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 4096,
    system: 'You are a Next.js developer. Return only a JSON array of {path, content}. No explanation.',
    messages: [{ role: 'user', content: patchPrompt }],
  });
  const block = msg.content[0];
  const changedFiles: Array<{ path: string; content: string }> = JSON.parse(
    block.type === 'text' ? block.text : '[]',
  );

  const result = await sbx.files.writeMany(changedFiles);
  return result.written;
}

const changed = await applyFeedback(sbx, userPrompt, 'Make the hero section taller with a dark background');
console.log(`Patched ${changed.length} files  -  preview refreshing automatically`);
```

### Watch file changes over SSE

If your backend needs to push file-tree diffs to your UI in real time:

```python
# Subscribe to file change events (SSE  -  runs until cancelled)
for change in sbx.files.watch():
    # change = {"type": "modified"|"created"|"deleted", "path": "...", "size_bytes": N}
    print(f"[file] {change['type']}: {change['path']}")
    # Forward to your frontend over WebSocket or SSE
```

```typescript
// Subscribe to file change events
for await (const change of sbx.files.watch()) {
  // change = { type: "modified" | "created" | "deleted", path: "...", size_bytes?: N }
  console.log(`[file] ${change.type}: ${change.path}`);
  // Forward to your frontend over WebSocket or SSE
}
```

## Step 5  -  Checkpoint progress

Snapshot the sandbox between iterations. Each snapshot captures filesystem state. If a later iteration breaks things, you can fork back to a known-good point.

```python

# Snapshot after the first working iteration
snap = sbx.snapshots.create("v1-dark-hero")
print(f"Snapshot {snap['id']}  -  status: {snap['status']}")

# Poll until ready (snapshots upload asynchronously)
while snap["status"] not in ("ready", "failed"):
    time.sleep(2)
    snap = sbx.snapshots.list()[0]  # re-fetch

if snap["status"] == "failed":
    raise RuntimeError("Snapshot failed")

print(f"Checkpoint ready: {snap['id']}")
snapshot_id = snap["id"]
```

```typescript
// Snapshot after the first working iteration
let snap = await sbx.snapshots.create('v1-dark-hero');
console.log(`Snapshot ${snap.id}  -  status: ${snap.status}`);

while (snap.status !== 'ready' && snap.status !== 'failed') {
  await new Promise(r => setTimeout(r, 2000));
  const snaps = await sbx.snapshots.list();
  snap = snaps.find(s => s.id === snap.id) ?? snap;
}

if (snap.status === 'failed') throw new Error('Snapshot failed');
console.log('Checkpoint ready:', snap.id);
const snapshotId = snap.id;
```

## Step 6  -  Branch into experiments

Fork the sandbox to create an independent copy for a risky or experimental change. The original sandbox is unaffected. Destroy the branch when you're done comparing.

```python
# Fork the current sandbox  -  creates a new independent sandbox from live state
branch = sbx.fork(name="branch-bolder-cta")
print(f"Branch sandbox: {branch.id}")

# Apply a different variant in the branch only
apply_feedback(branch, user_prompt, "Replace the CTA button with a neon green pill shape")

# Compare results, then destroy the losing branch
branch.delete()
print("Branch discarded")
```

```typescript
// Fork the current sandbox
const branch = await sbx.fork({ name: 'branch-bolder-cta' });
console.log('Branch sandbox:', branch.id);

// Apply a different variant in the branch only
await applyFeedback(branch, userPrompt, 'Replace the CTA button with a neon green pill shape');

// Compare, then destroy the losing branch
await branch.delete();
console.log('Branch discarded');
```

## Step 7  -  Share with stakeholders

Create a preview record for the running port, then mint a share token. The share URL is publicly accessible (read-only) for the TTL you specify.

```python
# Create a preview pointing at the dev server
preview = sbx.previews.create(port=3000)
preview_id = preview["id"]

# Mint a 24-hour public share token
share = sbx.previews.share(preview_id, ttl_seconds=86400)
print(f"Stakeholder URL: {share['share_url']}")
# Anyone with this URL can view the live sandbox in a browser  -  no login required
```

```typescript
// Create a preview pointing at the dev server
const preview = await sbx.previews.create(3000);
const previewId = String(preview.id ?? preview.preview_id ?? '');

// Mint a 24-hour public share token
const share = await sbx.previews.share(previewId, { ttl_seconds: 86400 });
console.log('Stakeholder URL:', share.share_url);
```

## Step 8  -  Track usage

Query usage attributed to the end-user who initiated this session. Use this to drive per-user billing in your platform.

```python
# Pull usage for this end-user over the current period
report = client.usage.report(computer_id=sbx.id)
print(f"Sandbox usage  -  credits: {report.get('total_credits', 'n/a')}")

# Or roll up across all sandboxes for this user (Python-first)
# user_report = client.usage.report(external_user_id="user-42", group_by="external_user_id")
```

```typescript
// Pull usage for this session
const report = await client.usage.report({ computer_id: sbx.id });
console.log(`Sandbox usage  -  credits: ${report.total_credits ?? 'n/a'}`);
```

## Step 9  -  Promote to production

When the user confirms, run the production build and deploy. The deployment is immutable. Destroy the sandbox after deploy  -  you no longer need it.

```python
# Run the production build first
build = sbx.exec("pnpm run build", cwd="/workspace")
if build.exit_code != 0:
    # Self-correction turn
    fixed_files = generate_files(
        f"Fix this Next.js build error and return only the affected files:\n{build.stderr}"
    )
    sbx.files.write_many(fixed_files)
    build = sbx.exec("pnpm run build", cwd="/workspace")
    if build.exit_code != 0:
        raise RuntimeError("Build failed after correction.")

# Keep the sandbox alive if the user wants persistence instead
# sbx.update(always_on=True)

# Or deploy to production and clean up
deployment = sbx.deploy(name="dogwalk-landing")

while deployment.get("status") not in ("live", "failed"):
    time.sleep(2)
    deployment = client.deployments.get(deployment["id"])

if deployment.get("status") == "failed":
    raise RuntimeError(f"Deployment failed: {deployment.get('error')}")

print(f"Production URL: {deployment.get('url')}")

# Clean up the sandbox  -  deployment is the durable artifact
sbx.delete()
```

```typescript
// Run the production build
let build = await sbx.exec('pnpm run build', { cwd: '/workspace' });
if (build.exitCode !== 0) {
  const fixedFiles = await generateFiles(
    `Fix this Next.js build error and return only the affected files:\n${build.stderr}`,
  );
  await sbx.files.writeMany(fixedFiles);
  build = await sbx.exec('pnpm run build', { cwd: '/workspace' });
  if (build.exitCode !== 0) throw new Error('Build failed after correction.');
}

// Keep the sandbox alive if the user wants persistence instead of deploying
// await sbx.update({ always_on: true });

// Or deploy to production
const deployment = await sbx.deploy({ name: 'dogwalk-landing' });

let dep = deployment;
while (dep.status !== 'live' && dep.status !== 'failed') {
  await new Promise(r => setTimeout(r, 2000));
  dep = await client.deployments.get(String(dep.id));
}

if (dep.status === 'failed') throw new Error(`Deployment failed: ${dep.error}`);
console.log('Production URL:', dep.url);

await sbx.delete();
```

## What you learned

- `files.writeMany` pushes multiple files atomically in a single request  -  faster than individual writes and avoids partial state.
- `processes.start` keeps the dev server alive across multiple `exec` calls. The sandbox does not have to restart between iterations.
- `sbx.previewToken(expires_in)` returns an iframe-safe URL with no `msk_*` key  -  safe to embed directly in your frontend.
- `sbx.files.watch()` is an SSE stream of file changes you can relay to your UI for live file-tree updates.
- `sbx.snapshots.create(comment)` checkpoints without stopping the sandbox. The sandbox keeps running while the snapshot uploads.
- `sbx.fork()` creates a fully independent copy of the live sandbox for A/B experiments. No shared state, no interference.
- `sbx.previews.create(port)` + `sbx.previews.share(preview_id, ttl_seconds=86400)` produce a public stakeholder link that expires automatically.
- `sbx.update(always_on=True)` makes a sandbox persistent after the agent session ends  -  use when the user wants to keep editing.
- `sbx.deploy(name=...)` produces an immutable release; the sandbox can be destroyed immediately after.

## Related


    Server mints a preview token; frontend uses it in a React, Vue, Svelte, or vanilla iframe.


    Deep dive on the checkpoint and branch-and-compare pattern.


    Cap end-users, roll up monthly usage, and generate invoices.


    React to sandbox lifecycle events via webhooks or SSE.

---

# Agent with secrets  -  full walkthrough

URL: https://miosa.ai/docs/cookbook/agent-with-secrets
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/agent-with-secrets
Source: src/routes/docs/cookbook/agent-with-secrets/+page.md
Description: Create a sandbox, store an OpenAI key and connect GitHub via OAuth, run an AI agent, watch the audit log live, lock the network down, then rotate the key mid-run.

# Agent with secrets  -  full walkthrough

~20 min Python TypeScript Go

> **Goal**: Build a customer-support AI agent in a MIOSA sandbox that calls OpenAI and reads GitHub issues. Wire up vault-managed secrets for both credentials. Watch the audit trail in real time. Lock down egress to only those two hosts. Then rotate the OpenAI key while the agent is mid-run  -  no restart, no redeploy.
>
> **What you'll use**: Sandboxes, Secrets, Connect Accounts, Audit Log, Network Allowlist

## What you'll build

```
Your backend
  └─ creates sandbox
  └─ sets OpenAI API key in vault           → sandbox sees $OPENAI_API_KEY (placeholder)
  └─ connects GitHub via OAuth              → sandbox sees $GITHUB_TOKEN (placeholder)
  └─ runs agent code                        → proxy swaps placeholders on egress
  └─ tails audit log (live stream)          → every outbound call visible
  └─ locks down to api.openai.com + api.github.com
  └─ rotates OpenAI key while agent runs    → next request silently picks up new key
```

## Prerequisites

- MIOSA API key (`msk_live_*`)  -  see [API Keys](/docs/platform/api-keys/)
- OpenAI API key (`sk-proj-*`)
- GitHub account (for the OAuth step)
- Python 3.11+ or Node 22+

## Step 1  -  Install and configure

```bash
pip install miosa openai
export MIOSA_API_KEY="msk_live_..."
export MY_OPENAI_KEY="sk-proj-..."   # stored on your machine, not in the sandbox
```

```bash
npm install @miosa/sdk openai
export MIOSA_API_KEY="msk_live_..."
export MY_OPENAI_KEY="sk-proj-..."
```

```bash
go get github.com/miosa-ai/miosa-go
export MIOSA_API_KEY="msk_live_..."
export MY_OPENAI_KEY="sk-proj-..."
```

## Step 2  -  Create the sandbox

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

sandbox = client.sandboxes.create(
    template="python-ds",
    timeout_sec=1800,   # 30 min for a long-running agent
)
print(f"Sandbox ready: {sandbox.id}")
```

```typescript

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

const sandbox = await client.sandboxes.create({
  template: 'python-ds',
  timeoutSec: 1800,
});
console.log('Sandbox ready:', sandbox.id);
```

```go
package main

    "context"
    "fmt"
    "os"
    miosa "github.com/miosa-ai/miosa-go"
)

func main() {
    ctx := context.Background()
    client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))

    sandbox, err := client.Sandboxes.Create(ctx, miosa.SandboxCreate{
        Template:   "python-ds",
        TimeoutSec: 1800,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Sandbox ready:", sandbox.ID)
}
```

## Step 3  -  Add the OpenAI key to the vault

The real key never enters the sandbox. The sandbox sees only an opaque placeholder that the MIOSA proxy swaps on the way out.

```python
sandbox.secrets.set(
    name="openai_key",
    value=os.environ["MY_OPENAI_KEY"],
    expose_as_env="OPENAI_API_KEY",
)
print("OpenAI secret saved.")
```

```typescript
await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});
console.log('OpenAI secret saved.');
```

```go
err = sandbox.Secrets.Set(ctx, miosa.SecretSet{
    Name:        "openai_key",
    Value:       os.Getenv("MY_OPENAI_KEY"),
    ExposeAsEnv: "OPENAI_API_KEY",
})
if err != nil {
    panic(err)
}
fmt.Println("OpenAI secret saved.")
```

Verify it landed:

```python
result = sandbox.exec("echo $OPENAI_API_KEY")
print(result.stdout)
# → miosa-tok-7f2a8c1d4b2e6f0a...
# NOT the real key. Good.
```

```typescript
const result = await sandbox.exec('echo $OPENAI_API_KEY');
console.log(result.stdout);
// → miosa-tok-7f2a8c1d4b2e6f0a...
```

```go
result, _ := sandbox.Exec(ctx, "echo $OPENAI_API_KEY", miosa.ExecOpts{})
fmt.Println(result.Stdout)
// → miosa-tok-7f2a8c1d4b2e6f0a...
```

## Step 4  -  Connect GitHub via OAuth

```python
flow = sandbox.secrets.connect(
    provider="github",
    expose_as_env="GITHUB_TOKEN",
    scopes=["repo", "read:user"],
)

# Open this URL in your browser (or send it to your end-user)
print("Authorize at:", flow.authorize_url)

# Block until the user completes the OAuth dance (up to 5 minutes)
flow.wait_for_completion(timeout=300)
print("GitHub connected.")
```

```typescript
const flow = await sandbox.secrets.connect({
  provider: 'github',
  exposeAsEnv: 'GITHUB_TOKEN',
  scopes: ['repo', 'read:user'],
});

console.log('Authorize at:', flow.authorizeUrl);
await flow.waitForCompletion({ timeoutSec: 300 });
console.log('GitHub connected.');
```

```go
flow, err := sandbox.Secrets.Connect(ctx, miosa.OAuthConnect{
    Provider:    "github",
    ExposeAsEnv: "GITHUB_TOKEN",
    Scopes:      []string{"repo", "read:user"},
})
if err != nil {
    panic(err)
}
fmt.Println("Authorize at:", flow.AuthorizeURL)

if err := flow.WaitForCompletion(ctx, 300); err != nil {
    panic(err)
}
fmt.Println("GitHub connected.")
```

In a white-label product you'd send `flow.authorize_url` to your end-user instead of opening it yourself. See [White-label Credentials](/docs/security/white-label) for the full pattern.

## Step 5  -  Write and run the agent

Now write a simple agent that reads open GitHub issues and drafts replies via OpenAI. The code uses both env vars exactly as it would on a bare machine  -  no MIOSA-specific client code inside the sandbox.

```python
agent_code = '''

GITHUB_TOKEN = os.environ["GITHUB_TOKEN"]
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
REPO = "your-org/your-repo"

def get_open_issues():
    resp = requests.get(
        f"https://api.github.com/repos/{REPO}/issues",
        headers={"Authorization": f"Bearer {GITHUB_TOKEN}"},
        params={"state": "open", "per_page": 5},
    )
    resp.raise_for_status()
    return resp.json()

def draft_reply(issue_body: str) -> str:
    payload = {
        "model": "gpt-4o-mini",
        "messages": [
            {"role": "system", "content": "You are a helpful support agent. Draft a polite reply."},
            {"role": "user", "content": issue_body},
        ],
    }
    resp = requests.post(
        "https://api.openai.com/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {OPENAI_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    resp.raise_for_status()
    return resp.json()["choices"][0]["message"]["content"]

issues = get_open_issues()
for issue in issues:
    reply = draft_reply(issue["body"] or "(no body)")
    print(f"Issue #{issue['number']}: {issue['title']}")
    print(f"Draft reply:\\n{reply}\\n---")
'''

sandbox.files.write("/workspace/agent.py", agent_code)
result = sandbox.exec("python /workspace/agent.py")
print(result.stdout)
```

```typescript
const agentCode = `

const GITHUB_TOKEN = process.env.GITHUB_TOKEN!;
const OPENAI_API_KEY = process.env.OPENAI_API_KEY!;
const REPO = 'your-org/your-repo';

async function getOpenIssues() {
  const res = await fetch(
    \`https://api.github.com/repos/\${REPO}/issues?state=open&per_page=5\`,
    { headers: { Authorization: \`Bearer \${GITHUB_TOKEN}\` } },
  );
  return res.json() as Promise<Array<{ number: number; title: string; body: string }>>;
}

async function draftReply(issueBody: string): Promise<string> {
  const res = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: \`Bearer \${OPENAI_API_KEY}\`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [
        { role: 'system', content: 'You are a helpful support agent. Draft a polite reply.' },
        { role: 'user', content: issueBody },
      ],
    }),
  });
  const data = await res.json() as { choices: Array<{ message: { content: string } }> };
  return data.choices[0].message.content;
}

const issues = await getOpenIssues();
for (const issue of issues) {
  const reply = await draftReply(issue.body || '(no body)');
  console.log(\`Issue #\${issue.number}: \${issue.title}\`);
  console.log(\`Draft reply:\\n\${reply}\\n---\`);
}
`;

await sandbox.files.write('/workspace/agent.ts', agentCode);
const result = await sandbox.exec('npx tsx /workspace/agent.ts');
console.log(result.stdout);
```

## Step 6  -  Watch the audit log in real time

Open a second process (or a second async task) to tail the audit log while the agent runs. You'll see every outbound call as it happens.

```python

def tail_audit():
    for event in sandbox.audit.tail():
        action = event.action
        host = event.host
        status = event.status_code
        transformed = ", ".join(event.request_transforms.get("secrets", {}).get("swapped", []))
        print(f"[audit] {action:8} {host} HTTP {status}  secrets={transformed or 'none'}")

t = threading.Thread(target=tail_audit, daemon=True)
t.start()

# Now run the agent
result = sandbox.exec("python /workspace/agent.py")
print(result.stdout)
```

```typescript
// Tail audit in the background
(async () => {
  for await (const event of sandbox.audit.tail()) {
    const swapped = event.requestTransforms?.secrets?.swapped?.join(', ') ?? 'none';
    console.log(`[audit] ${event.action.padEnd(8)} ${event.host} HTTP ${event.statusCode}  secrets=${swapped}`);
  }
})();

// Run the agent
const result = await sandbox.exec('npx tsx /workspace/agent.ts');
console.log(result.stdout);
```

Expected output while the agent runs:

```
[audit] allow    api.github.com   HTTP 200  secrets=none
[audit] allow    api.openai.com   HTTP 200  secrets=openai_key
[audit] allow    api.github.com   HTTP 200  secrets=none
[audit] allow    api.openai.com   HTTP 200  secrets=openai_key
```

The `secrets=openai_key` column confirms the proxy is swapping the placeholder with the real key on each OpenAI call.

## Step 7  -  Lock down the network

After observing what the agent actually calls, lock it to exactly those two hosts.

```python
sandbox.network.allow("api.openai.com")
sandbox.network.allow("api.github.com")
sandbox.network.lockdown()
print("Network locked. Only api.openai.com and api.github.com are reachable.")
```

```typescript
await sandbox.network.allow('api.openai.com');
await sandbox.network.allow('api.github.com');
await sandbox.network.lockdown();
console.log('Network locked. Only api.openai.com and api.github.com are reachable.');
```

```go
sandbox.Network.Allow(ctx, "api.openai.com", miosa.AllowOpts{})
sandbox.Network.Allow(ctx, "api.github.com", miosa.AllowOpts{})
sandbox.Network.Lockdown(ctx)
fmt.Println("Network locked.")
```

Run the agent again. It still works. Now try to reach anything else:

```bash
# Inside the sandbox after lockdown:
curl -s https://pypi.org/simple/requests/
# → blocked: 403 MIOSA-Egress-Deny
```

`pip install` and `npm install` reach package registries that won't be on your allowlist. Either pre-install everything into the template, or add `pypi.org`, `files.pythonhosted.org`, and `registry.npmjs.org` to the allowlist before locking down.

## Bonus  -  Rotate the OpenAI key while the agent is running

Rotate mid-run without restarting anything. The next request automatically uses the new key.

```python

# Start the agent in background
proc = sandbox.exec("python /workspace/agent.py", background=True)

# While it's running, rotate the key

time.sleep(2)   # let the agent make a few calls first

sandbox.secrets.rotate(
    name="openai_key",
    new_value="sk-proj-newrotatedkey...",
)
print("Key rotated. The agent's next OpenAI call will use the new key transparently.")

# Wait for the agent to finish
result = proc.wait()
print(result.stdout)
```

```typescript
// Start agent in background
const proc = await sandbox.exec('npx tsx /workspace/agent.ts', { background: true });

// Rotate the key after 2 seconds
await new Promise(r => setTimeout(r, 2000));
await sandbox.secrets.rotate({
  name: 'openai_key',
  newValue: 'sk-proj-newrotatedkey...',
});
console.log('Key rotated. Next call picks up the new value automatically.');

const result = await proc.wait();
console.log(result.stdout);
```

The agent does not restart. The placeholder token in `$OPENAI_API_KEY` doesn't change. The proxy simply starts looking up the new real value on the next request that carries the placeholder.

## What you learned

- `sandbox.secrets.set` keeps the real credential out of the VM entirely.
- OAuth Connect handles token refresh transparently  -  no retry logic needed in the agent.
- `sandbox.audit.tail()` gives a live stream of every outbound call with secret attribution.
- `sandbox.network.lockdown()` hardens the sandbox to exactly the hosts it needs.
- `sandbox.secrets.rotate()` updates the real value mid-run  -  the placeholder and the agent code are unaffected.

## Next


    Stamp external_user_id, scope credentials per user, and embed auditing in your own dashboard.


    Operational playbook: audit-only → review suggestions → lock down → handle pending requests.


    Full SDK reference for the secrets vault.

---

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

---

# Embed sandbox in an iframe

URL: https://miosa.ai/docs/cookbook/embed-sandbox-iframe
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/embed-sandbox-iframe
Source: src/routes/docs/cookbook/embed-sandbox-iframe/+page.md
Description: Your server mints a preview token; your frontend uses it as an iframe src. Covers React, Vue, Svelte, and vanilla JS, plus token TTL refresh.

# Embed sandbox in an iframe

~8 min Python TypeScript

> **Goal**: Embed a live MIOSA sandbox in your product's UI without exposing your `msk_*` key. Your server mints a short-lived preview token; your frontend drops it into an `<iframe src>`.
>
> **What you'll use**: Sandboxes, Preview tokens

## How preview tokens work

```
Browser ──── GET /my-api/preview-token ────► Your server
                                                │
                                          sbx.previewToken(3600)
                                                │
Your server ◄─── { url, expires_at } ──── MIOSA API
     │
     └── token embedded in https://<slug>.miosa.app?mp_...
```

The URL returned by `previewToken` is:

```
https://<sandbox-slug>.miosa.app?mp=<base64url-token>
```

It is safe to put in an iframe `src` attribute. It does not contain your API key. When the token expires the sandbox is still alive  -  you mint a new token and update the `src`.

## Step 1  -  Server-side: mint the token

Your backend verifies ownership, then calls `previewToken`. Return the URL to the frontend.

```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 session/JWT auth  -  returns {user_id, workspace_id}
    ...

@app.get("/api/sandboxes/{sandbox_id}/preview-token")
async def get_preview_token(sandbox_id: str, user=Depends(get_current_user)):
    # Ownership check  -  ensure this sandbox belongs to this user
    sbx = client.sandboxes.get(sandbox_id)
    if sbx.data.get("external_user_id") != user["user_id"]:
        raise HTTPException(403, "Forbidden")

    # Mint a 1-hour preview token
    token_info = sbx.preview_token(expires_in=3600)

    return {
        "url": token_info["url"],
        "expires_at": token_info["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 { userId } = (req as any).user;

  // Ownership check
  const sbx = await client.sandboxes.get(sandboxId);
  if (sbx.data.external_user_id !== userId) {
    res.status(403).json({ error: 'Forbidden' });
    return;
  }

  // Mint a 1-hour preview token
  const tokenInfo = await sbx.previewToken(3600);

  res.json({
    url: tokenInfo.url,
    expiresAt: tokenInfo.expires_at,
  });
});
```

Never return the raw `msk_*` key to the browser. The preview token URL is the only credential your frontend should ever receive, and it grants read-only access to exactly one sandbox for the duration of the TTL.

## Step 2  -  Frontend: embed the iframe

Fetch the token from your server and use the URL as the `src`. Set up a refresh timer to re-mint before expiry.

```tsx

interface SandboxEmbedProps {
  sandboxId: string;
  height?: number;
}

export function SandboxEmbed({ sandboxId, height = 600 }: SandboxEmbedProps) {
  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
  const refreshTimerRef = useRef<ReturnType<typeof setTimeout>>();

  async function fetchToken() {
    const res = await fetch(`/api/sandboxes/${sandboxId}/preview-token`);
    const { url, expiresAt } = await res.json();

    setPreviewUrl(url);

    // Re-mint 60 seconds before expiry
    const ttlMs = new Date(expiresAt).getTime() - Date.now() - 60_000;
    clearTimeout(refreshTimerRef.current);
    refreshTimerRef.current = setTimeout(fetchToken, Math.max(ttlMs, 5_000));
  }

  useEffect(() => {
    fetchToken();
    return () => clearTimeout(refreshTimerRef.current);
  }, [sandboxId]);

  if (!previewUrl) {
    return <div style={{ height, background: '#111', borderRadius: 8 }}>Loading…</div>;
  }

  return (
    <iframe
      src={previewUrl}
      width="100%"
      height={height}
      style={{ border: 'none', borderRadius: 8 }}
      sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
      title={`Sandbox ${sandboxId}`}
    />
  );
}
```

```vue

<template>
  <div :style="{ height: `${height}px` }">
    <div v-if="!previewUrl" :style="{ height: '100%', background: '#111', borderRadius: '8px' }">
      Loading…
    </div>
    <iframe
      v-else
      :src="previewUrl"
      width="100%"
      :height="height"
      style="border: none; border-radius: 8px"
      sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
      :title="`Sandbox ${sandboxId}`"
    />
  </div>
</template>
```

```svelte

{#if previewUrl}
  <iframe
    src={previewUrl}
    width="100%"
    {height}
    style="border: none; border-radius: 8px"
    sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
    title="Sandbox {sandboxId}"
  />
{:else}
  <div style="height: {height}px; background: #111; border-radius: 8px">Loading…</div>
{/if}
```

```html
<!doctype html>
<html>
  <body>
    <div id="sandbox-container" style="height:600px"></div>

  </body>
</html>
```

## Token refresh strategy

| Scenario | Recommendation |
|---|---|
| Short session (under 1 h) | Mint once with `expires_in=3600`. No refresh needed. |
| Long session | Mint with `expires_in=3600`, schedule refresh 60 s before expiry (shown above). |
| Tab inactive | Pause the refresh timer using `visibilitychange`. Mint fresh when the tab comes back. |
| Token already expired | Fetch a new token  -  the old one is silently rejected by the iframe, not a hard error. |

## CSP considerations

If your product sets a `Content-Security-Policy`, add the MIOSA preview domain to `frame-src`:

```http
Content-Security-Policy: frame-src https://*.miosa.app;
```

If you use a custom white-label preview domain (configured via `client.customDomains.create`), add that domain instead.

## Related


    The full lifecycle that produces the sandbox you're embedding.


    Tag sandboxes to tenants, issue browser tokens, query per-tenant usage.


    Token format, scopes, revocation, and CSP embedding configuration.

---

# Lockdown workflow  -  audit to enforce

URL: https://miosa.ai/docs/cookbook/lockdown-workflow
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/lockdown-workflow
Source: src/routes/docs/cookbook/lockdown-workflow/+page.md
Description: Operational playbook for moving a sandbox from audit-only to locked-down network policy. Start safe, review suggestions, lock down, handle pending requests, roll back if needed.

# Lockdown workflow

~10 min Python TypeScript

> **Goal**: Move a sandbox from audit-only (observe everything, block nothing) to enforce mode (block everything not on the allowlist) safely. This playbook walks every step, from "let it run for a few days" through "lock down" through "handle something unexpected."
>
> **What you'll use**: Network Allowlist, Audit Log

## The four phases

```
Phase 1  -  Observe      sandbox runs, everything logged, nothing blocked
Phase 2  -  Review       inspect traffic suggestions from the MIOSA Network tab
Phase 3  -  Lock down    apply the allowlist, switch to enforce mode
Phase 4  -  Operate      handle pending requests, roll back if needed
```

## Phase 1  -  Observe

Every new sandbox starts in audit-only mode. You don't need to do anything  -  just use the sandbox normally.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Create a sandbox. Audit-only is the default.
sandbox = client.sandboxes.create(template="python-ds")

# Verify the mode
policy = sandbox.network.get_policy()
print(policy.mode)   # → "observe"
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const sandbox = await client.sandboxes.create({ template: 'python-ds' });

const policy = await sandbox.network.getPolicy();
console.log(policy.mode);   // → "observe"
```

Let the sandbox run for at least a few days. The longer you observe, the more complete your allowlist will be. Seven days is a good baseline for a regularly-running sandbox.

MIOSA's Network tab shows traffic from the last 7 days by default. You can query longer windows via the SDK (e.g., `since="30d"`). Longer windows catch infrequent calls like weekly cron jobs.

## Phase 2  -  Review suggestions

After the observation window, pull the list of hosts MIOSA suggests based on actual traffic.

```python
# Get all hosts the sandbox contacted in the last 7 days
suggestions = sandbox.network.suggestions(since="7d")

print(f"{'HOST':<45} {'REQUESTS':>10}  {'LAST SEEN'}")
print("-" * 70)
for h in sorted(suggestions, key=lambda x: x.request_count, reverse=True):
    print(f"{h.host:<45} {h.request_count:>10}  {h.last_seen}")
```

Example output:

```
HOST                                          REQUESTS  LAST SEEN
api.openai.com                                    1247  2 minutes ago
api.github.com                                    1053  5 minutes ago
github.com                                         412  1 hour ago
pypi.org                                            29  3 days ago
files.pythonhosted.org                             161  3 days ago
pythonhosted.org                                    44  3 days ago
```

```typescript
const suggestions = await sandbox.network.suggestions({ since: '7d' });

console.log('HOST'.padEnd(45), 'REQUESTS'.padStart(10), ' LAST SEEN');
console.log('-'.repeat(70));
for (const h of suggestions.sort((a, b) => b.requestCount - a.requestCount)) {
  console.log(h.host.padEnd(45), String(h.requestCount).padStart(10), '', h.lastSeen);
}
```

### What to keep, what to question

| Pattern | Decision |
|---|---|
| `api.openai.com`, `api.github.com`  -  high frequency, expected | Keep |
| `pypi.org`, `files.pythonhosted.org`, `pythonhosted.org`  -  if sandbox installs packages | Keep |
| `registry.npmjs.org`  -  if sandbox installs npm packages | Keep |
| `fonts.gstatic.com`, `cdn.jsdelivr.net`  -  only if the sandbox serves a browser app | Keep if needed |
| `169.254.169.254`  -  AWS metadata endpoint | **Deny explicitly** |
| `ifconfig.me`, `ipinfo.io`  -  IP-lookup services | Usually deny |
| Unknown third-party domains | Investigate before allowing |

## Phase 3  -  Lock down

Apply the allowlist and switch to enforce mode.

```python
# Step 3a  -  add each host you want to allow
hosts_to_allow = [
    "api.openai.com",
    "api.github.com",
    "github.com",
    "pypi.org",
    "files.pythonhosted.org",
    "pythonhosted.org",
]

for host in hosts_to_allow:
    sandbox.network.allow(host)
    print(f"Allowed: {host}")

# Step 3b  -  explicitly deny anything you want blocked even if traffic is observed
sandbox.network.deny("169.254.169.254")   # block metadata endpoint

# Step 3c  -  switch to enforce mode
sandbox.network.lockdown()
print("Sandbox is now in enforce mode.")
```

```typescript
const hostsToAllow = [
  'api.openai.com',
  'api.github.com',
  'github.com',
  'pypi.org',
  'files.pythonhosted.org',
  'pythonhosted.org',
];

for (const host of hostsToAllow) {
  await sandbox.network.allow(host);
  console.log('Allowed:', host);
}

await sandbox.network.deny('169.254.169.254');

await sandbox.network.lockdown();
console.log('Sandbox is now in enforce mode.');
```

### Verify enforce mode is active

```python
policy = sandbox.network.get_policy()
print(policy.mode)          # → "enforce"
print(policy.allow_rules)   # list of allowed hosts
print(policy.deny_rules)    # list of explicit denies
```

### Test the boundary

```python
# This should succeed
r = sandbox.exec("curl -s -o /dev/null -w '%{http_code}' https://api.openai.com/")
print("OpenAI reachable:", r.stdout)   # → 401 (auth error is fine  -  proves egress works)

# This should be blocked
r = sandbox.exec("curl -s -o /dev/null -w '%{http_code}' https://pypi.org/simple/numpy/ --max-time 5")
print("pypi.org:", r.stdout)   # wait  -  pypi.org IS on our list, this should succeed
# If you're testing a host NOT on the list:
r = sandbox.exec("curl -s -o /dev/null -w '%{http_code}' https://example.com/ --max-time 5")
print("example.com (should be blocked):", r.stdout)   # → 000 (connection refused by proxy)
```

Run a full smoke test of your sandbox's normal workflow immediately after locking down. The most common surprise is a dependency that phones home to a domain you didn't expect.

## Phase 4  -  Operate

### Handling pending requests

When enforce mode is on, any request to a host not on the allowlist is blocked **and** added to the Pending Requests queue. You don't lose visibility  -  you see exactly what was blocked and why.

```python
# List all pending (blocked) requests since lockdown
pending = sandbox.network.pending()
for p in pending:
    print(f"{p.host:<45} {p.request_count:>5} blocked  first_seen={p.first_seen}")

# Allow a host from the pending list
sandbox.network.allow("fonts.gstatic.com")
print("Added fonts.gstatic.com  -  future requests will pass.")
```

```typescript
const pending = await sandbox.network.pending();
for (const p of pending) {
  console.log(p.host.padEnd(45), String(p.requestCount).padStart(5), 'blocked');
}

// Allow one of the pending hosts
await sandbox.network.allow('fonts.gstatic.com');
console.log('Added fonts.gstatic.com.');
```

### Warn-only rules for trial hosts

If you want to allow a host temporarily but flag it in the audit log:

```python
sandbox.network.allow("api.experimental.example.com", warn_only=True)
```

The request passes in enforce mode, but appears in the audit log with `action=warn`. Good for trialling a new integration before committing to it permanently.

### Rolling back

If something breaks and you need to unblock immediately:

```python
# Revert to audit-only. The allowlist is preserved  -  you can re-lock later.
sandbox.network.observe()
print("Back to audit-only. Nothing is blocked.")
```

```typescript
await sandbox.network.observe();
console.log('Back to audit-only. Nothing is blocked.');
```

Calling `observe()` does not delete your allowlist rules. When you call `lockdown()` again, they'll all still be there. You can roll back and re-lock as many times as you need.

### Exporting the policy for reuse

To apply the same policy to a new sandbox:

```python
# Export policy from the locked sandbox
policy = sandbox.network.get_policy()

# Apply to a new sandbox
new_sandbox = client.sandboxes.create(template="python-ds")
for rule in policy.allow_rules:
    new_sandbox.network.allow(rule.host, methods=rule.methods)
for rule in policy.deny_rules:
    new_sandbox.network.deny(rule.host)
new_sandbox.network.lockdown()
print(f"Policy cloned to {new_sandbox.id}.")
```

## Full script

```python
#!/usr/bin/env python3
"""lockdown_workflow.py  -  end-to-end lockdown playbook"""

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
sandbox = client.sandboxes.create(template="python-ds")
print(f"Sandbox {sandbox.id}  -  mode: {sandbox.network.get_policy().mode}")

# --- Phase 1: observe for a while ---
print("Observing for 10 seconds (use 7d in production)...")
time.sleep(10)

# --- Phase 2: review ---
suggestions = sandbox.network.suggestions(since="1h")
print(f"\n{len(suggestions)} host(s) contacted:")
for h in suggestions:
    print(f"  {h.host}  ({h.request_count} requests)")

# --- Phase 3: lock down ---
for h in suggestions:
    sandbox.network.allow(h.host)
sandbox.network.lockdown()
print(f"\nLocked. Mode: {sandbox.network.get_policy().mode}")

# --- Phase 4: handle pending ---

pending = sandbox.network.pending()
if pending:
    print(f"\n{len(pending)} pending request(s) since lockdown:")
    for p in pending:
        print(f"  {p.host}  ({p.request_count} blocked)")
else:
    print("\nNo pending requests.")
```

```typescript
// lockdown-workflow.ts

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const sandbox = await client.sandboxes.create({ template: 'python-ds' });
const initial = await sandbox.network.getPolicy();
console.log(`Sandbox ${sandbox.id}  -  mode: ${initial.mode}`);

// Phase 1: observe
console.log('Observing for 10 s (use 7d in production)...');
await new Promise(r => setTimeout(r, 10_000));

// Phase 2: review
const suggestions = await sandbox.network.suggestions({ since: '1h' });
console.log(`\n${suggestions.length} host(s) contacted:`);
for (const h of suggestions) {
  console.log(`  ${h.host}  (${h.requestCount} requests)`);
}

// Phase 3: lock down
for (const h of suggestions) {
  await sandbox.network.allow(h.host);
}
await sandbox.network.lockdown();
const locked = await sandbox.network.getPolicy();
console.log(`\nLocked. Mode: ${locked.mode}`);

// Phase 4: handle pending
await new Promise(r => setTimeout(r, 2000));
const pending = await sandbox.network.pending();
if (pending.length > 0) {
  console.log(`\n${pending.length} pending request(s) since lockdown:`);
  for (const p of pending) {
    console.log(`  ${p.host}  (${p.requestCount} blocked)`);
  }
} else {
  console.log('\nNo pending requests.');
}
```

## Troubleshooting

**Sandbox can't reach `pypi.org` after lockdown.**
You need three rules for pip: `pypi.org`, `files.pythonhosted.org`, and `pythonhosted.org`. All three must be on the allowlist. Check the pending queue  -  the missing ones will appear there the first time pip tries to connect.

**Agent stopped working and I can't figure out what's blocked.**
Use `sandbox.network.pending()` or filter the audit log by `action=reject`. Each blocked row has a `rejected_by` field naming the rule that triggered.

**I locked down a template sandbox and now all new sandboxes forked from it are also locked.**
Policy is inherited from the template at creation time. If you want new sandboxes to start in audit-only, call `new_sandbox.network.observe()` immediately after creation.

**I want the same policy on 50 sandboxes.**
Export the policy from a reference sandbox and apply it in a loop (see "Exporting the policy for reuse" above), or set it at the tenant level so it applies to all resources by default.

## What you learned

- Sandboxes always start in audit-only  -  no accidental lock-outs.
- `suggestions(since="7d")` gives you a data-driven starting point for the allowlist.
- `lockdown()` is reversible: `observe()` reverts instantly without losing the allowlist.
- Blocked requests appear in the Pending queue  -  nothing is silently lost.

## Next


    Pair lockdown with vault-managed credentials for a fully hardened sandbox.


    Full SDK reference for allow, deny, lockdown, observe, and pending.


    Top 15 issues and fixes across all security features.

---

# 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,
  };
}
```

## Step 7  -  Set per-user quotas

Cap each user so they cannot exhaust your MIOSA allocation. Quotas take effect immediately.

```python
# Free-tier: max 3 sandboxes, 1 concurrent, $5 credit cap
client.quotas.set(
    "jane-doe",
    max_sandboxes=3,
    max_concurrent=1,
    max_credit_cents=500,
)

# Pro-tier: higher limits
client.quotas.set(
    "jane-doe",
    max_sandboxes=20,
    max_concurrent=5,
    max_credit_cents=5000,
)
```

```typescript
// Quotas API via REST (SDK method landing in a future release):
await fetch(`https://api.miosa.ai/api/v1/quotas/external/jane-doe`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.MIOSA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ max_sandboxes: 3, max_concurrent: 1, max_credit_cents: 500 }),
});
```

## Step 8  -  Audit log

Pull a paginated audit log to meet compliance requirements or investigate support tickets.

```python
# List recent sandbox create/destroy events
events = client.audit_log.list(
    resource_type="sandbox",
    limit=50,
)

for event in events:
    print(f"  {event.get('inserted_at')}  {event.get('action')}  {event.get('resource_id')}")
```

```typescript
const events = await client.auditLog.list({
  resource_type: 'sandbox',
  limit: 50,
});

for (const event of events) {
  console.log(`  ${event.inserted_at}  ${event.action}  ${event.resource_id}`);
}
```

## What you learned

- Three external ID fields (`external_workspace_id`, `external_user_id`, `external_project_id`) group every MIOSA resource by your own identifiers with no 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.
- `client.quotas.set` caps end-users before they exhaust your allocation  -  call it on plan changes, not on every request.
- `client.auditLog.list` gives you a paginated event history for compliance and support.

## Next


    Full walkthrough of caps, monthly invoice rollups, and Stripe integration.


    React, Vue, Svelte, and vanilla JS iframe embed with token TTL refresh.


    Webhooks and SSE stream for sandbox lifecycle notifications.

---

# Per-user quotas and billing

URL: https://miosa.ai/docs/cookbook/per-user-quotas-billing
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/per-user-quotas-billing
Source: src/routes/docs/cookbook/per-user-quotas-billing/+page.md
Description: Set per-end-user resource caps, pull monthly usage rollups keyed by external_user_id, and generate invoices for your customers.

# Per-user quotas and billing

~10 min Python TypeScript

> **Goal**: Cap each of your end-users so they cannot exhaust your MIOSA allocation, then pull a monthly usage rollup per user to generate accurate invoices.
>
> **What you'll use**: Sandboxes (external attribution), Quotas API, Usage API

## Overview

Every sandbox created with an `external_user_id` is automatically attributed. Two APIs build on top of that:

- **Quotas**  -  hard caps per `external_user_id`: max sandboxes, max concurrent, max credits.
- **Usage**  -  period-based metering rollup queryable by `computer_id`, filterable and paginated.

```
Your platform
  │
  ├─ Create sandbox ──── external_user_id="user-42" ──► MIOSA
  │
  ├─ Set quota ────────── max_sandboxes=5 ──────────► MIOSA
  │
  └─ Invoice run ──────── usage.report(period_start, period_end) ──► billing system
```

## Step 1  -  Attribute every sandbox to an end-user

Pass `external_user_id` on every create. MIOSA propagates it to every usage record and audit event automatically.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def create_user_sandbox(user_id: str, template: str = "miosa-sandbox"):
    sbx = client.sandboxes.create(
        template_id=template,
        timeout_sec=3600,
        external_user_id=user_id,
        external_workspace_id="acme-corp",   # optional  -  your tenant ID
    )
    return sbx

sbx = create_user_sandbox("user-42")
print(f"Sandbox {sbx.id} attributed to user-42")
```

```typescript

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

async function createUserSandbox(userId: string, template = 'miosa-sandbox') {
  const sbx = await client.sandboxes.create({
    templateId: template,
    timeoutSec: 3600,
    externalUserId: userId,
    externalWorkspaceId: 'acme-corp',
  });
  return sbx;
}

const sbx = await createUserSandbox('user-42');
console.log(`Sandbox ${sbx.id} attributed to user-42`);
```

## Step 2  -  Set per-user quotas

Call `client.quotas.set` once during onboarding (or whenever a user upgrades their plan). Limits take effect immediately for all subsequent sandbox creates.

```python
# Apply limits for a free-tier user
client.quotas.set(
    "user-42",
    max_sandboxes=3,       # total sandboxes this user can own
    max_concurrent=1,      # sandboxes in "running" state at once
    max_credit_cents=500,  # $5.00 cap per billing period
)

# Upgrade to a pro-tier user
client.quotas.set(
    "user-42",
    max_sandboxes=20,
    max_concurrent=5,
    max_credit_cents=5000,
)

# Remove limits (revert to tenant default)
client.quotas.delete("user-42")
```

```typescript
// Quotas are Python-first in the current SDK  -  use the raw API:
// POST /api/v1/quotas/external/{external_user_id}
// with body: { max_sandboxes, max_concurrent, max_credit_cents }

// For Python-first access (recommended):
// client.quotas.set("user-42", { max_sandboxes: 3, max_concurrent: 1 })

// TypeScript workaround until the SDK ships quotas.set():
async function setQuota(
  userId: string,
  limits: { max_sandboxes?: number; max_concurrent?: number; max_credit_cents?: number },
) {
  const res = await fetch(
    `https://api.miosa.ai/api/v1/quotas/external/${encodeURIComponent(userId)}`,
    {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${process.env.MIOSA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(limits),
    },
  );
  return res.json();
}

await setQuota('user-42', { max_sandboxes: 3, max_concurrent: 1, max_credit_cents: 500 });
```

`max_credit_cents` is enforced as a soft cap  -  the API rejects new sandbox creates once the user has consumed this amount in the current billing period. It does not kill running sandboxes mid-session.

## Step 3  -  Check current quota state

Before creating a sandbox on behalf of a user, check whether they have headroom. This lets you surface a friendly upgrade prompt rather than a raw API error.

```python
def check_quota(user_id: str) -> dict:
    quota = client.quotas.get(user_id)
    usage = quota.get("usage", {})

    current = usage.get("sandbox_count", 0)
    limit = quota.get("max_sandboxes") or float("inf")

    return {
        "can_create": current < limit,
        "sandbox_count": current,
        "max_sandboxes": quota.get("max_sandboxes"),
        "max_concurrent": quota.get("max_concurrent"),
        "max_credit_cents": quota.get("max_credit_cents"),
        "credit_cents_used": usage.get("credit_cents", 0),
    }

state = check_quota("user-42")
if not state["can_create"]:
    print(f"user-42 is at their sandbox limit ({state['max_sandboxes']}). Show upgrade prompt.")
else:
    sbx = create_user_sandbox("user-42")
```

```typescript
async function checkQuota(userId: string) {
  const res = await fetch(
    `https://api.miosa.ai/api/v1/quotas/external/${encodeURIComponent(userId)}`,
    {
      headers: { Authorization: `Bearer ${process.env.MIOSA_API_KEY}` },
    },
  );
  const quota = await res.json();
  const usage = quota.usage ?? {};
  const current = usage.sandbox_count ?? 0;
  const limit = quota.max_sandboxes ?? Infinity;

  return {
    canCreate: current < limit,
    sandboxCount: current,
    maxSandboxes: quota.max_sandboxes,
    creditCentsUsed: usage.credit_cents ?? 0,
    maxCreditCents: quota.max_credit_cents,
  };
}

const state = await checkQuota('user-42');
if (!state.canCreate) {
  console.log(`user-42 is at their sandbox limit. Show upgrade prompt.`);
} else {
  const sbx = await createUserSandbox('user-42');
}
```

## Step 4  -  Monthly invoice rollup

At the end of each billing period, pull a usage report. The response gives you the data you need to generate per-user line items.

```python
from datetime import date, timedelta

def get_monthly_usage_per_user(year: int, month: int) -> list[dict]:
    """Returns a list of {external_user_id, total_credits, ...} rows."""
    # Build period bounds
    period_start = date(year, month, 1).isoformat()
    if month == 12:
        period_end = date(year + 1, 1, 1).isoformat()
    else:
        period_end = date(year, month + 1, 1).isoformat()

    # report() returns a summary; sessions() gives per-sandbox detail
    sessions = client.usage.sessions()  # paginate if needed

    # Group by external_user_id manually (SDK-level grouping landing in next release)
    from collections import defaultdict
    by_user = defaultdict(float)
    for session in sessions:
        uid = session.get("external_user_id")
        if uid:
            by_user[uid] += session.get("credits_used", 0) or 0

    return [{"external_user_id": uid, "credits": credits} for uid, credits in by_user.items()]

# May 2026 invoice run
rows = get_monthly_usage_per_user(2026, 5)
for row in rows:
    print(f"  user={row['external_user_id']}  credits={row['credits']:.4f}")
```

```typescript
async function getMonthlyUsagePerUser(year: number, month: number) {
  const periodStart = new Date(year, month - 1, 1).toISOString().split('T')[0];
  const periodEnd = new Date(year, month, 1).toISOString().split('T')[0];

  const sessions = await client.usage.sessions({ limit: 1000 });

  // Group by external_user_id
  const byUser = new Map<string, number>();
  for (const session of sessions) {
    const uid = String((session as any).external_user_id ?? '');
    if (uid) {
      byUser.set(uid, (byUser.get(uid) ?? 0) + Number((session as any).credits_used ?? 0));
    }
  }

  return Array.from(byUser.entries()).map(([userId, credits]) => ({ userId, credits }));
}

// May 2026 invoice run
const rows = await getMonthlyUsagePerUser(2026, 5);
for (const row of rows) {
  console.log(`  user=${row.userId}  credits=${row.credits.toFixed(4)}`);
}
```

## Connecting to Stripe (optional)

Once you have the per-user credit totals, map them to money and charge via Stripe:

```python

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

CREDIT_TO_USD = 0.001  # $0.001 per credit  -  adjust to your pricing

def bill_user(stripe_customer_id: str, credits: float, period: str):
    """Create a Stripe invoice item and finalize."""
    amount_cents = int(credits * CREDIT_TO_USD * 100)
    if amount_cents < 50:
        return  # below Stripe minimum  -  carry over to next period

    stripe.InvoiceItem.create(
        customer=stripe_customer_id,
        amount=amount_cents,
        currency="usd",
        description=f"MIOSA sandbox usage  -  {period} ({credits:.2f} credits)",
    )
    invoice = stripe.Invoice.create(customer=stripe_customer_id, auto_advance=True)
    stripe.Invoice.finalize_invoice(invoice.id)
    print(f"Invoice {invoice.id} sent to {stripe_customer_id}")
```

```typescript

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const CREDIT_TO_USD = 0.001; // $0.001 per credit

async function billUser(stripeCustomerId: string, credits: number, period: string) {
  const amountCents = Math.round(credits * CREDIT_TO_USD * 100);
  if (amountCents < 50) return; // below Stripe minimum

  await stripe.invoiceItems.create({
    customer: stripeCustomerId,
    amount: amountCents,
    currency: 'usd',
    description: `MIOSA sandbox usage  -  ${period} (${credits.toFixed(2)} credits)`,
  });

  const invoice = await stripe.invoices.create({ customer: stripeCustomerId, auto_advance: true });
  await stripe.invoices.finalizeInvoice(invoice.id!);
  console.log(`Invoice ${invoice.id} sent to ${stripeCustomerId}`);
}
```

## What you learned

- Every sandbox created with `external_user_id` is attributable  -  no extra tagging step required after create.
- `client.quotas.set(user_id, {...})` enforces hard caps per user. Call it on plan changes, not on every request.
- `client.quotas.get(user_id)` returns both the limits and current usage in a single call  -  use it for proactive upgrade prompts.
- `client.usage.sessions()` gives you the raw per-session metering rows you need to build an invoice rollup.
- Connecting to Stripe is a thin adapter layer  -  MIOSA gives you the credits; you decide the USD rate.

## Related


    Full walkthrough of tagging, filtering, browser tokens, and per-tenant usage in a SaaS context.


    Listen for sandbox lifecycle events to trigger billing actions (e.g., credit deduction on destroy).


    Full parameter reference and enforcement semantics for the Quotas API.

---

# Sandbox events in real time

URL: https://miosa.ai/docs/cookbook/sandbox-events-realtime
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/sandbox-events-realtime
Source: src/routes/docs/cookbook/sandbox-events-realtime/+page.md
Description: React to sandbox lifecycle events using either HMAC-signed webhooks (server-to-server) or the SSE event stream (in-process). Covers both patterns, idempotency, and when to choose each.

# Sandbox events in real time

~10 min Python TypeScript

> **Goal**: React to sandbox lifecycle events  -  `sandbox.running`, `sandbox.destroyed`, `deployment.live`, and others  -  using either webhooks (durable, server-to-server) or the SSE stream (ephemeral, in-process).
>
> **What you'll use**: Webhooks, Tenant SSE event stream

## Two patterns  -  choose one

| | Webhooks | SSE stream |
|---|---|---|
| Delivery | MIOSA calls your URL | Your process pulls |
| Durability | Retried on failure | Lost if process dies |
| Auth | HMAC-SHA256 signature | Your `msk_*` key |
| Latency | ~100ms | ~50ms |
| Best for | Background jobs, billing triggers, Slack alerts | Dashboard UIs, dev-time debugging |

Both patterns carry the same event payloads. You can use both simultaneously  -  webhooks for the durable server-side reaction, SSE for the live frontend widget.

## Pattern A  -  Webhooks

### Register a webhook endpoint

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

hook = client.webhooks.create(
    url="https://api.acme.com/webhooks/miosa",
    events=[
        "sandbox.running",
        "sandbox.destroyed",
        "sandbox.error",
        "deployment.live",
        "deployment.failed",
    ],
    description="Acme sandbox lifecycle",
)

# IMPORTANT: save hook["secret"] immediately  -  it is shown only once
print(f"Webhook ID: {hook['id']}")
print(f"Secret (save this): {hook.get('secret')}")
```

```typescript

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

const hook = await client.webhooks.create({
  url: 'https://api.acme.com/webhooks/miosa',
  events: [
    'sandbox.running',
    'sandbox.destroyed',
    'sandbox.error',
    'deployment.live',
    'deployment.failed',
  ],
  description: 'Acme sandbox lifecycle',
});

// IMPORTANT: save hook.secret immediately  -  shown only once
console.log('Webhook ID:', hook.id);
console.log('Secret (save this):', (hook as any).secret);
```

### Verify the signature

Every delivery includes a `Miosa-Signature` header: `t=<unix-timestamp>,v1=<hex-digest>`. The signed payload is `<timestamp>.<raw-body>`.

```python

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = os.environ["MIOSA_WEBHOOK_SECRET"]

def verify_signature(body: bytes, header: str, secret: str) -> bool:
    """Return True if the signature is valid and not a replay."""
    parts = dict(item.split("=", 1) for item in header.split(","))
    ts = parts.get("t", "")
    sig = parts.get("v1", "")

    # Replay guard: reject events older than 5 minutes
    if abs(time.time() - int(ts)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{ts}.{body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, sig)

@app.post("/webhooks/miosa")
async def receive_webhook(request: Request):
    body = await request.body()
    header = request.headers.get("Miosa-Signature", "")

    if not verify_signature(body, header, WEBHOOK_SECRET):
        raise HTTPException(400, "Invalid signature")

    event = json.loads(body)
    event_type = event.get("type")

    # Idempotency: check event["id"] against your DB before processing
    event_id = event.get("id")

    if event_type == "sandbox.running":
        sandbox_id = event.get("data", {}).get("id")
        print(f"Sandbox {sandbox_id} is running  -  start your downstream job")

    elif event_type == "sandbox.destroyed":
        sandbox_id = event.get("data", {}).get("id")
        print(f"Sandbox {sandbox_id} destroyed  -  record billing event")

    elif event_type == "deployment.live":
        url = event.get("data", {}).get("url")
        print(f"Deployment live at {url}  -  notify user")

    # Always return 200 quickly; do heavy work asynchronously
    return {"ok": True}
```

```typescript

const app = express();
app.use(express.raw({ type: 'application/json' })); // raw body for signature check

const WEBHOOK_SECRET = process.env.MIOSA_WEBHOOK_SECRET!;

function verifySignature(body: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const { t: ts, v1: sig } = parts;
  if (!ts || !sig) return false;

  // Replay guard: reject events older than 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${ts}.${body.toString()}`)
    .digest('hex');

  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
}

app.post('/webhooks/miosa', (req, res) => {
  const body = req.body as Buffer;
  const header = req.headers['miosa-signature'] as string ?? '';

  if (!verifySignature(body, header, WEBHOOK_SECRET)) {
    res.status(400).json({ error: 'Invalid signature' });
    return;
  }

  const event = JSON.parse(body.toString());
  const { type: eventType, id: eventId, data } = event;

  // Idempotency: check eventId against your DB before processing

  switch (eventType) {
    case 'sandbox.running':
      console.log(`Sandbox ${data?.id} is running  -  start downstream job`);
      break;
    case 'sandbox.destroyed':
      console.log(`Sandbox ${data?.id} destroyed  -  record billing event`);
      break;
    case 'deployment.live':
      console.log(`Deployment live at ${data?.url}  -  notify user`);
      break;
  }

  // Always return 200 quickly
  res.json({ ok: true });
});
```

### Idempotency

MIOSA retries webhook delivery on failure (5xx, timeout). Your handler must be idempotent. The simplest approach is to persist `event.id` in a seen-events table before processing:

```python

conn = sqlite3.connect("/var/lib/acme/events.db")
conn.execute(
    "CREATE TABLE IF NOT EXISTS seen_events (event_id TEXT PRIMARY KEY)"
)

def process_event(event: dict):
    event_id = event["id"]
    try:
        conn.execute("INSERT INTO seen_events VALUES (?)", (event_id,))
        conn.commit()
    except sqlite3.IntegrityError:
        # Already processed  -  skip
        return

    # Safe to process now
    handle_event(event)
```

```typescript
const seenEvents = new Set<string>(); // use Redis or a DB table in production

function processEvent(event: Record<string, unknown>) {
  const eventId = String(event.id ?? '');
  if (seenEvents.has(eventId)) return; // already processed
  seenEvents.add(eventId);

  handleEvent(event);
}
```

## Pattern B  -  SSE event stream

Use the tenant SSE stream for in-process listeners  -  dashboard backends, dev-time monitoring, or any scenario where you want to react inside your running process rather than receive callbacks.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# Stream all tenant-scoped events  -  runs until cancelled
for event in client.events.stream():
    event_type = event.get("type", "")

    if event_type == "sandbox.running":
        print(f"[running]   {event['data']['id']}")
    elif event_type == "sandbox.destroyed":
        print(f"[destroyed] {event['data']['id']}")
    elif event_type == "sandbox.error":
        print(f"[error]     {event['data']['id']}  -  {event['data'].get('error')}")
    elif event_type.startswith("deployment."):
        print(f"[deploy]    {event_type}  -  {event.get('data', {}).get('url', '')}")
```

```typescript

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

// Stream all tenant-scoped events
// (TenantEvents is available as a standalone resource)
const eventStream = new TenantEvents((client as any).http);

for await (const event of eventStream.stream()) {
  const type = event.type ?? '';

  if (type === 'sandbox.running') {
    console.log(`[running]   ${(event as any).data?.id}`);
  } else if (type === 'sandbox.destroyed') {
    console.log(`[destroyed] ${(event as any).data?.id}`);
  } else if (type === 'sandbox.error') {
    console.log(`[error]     ${(event as any).data?.id}  -  ${(event as any).data?.error}`);
  } else if (type.startsWith('deployment.')) {
    console.log(`[deploy]    ${type}  -  ${(event as any).data?.url ?? ''}`);
  }
}
```

### Filter by event type

The stream accepts a `types` filter to reduce noise:

```python
# Receive only deployment events
for event in client.events.stream(types=["deployment.live", "deployment.failed"]):
    print(event)
```

```typescript
for await (const event of eventStream.stream(['deployment.live', 'deployment.failed'])) {
  console.log(event);
}
```

## Event catalog

| Event type | Trigger |
|---|---|
| `sandbox.running` | Sandbox finished booting |
| `sandbox.paused` | Sandbox suspended (idle timeout or manual pause) |
| `sandbox.destroyed` | Sandbox deleted |
| `sandbox.error` | Unrecoverable sandbox failure |
| `sandbox.snapshot.ready` | Snapshot upload completed |
| `sandbox.share.created` | Preview share token minted |
| `sandbox.share.revoked` | Preview share token revoked |
| `deployment.live` | Deployment promoted to live |
| `deployment.failed` | Deployment build or promotion failed |

## Choosing between patterns

Use **webhooks** when:

- You need durability (your process may restart)
- You're triggering background jobs, billing events, or Slack notifications
- You want MIOSA to push rather than your process to pull

Use the **SSE stream** when:

- You're building a live dashboard widget
- You're writing a short-lived script or dev tool
- You want the simplest possible integration with no webhook endpoint to deploy

## Related


    Use events to update your UI as the agent builds and deploys.


    Trigger billing actions on sandbox.destroyed events.


    Full event catalog, delivery semantics, retry policy, and signature spec.

---

# 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` | VM 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.

## Fork a running sandbox

`sandbox.fork()` creates a copy-on-write clone of a **running** sandbox  -  no snapshot creation step, no polling. The original keeps running unchanged.

```python
# Fork the live sandbox into a branch for a risky experiment
branch = sbx.fork(name="branch-experiment-x")
print(f"Branch: {branch.id}")

# Run the experiment only in the branch
branch.files.write("/workspace/experiment.py", "print('experimental path')")
result = branch.exec("python3 /workspace/experiment.py")
print(result.stdout)

# Discard the branch  -  original is untouched
branch.delete()
```

```typescript
// Fork the live sandbox
const branch = await sbx.fork({ name: 'branch-experiment-x' });
console.log('Branch:', branch.id);

// Run the experiment only in the branch
await branch.files.write('/workspace/experiment.py', "print('experimental path')");
const result = await branch.exec('python3 /workspace/experiment.py');
console.log(result.stdout);

// Discard the branch  -  original is untouched
await branch.delete();
```

**When to use `fork` vs `snapshots.restore`:**

| | `fork()` | `snapshots.restore(snap_id)` |
|---|---|---|
| Source | Running sandbox (live state) | Completed snapshot (stored state) |
| Speed | Instant | Requires snapshot to be `ready` first |
| Use case | Branching during an active session | Restoring from a checkpoint days later |
| Original affected? | No | No |

## What you learned

- `sbx.snapshots.create(comment)` captures state without stopping the sandbox. The sandbox keeps running while the snapshot uploads.
- `sbx.snapshots.restore(snap_id)` creates an independent sandbox from the checkpoint. N restores = N independent sandboxes.
- `sbx.fork()` creates a live copy-on-write clone of a running sandbox instantly  -  no snapshot step needed.
- 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 lifecycle using snapshots and forks mid-agent-loop.


    Full endpoint reference, SSE progress events, and status state machine.


    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);
}
```

## Long-running server processes

For servers or daemons that must survive across multiple `exec` calls, use `processes.start` instead of exec with a background flag. The process keeps running even when your driver script moves on.

```python
# Start a long-running server  -  stays alive between exec calls
proc = sbx.processes.start(
    command="python3 -m http.server 8080",
    name="http-server",
)
print(f"Server running  -  pid {proc['pid']}")

# Do other work…

# Tail the last 50 lines of output
logs = sbx.processes.logs(proc["pid"], tail=50)
print(logs)

# List all running processes
for p in sbx.processes.list():
    print(f"  {p['pid']}  {p['command']}  {p['status']}")

# Stop cleanly when done
sbx.processes.stop(proc["pid"])
```

```typescript
// processes is Python-first in the current SDK.
// For TypeScript, use exec with a detached background command:
await sbx.exec('python3 -m http.server 8080 &', { cwd: '/workspace' });

// Check it is up:
const check = await sbx.exec('curl -s http://localhost:8080/', { cwd: '/workspace' });
console.log('Server responded:', check.stdout.slice(0, 80));
```

Use `processes.start` (Python) when you need to tail logs or stop the process programmatically later. Use a backgrounded `exec` command for simpler cases where you only need the process to keep running.

## 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.
- `processes.start` (Python) keeps a server or daemon alive independently of exec calls, with named process management and log tailing.

## Next


    Wire a streaming exec into an LLM agent loop that self-corrects on build errors.


    React to sandbox lifecycle events via webhooks or the SSE stream.


    Complete reference for exec options, working directories, environment variables, and timeouts.

---

# White-label end-users  -  secrets, audit, OAuth branding

URL: https://miosa.ai/docs/cookbook/white-label-end-users
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/cookbook/white-label-end-users
Source: src/routes/docs/cookbook/white-label-end-users/+page.md
Description: Stamp external_user_id on sandboxes, scope credentials per end-user, surface per-user audit data in your own dashboard, and brand the OAuth consent flow with your domain.

# White-label end-users

~15 min Python TypeScript

> **Goal**: You're building a SaaS product on MIOSA. Your end-users create sandboxes through your UI  -  they don't have MIOSA accounts. This recipe shows you how to stamp identity on every sandbox, store per-user credentials, surface a per-user audit feed in your dashboard, and make the GitHub OAuth consent screen say your brand name instead of "Authorize MIOSA."
>
> **What you'll use**: External Attribution, Secrets (external_user scope), Audit Log, White-label OAuth

## What you'll build

```
Your SaaS backend
  └─ creates sandbox with external_user_id + external_workspace_id
  └─ accepts user's OpenAI key → stores it scoped to that user
  └─ initiates GitHub OAuth → stores token scoped to that user
  └─ queries audit log by external_user_id → exposes in your dashboard
  └─ OAuth consent screen shows "Authorize YourApp" not "Authorize MIOSA"
```

## Prerequisites

- MIOSA API key (`msk_live_*`) with admin scope  -  see [API Keys](/docs/platform/api-keys/)
- A GitHub OAuth App registered at `github.com/settings/applications/new` (for the custom branding step)

## Step 1  -  Stamp identity at create time

Every sandbox you create for one of your end-users gets tagged with your IDs.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def create_sandbox_for_user(user_id: str, workspace_id: str, project_id: str):
    sandbox = client.sandboxes.create(
        template="python-ds",
        external_user_id=user_id,
        external_workspace_id=workspace_id,
        external_project_id=project_id,
        timeout_sec=3600,
    )
    return sandbox

sbx = create_sandbox_for_user(
    user_id="dr_smith@clinic1.example",
    workspace_id="clinic1",
    project_id="patient-intake",
)
print(f"Sandbox {sbx.id} created for dr_smith.")
```

```typescript

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

async function createSandboxForUser(
  userId: string,
  workspaceId: string,
  projectId: string,
) {
  return client.sandboxes.create({
    template: 'python-ds',
    externalUserId: userId,
    externalWorkspaceId: workspaceId,
    externalProjectId: projectId,
    timeoutSec: 3600,
  });
}

const sbx = await createSandboxForUser(
  'dr_smith@clinic1.example',
  'clinic1',
  'patient-intake',
);
console.log(`Sandbox ${sbx.id} created for dr_smith.`);
```

Use whatever identifiers make sense in your system  -  email addresses, UUIDs, internal codes. MIOSA treats them as opaque strings. They appear on every audit row, usage record, and secret binding.

## Step 2  -  Store credentials scoped to the end-user

Your user pastes their own OpenAI key into your settings UI. Store it scoped to them  -  other users at the same clinic cannot see it.

```python
def save_user_api_key(user_id: str, openai_key: str):
    client.secrets.set(
        name="openai_key",
        value=openai_key,
        scope="external_user",
        external_user_id=user_id,
        expose_as_env="OPENAI_API_KEY",
    )

save_user_api_key("dr_smith@clinic1.example", "sk-proj-her-personal-key...")
print("Dr. Smith's OpenAI key stored (encrypted). MIOSA cannot read it back.")
```

For a shared clinic-wide credential (e.g., an EHR API key shared by all clinicians at clinic1):

```python
client.secrets.set(
    name="ehr_api_key",
    value="ehr-prod-...",
    scope="external_workspace",
    external_workspace_id="clinic1",
    expose_as_env="EHR_API_KEY",
)
print("Clinic-wide EHR key stored.")
```

```typescript
async function saveUserApiKey(userId: string, openaiKey: string) {
  await client.secrets.set({
    name: 'openai_key',
    value: openaiKey,
    scope: 'external_user',
    externalUserId: userId,
    exposeAsEnv: 'OPENAI_API_KEY',
  });
}

await saveUserApiKey('dr_smith@clinic1.example', 'sk-proj-her-personal-key...');
console.log("Dr. Smith's OpenAI key stored.");

// Clinic-wide credential
await client.secrets.set({
  name: 'ehr_api_key',
  value: 'ehr-prod-...',
  scope: 'external_workspace',
  externalWorkspaceId: 'clinic1',
  exposeAsEnv: 'EHR_API_KEY',
});
```

### How the proxy resolves the right credential

When Dr. Smith's sandbox makes an outbound call, the proxy walks this priority list and uses the first match:

```
1. Direct binding on that specific sandbox
2. external_user scope  ← matches dr_smith@clinic1.example
3. external_workspace scope
4. MIOSA workspace scope
5. Tenant-wide scope
```

Another clinician at the same clinic resolves the clinic-wide `EHR_API_KEY` but not Dr. Smith's personal `OPENAI_API_KEY`.

## Step 3  -  Initiate OAuth on behalf of your end-user

When Dr. Smith clicks "Connect GitHub" in your dashboard, your backend initiates the OAuth flow and sends the authorization URL back to her browser.

```python
from flask import Flask, redirect, request, jsonify

app = Flask(__name__)

@app.post("/api/connect-github")
def connect_github():
    user_id = request.json["user_id"]
    # Create (or retrieve) the sandbox for this user
    sandboxes = client.sandboxes.list(external_user_id=user_id)
    sbx = sandboxes[0] if sandboxes else create_sandbox_for_user(user_id, "clinic1", "intake")

    flow = sbx.secrets.connect(
        provider="github",
        expose_as_env="GITHUB_TOKEN",
        scopes=["repo", "read:user"],
    )
    return jsonify({"authorize_url": flow.authorize_url})

@app.get("/oauth/callback")
def oauth_callback():
    code = request.args["code"]
    state = request.args["state"]
    # Forward to MIOSA to complete the exchange
    client.oauth.complete(provider="github", code=code, state=state)
    return redirect("/dashboard?github=connected")
```

```typescript

const app = express();
app.use(express.json());

app.post('/api/connect-github', async (req, res) => {
  const { userId } = req.body as { userId: string };

  const sandboxes = await client.sandboxes.list({ externalUserId: userId });
  const sbx = sandboxes[0] ?? await createSandboxForUser(userId, 'clinic1', 'intake');

  const flow = await sbx.secrets.connect({
    provider: 'github',
    exposeAsEnv: 'GITHUB_TOKEN',
    scopes: ['repo', 'read:user'],
  });
  res.json({ authorizeUrl: flow.authorizeUrl });
});

app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query as { code: string; state: string };
  await client.oauth.complete({ provider: 'github', code, state });
  res.redirect('/dashboard?github=connected');
});
```

## Step 4  -  Display per-user audit data in your dashboard

Pull the audit log for a single user and render it in your own UI.

```python
def get_user_activity(user_id: str, since: str = "24h"):
    events = client.audit.list(
        since=since,
        external_user_id=user_id,
        limit=200,
    )
    return [
        {
            "time": e.timestamp,
            "host": e.host,
            "method": e.method,
            "status": e.status_code,
            "action": e.action,
        }
        for e in events
    ]

activity = get_user_activity("dr_smith@clinic1.example")
for row in activity[:5]:
    print(row)
```

For workspace-level rollup (all users at clinic1):

```python
workspace_activity = client.audit.list(
    since="7d",
    external_workspace_id="clinic1",
    limit=1000,
)
```

```typescript
async function getUserActivity(userId: string, since = '24h') {
  const events = await client.audit.list({
    since,
    externalUserId: userId,
    limit: 200,
  });
  return events.map(e => ({
    time: e.timestamp,
    host: e.host,
    method: e.method,
    status: e.statusCode,
    action: e.action,
  }));
}

const activity = await getUserActivity('dr_smith@clinic1.example');
console.log(activity.slice(0, 5));

// Workspace rollup
const workspaceActivity = await client.audit.list({
  since: '7d',
  externalWorkspaceId: 'clinic1',
  limit: 1000,
});
```

MIOSA gives you the raw audit data; how you surface it to end-users is entirely up to you. Most white-label customers show "your recent activity" in their dashboards filtered to the logged-in user's external_user_id.

## Step 5  -  Brand the OAuth consent screen

By default, the GitHub consent screen says "Authorize MIOSA." Replace that with your product name.

### Register your OAuth app on GitHub

```
https://github.com/settings/applications/new

Application name:   ClinicIQ Cloud
Homepage URL:       https://cliniciq.example
Callback URL:       https://app.cliniciq.example/oauth/callback
```

Copy the `Client ID` and generate a `Client Secret`.

### Add the override to your MIOSA tenant

In your tenant dashboard → Settings → OAuth Providers → "Add provider override":

| Field | Value |
|---|---|
| Provider | `github` |
| Display name | `GitHub` |
| Client ID | `<from GitHub>` |
| Client Secret | `<from GitHub>` |
| Callback URL | `https://app.cliniciq.example/oauth/callback` |
| Button label | `Connect GitHub to ClinicIQ` |

From now on, when any of your end-users clicks "Connect GitHub," they see:

```
Authorize ClinicIQ Cloud
ClinicIQ Cloud by cliniciq.example is requesting access to:
  ✓ Repositories (read and write)
  ✓ User profile (read)
```

Your brand. Your callback domain. MIOSA is invisible.

### Your callback route forwards to MIOSA

```python
@app.get("/oauth/callback")
def oauth_callback():
    code = request.args["code"]
    state = request.args["state"]
    # MIOSA exchanges the code, stores the token, resolves the pending flow
    client.oauth.complete(provider="github", code=code, state=state)
    return redirect("/dashboard?connected=github")
```

## Step 6  -  Disable end-user-scoped credentials (optional)

Some operators want all credentials managed centrally  -  end-users cannot add their own keys.

In your tenant dashboard → Settings → Security → toggle "Allow end-user-scoped credentials" to Off.

After that, any SDK call with `scope="external_user"` returns HTTP 403. Only `external_workspace` and `tenant` scoped secrets resolve.

## Troubleshooting

**Q: I stored a secret for `dr_smith@clinic1.example` but her sandbox can't see it.**
Check that the sandbox was created with `external_user_id="dr_smith@clinic1.example"` (exact match, case-sensitive). Use `client.sandboxes.get(sbx.id)` and verify `external_user_id` on the returned object.

**Q: The OAuth callback returns `invalid_state`.**
The state token has a 10-minute TTL. If the user took longer than that to authorize, the state expired. Re-initiate `secrets.connect()` to get a fresh `authorize_url`.

**Q: I see "Authorize MIOSA" instead of my brand name.**
You registered the provider override but used MIOSA's default OAuth app client ID. Verify the override in Settings → OAuth Providers shows your own `client_id`, not MIOSA's.

**Q: `client.audit.list(external_user_id=...)` returns an empty list.**
The sandbox must actually make outbound network calls for rows to appear. Confirm with `sandbox.exec("curl -s https://api.openai.com/")`  -  even a 401 generates an audit row.

## What you learned

- `external_user_id` / `external_workspace_id` are the identity primitives for white-label deployments.
- `scope="external_user"` secrets resolve only for that user's sandboxes.
- `client.audit.list(external_user_id=...)` lets you build per-user audit dashboards without any custom logging.
- The OAuth branding override requires registering your own OAuth app with the provider and pointing the callback at your domain.

## Next


    Full walkthrough: vault setup, audit tail, live rotation  -  for your own account.


    Move from audit-only to enforce mode safely, with a rollback plan.


    Full reference for external attribution, scoping, and per-user auditing.

---

# Custom Domains

URL: https://miosa.ai/docs/custom-domains
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/custom-domains
Source: src/routes/docs/custom-domains/+page.md


# Custom Domains

Connect your own domain  -  for example `app.cliniciq.com`  -  so your users land on your brand rather than MIOSA. All sandboxes, computers, and deployments under your org will be accessible through your domain automatically.

## Setup wizard

Go to **Settings → Domains** and click **+ Add custom domain**. The wizard walks you through three steps:

1. Enter your domain (`app.example.com`  -  no `https://`, no trailing path).
2. Add the DNS records shown to your domain provider.
3. Click **Continue to verify**  -  MIOSA checks your DNS and activates the domain.

## Required DNS records

| Type | Name | Value | Notes |
|------|------|-------|-------|
| CNAME | `*.yourdomain.com` | `proxy.miosa.ai` | Routes all subdomains through MIOSA |

Replace `yourdomain.com` with the apex domain you own (e.g. `cliniciq.com` if your custom domain is `app.cliniciq.com`).

> **Apex domains** (no subdomain, e.g. `cliniciq.com` directly) additionally require an A/ALIAS record  -  add `_miosa-verify.cliniciq.com TXT <token>` as shown in the wizard.

## TLS certificates

Certificates are provisioned automatically once DNS propagates. There is nothing to upload. You will see a valid `https://` certificate on first browser visit.

## Propagation time

DNS changes typically take **5-30 minutes** but can take up to 48 hours depending on your provider's TTL settings.

To check current propagation status, run:

```bash
dig *.yourdomain.com CNAME +short
```

The expected result is `proxy.miosa.ai.`

## Troubleshooting

**Verification fails immediately after adding records**

DNS propagation is not instant. Wait a few minutes and click **Retry verification** in the wizard. The page polls every 5 seconds automatically while the wizard is open.

**`dig` shows the right value but verification still fails**

Some DNS providers add extra trailing dots or spaces. Ensure the CNAME value is exactly `proxy.miosa.ai` with no extra characters.

**Cache flush**

If you changed the record and it still shows the old value, try flushing your local DNS cache:

```bash
# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux (systemd-resolved)
sudo systemd-resolve --flush-caches
```

Or check propagation from a neutral vantage point using [dnschecker.org](https://dnschecker.org).

**Multiple domains**

Currently each org can have one white-label custom domain (the wildcard CNAME). Per-resource custom domains (a specific computer at `studio.yourdomain.com`) are configured per-resource in the computer settings.

## Branding

Once your domain is connected, customize the app name, logo, accent color, and favicon at **Settings → General → Branding**. The Domains page shows a live preview of what your users will see.

---

# 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 | running

# 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 | running

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

---

# Deployment 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: Preview domains, tenant deployment domains, managed fallback URLs, exact custom domains, DNS verification, automatic TLS, and route changes.

A **Domain** is a hostname that routes to a preview, a deployment, a computer, or an exact custom resource. For production deployments, always use the `public_url` returned by the API. Do not reconstruct hostnames in SDKs, CLIs, or frontends.

## Domain layers

MIOSA keeps these layers separate:

| Layer | URL shape | Purpose |
|---|---|---|
| Sandbox preview domain | `https://{port}-{sandbox_slug}.sandbox.{preview_domain}` | Mutable live previews while an agent/user is editing |
| Tenant deployment domain | `https://{deployment_slug}.{deployment_domain}` | Branded durable URLs for generated production apps |
| Managed fallback domain | `https://{deployment_slug}.{organization_slug}.miosa.app` | Always-available MIOSA-managed fallback |
| Exact custom domain | `https://customer-owned.example.com` | A customer's chosen production domain attached to one deployment |

ClinicIQ example:

```text
Sandbox preview:   https://5173-abc123.sandbox.cliniciq.com
Deployment domain: https://lead-magnet.apps.cliniciq.com
Managed fallback:  https://lead-magnet.cliniciq.miosa.app
Custom domain:     https://newpatients.someclinic.com
```

Preview domains do not imply production deployment domains. Configure both if you want both surfaces branded.

## Tenant deployment domains

Tenant deployment domains are configured separately from preview domains. The backend resolves `settings["deployment_domain"]` for durable app URLs and falls back to `{organization_slug}.miosa.app` when no deployment domain is configured.

Public tenant-level management routes for deployment domains are not exposed yet. Operators can configure the tenant setting; SDKs and CLIs should treat deployment `public_url` / `url` as authoritative.

Recommended white-label DNS:

| Record type | Name | Value | Used for |
|---|---|---|---|
| `CNAME` | `*.sandbox` | `proxy.miosa.ai` | Sandbox port previews |
| `CNAME` | `*.apps` | `proxy.miosa.ai` | Durable generated apps |

## Exact custom domains

Exact custom domains attach a customer-owned hostname to one deployment:

| Kind | Example | DNS record |
|---|---|---|
| Subdomain | `app.smiledental.test` | `CNAME` to the verification target |
| Apex | `smiledental.test` | `A`/`AAAA`, `ALIAS`, `ANAME`, or flattened `CNAME` depending on DNS provider |
| WWW alias | `www.smiledental.test` | `CNAME` to the verification target |

## The attach flow

```typescript
// 1. Register the exact domain. MIOSA returns DNS instructions.
const domain = await miosa.deployments.domains.add(deploymentId, {
  domain: "newpatients.someclinic.com",
})

console.log(domain.dns_records)

// 2. After records are set, ask MIOSA to verify.
await miosa.deployments.domains.verify(deploymentId, domain.id)

// 3. Use the deployment public_url returned by the API.
const deployment = await miosa.deployments.get(deploymentId)
console.log(deployment.public_url)
```

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_live_...")

domain = miosa.deployments.domains(deployment_id).add(
    domain="newpatients.someclinic.com",
)

for record in domain.get("dns_records", []):
    print(record["type"], record["name"], record["value"])

miosa.deployments.domains(deployment_id).verify(domain["id"])

deployment = miosa.deployments.get(deployment_id)
print(deployment["public_url"])
```

```bash
curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/domains \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"newpatients.someclinic.com"}'

curl -X POST https://api.miosa.ai/api/v1/deployments/$DEP/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

Once verified and TLS-active, MIOSA routes the exact domain to the deployment's active version. Exact custom domains take precedence over tenant deployment domains and MIOSA fallback URLs.

## Redirect policy

For apex + www domains, set the redirect policy:

| Policy | Result |
|---|---|
| `none` | Both apex and www serve independently |
| `apex_to_www` | `smiledental.test` redirects to `www.smiledental.test` |
| `www_to_apex` | `www.smiledental.test` redirects to `smiledental.test` |

Configure at attach time or update later via `PATCH /deployments/:id/domains/:domain_id`.

## What changing a domain does

Changing a domain mapping:

- Updates MIOSA's route table.
- Takes effect within seconds.
- Does **not** rebuild the app.
- Does **not** involve the source sandbox.
- Does **not** require users to change the deployment ID.

This is why rollback is fast: only the deployment's active version/route changes.

## DNS verification edge cases

| Situation | Behavior |
|---|---|
| CNAME points to the wrong host | Verification fails with `dns_target_mismatch`. Show the expected target. |
| TXT record not propagated yet | Verification fails with `dns_propagation_pending`. Retry after a few minutes. |
| User typos the domain | Verification fails with `dns_resolution_error`. Domain stays pending. |
| 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`. Contact support for transfer. |

## White-label checklist

For a platform like ClinicIQ:

1. Configure the organization slug (`cliniciq`).
2. Configure sandbox preview DNS, for example `*.sandbox.cliniciq.com`.
3. Configure tenant deployment DNS, for example `*.apps.cliniciq.com`.
4. Publish generated apps and display the returned deployment `public_url`.
5. Attach exact customer domains only when a clinic brings its own domain.

Preview domains, deployment domains, computer URLs, and exact custom domains are separate. Use the URL returned by the backend for each resource: `preview_url`, `desktop_url`, or deployment `public_url`.

## See also

- [Publishing](/docs/deploy/publishing/)  -  how `public_url` is returned
- [Versions](/docs/deploy/versions/)  -  what the domain points at
- [Rollback](/docs/deploy/rollback/)  -  repointing the deployment at an older version
- [White-label setup](/docs/platform/white-label/)  -  setup order for platforms

---

# 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 versions, health checks, deployment domains, custom domains, and rollback.

Deploying on MIOSA means turning a Sandbox into a stable production app/site/API backed by immutable versions, health checks, and a public URL returned by the API. Once published, the deployment URL stays stable  -  new publishes change 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[Build]
    C -->|builds| D[Release]
    D -->|creates| E[Deployment Version]
    E -->|promotes| F[Static Artifact or Dynamic Runtime]
    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. **Build**  -  MIOSA runs the configured build/packaging pipeline from the frozen source.
4. **Release**  -  the immutable build output. Static: files/assets. Dynamic: a server app artifact with command, port, and health check.
5. **Deployment Version**  -  the row in history. `version_number` increases monotonically. Every version is bootable forever.
6. **Runtime**  -  for dynamic deployments, MIOSA starts a production runtime and health-checks it. Static releases skip this; MIOSA 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 | Files/assets | Server app artifact |
| Production runtime | Static artifact serving  -  no per-app process | Dynamic production runtime |
| 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 the SDK equivalent) and MIOSA chooses the static or dynamic path from your publish inputs. Supplying a run command and port makes the deployment 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.cliniciq.miosa.app (managed fallback)
        │     ├── smile-dental.apps.cliniciq.com  (tenant deployment domain)
        │     └── 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 files or dynamic server artifact |
| 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 deployment at version 14 and MIOSA serves that known-good version again.

Use `kind: "static"`, `kind: "dynamic"`, or `kind: "auto"` when calling `deployments.publish`. MIOSA detects the correct path from the build output when `auto` is set.

## Next


    The sandbox-to-version pipeline: source snapshots, build modes, and promotion.


    Immutable history. List, inspect, promote, and archive versions.


    The artifacts: static files and dynamic server artifacts.


    Dynamic deployments  -  production runtimes, health checks, and reconciler behavior.


    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, build modes, static artifacts, dynamic runtimes, and public URLs.

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[Build]
    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. Build                       (static packager, auto-detect, or explicit commands)
4. Release                     (static artifact or dynamic server artifact, sha256-keyed)
5. Deployment Version          (database row pointing at the release)
6. Health check                (for dynamic; static skips this)
7. 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: 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 deployments 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.apps.cliniciq.com"
    },
    "version": {
      "id": "ver_...",
      "kind": "static",
      "state": "ready",
      "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 is stored 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` | MIOSA builds the container-style server artifact |
| **Auto-detect** | `package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `mix.exs` | MIOSA picks install/build/start defaults |
| **Static packager** | Only static files in output (no server entrypoint detected) | Files are stored as a static release |
| **Explicit** | `buildCommand` and/or `runCommand` provided | MIOSA runs those, then packages whatever's in `output_path` |

Do not construct production URLs in your SDK, CLI, or frontend. Read `data.deployment.public_url` or `data.url` from the publish response and display that exact value. Tenants can use a deployment domain, MIOSA fallback, or an exact custom domain.

## 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 dynamic release artifact was stored.
3. New production runtimes were scheduled.
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 automatically by our operation lock |

## 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 files or dynamic server artifact, sha256-keyed.

A **Release** is the immutable artifact produced by a build. Versions reference releases; static deployments serve files from them and dynamic deployments start runtimes 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.

Most integrations do not need to read release records directly. Use deployment versions and the returned deployment `public_url` unless you are building an operator dashboard or audit workflow.

## Release kinds

| Kind | Used by | Storage |
|---|---|---|
| `static` | Static deployments | Built files and assets |
| `oci` | Dynamic deployments via OCI-compatible workflows | Server image artifact |
| `dynamic` | Server apps with a run command and port | Packaged server artifact |

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.
- **Dynamic releases** → MIOSA starts healthy production runtimes and routes 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 and served by MIOSA. You can inspect release metadata on the version record:
```json
{
  "version_number": 17,
  "artifact_sha256": "a5e6f0c1...",
  "artifact_manifest": {
    "files": 42,
    "total_bytes": 184320,
    "entrypoint": "index.html"
  }
}
```

You do not need to download releases yourself. The metadata 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
- [Dynamic Runtimes](/docs/deploy/runtime-instances/)  -  what serves dynamic releases
- [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

---

# Dynamic Runtimes

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  -  production runtimes started from a release, health-checked, and reconciled by MIOSA.

A **Runtime Instance** is a running production runtime that serves a dynamic deployment. Static deployments do not have runtime instances; they are served from immutable static artifacts.

The caller-facing contract is stable: dynamic deployments start production runtimes, wait for health checks, and only promote when the new version is ready. You do not need to know how MIOSA places or reconciles those runtimes.

## What a runtime instance is

A runtime started from the customer's release. The release is the customer's app, fully packaged. The runtime:

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 30 s; pass `120000` for npm/pip installs | 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://3000-abc12345.sandbox.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://{port}-{slug}.sandbox.miosa.app` where `{slug}` is the first 8 characters of the sandbox UUID. For the template default port, the URL is `https://{slug}.sandbox.miosa.app` (no port prefix). For white-label platforms, this can be `https://{port}-{slug}.sandbox.{your-domain}` 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://3000-abc12345.sandbox.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://3000-abc12345.sandbox.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://3000-abc12345.sandbox.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 `*.sandbox.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://3000-abc12345.sandbox.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 isolated environments for AI agent code execution. Run commands, edit files, expose ports as live preview URLs, snapshot state, and publish to production.

# Sandboxes

A **Sandbox** is a mutable isolated environment for agent-driven development. 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, pause it, or publish it to a production deployment.

## What a Sandbox is  -  concretely

- Isolated compute for code generation, builds, tests, and dev servers
- Configurable CPU, memory, disk, timeout, and environment variables
- `/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
    [*] --> creating : Sandbox.create() / Sandbox.run()
    creating --> running : ready
    running --> running : exec.run() / files.write() / preview traffic
    running --> snapshotting : snapshot()
    snapshotting --> running : snapshot saved
    running --> paused : pause()
    paused --> running : resume() / auto_resume
    running --> destroyed : destroy() / timeout_sec elapsed
    paused --> destroyed : destroy()
    running --> error : boot or runtime failure
    creating --> error : boot failure
    error --> destroyed : cleanup
    destroyed --> [*]

| State | Meaning |
|---|---|
| `creating` / `provisioning` | VM is being claimed, restored, and prepared to accept commands |
| `running` | Command-ready  -  exec, files, previews, terminal, and port exposure work |
| `snapshotting` | Runtime is saving filesystem and memory state for resume/fork |
| `paused` | CPU is stopped; memory/filesystem state is preserved for resume |
| `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`.

## Current production benchmark

On June 9, 2026, MIOSA ran production sandbox benchmarks through the real HTTP API: `100` sandboxes, concurrency `10`, template `miosa-sandbox`, size `xs`.

Result: `100 / 100` sandboxes completed create -> ready -> exec -> destroy, with `0` capacity rejections.

| Path | What it measures | p50 | p95 | p99 |
|---|---|---:|---:|---:|
| `POST /api/v1/sandboxes/run` | Fused create -> wait -> first exec, the optimized agent path | `512ms` | `992ms` | `1.300s` |
| `POST /api/v1/sandboxes` + poll + `/exec` | Standard client-owned lifecycle | `947ms` | `1.333s` | `1.348s` |

See [Benchmarks](/docs/benchmarks/) for methodology, caveats, and the difference between VM boot time and full command-ready time.

## Fast path: create and run

For agents that need a sandbox and immediately run the first command, use the fused run endpoint. It is faster because MIOSA owns the readiness wait on the server and avoids an extra client poll loop plus a second public exec request.

```python

response = requests.post(
    "https://api.miosa.ai/api/v1/sandboxes/run",
    headers={
        "Authorization": f"Bearer {os.environ['MIOSA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "run-2026-06-09-001",
    },
    json={
        "template_id": "miosa-sandbox",
        "command": "python3 -c \"print('ready')\"",
        "cpu_count": 1,
        "memory_mb": 1024,
        "timeout_sec": 300,
        "wait_timeout_ms": 30000,
        "env": {"NODE_ENV": "production"},
        "metadata": {"agent_run": "abc123"},
    },
)
response.raise_for_status()

run = response.json()
print(run["data"]["id"], run["data"]["state"])
print(run["exec"]["stdout"])
print(run["timings"]["server_wait_and_exec_ms"])
```

```typescript
const response = await fetch("https://api.miosa.ai/api/v1/sandboxes/run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MIOSA_API_KEY!}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "run-2026-06-09-001"
  },
  body: JSON.stringify({
    template_id: "miosa-sandbox",
    command: "node -e \"console.log('ready')\"",
    cpu_count: 1,
    memory_mb: 1024,
    timeout_sec: 300,
    wait_timeout_ms: 30000,
    env: { NODE_ENV: "production" },
    metadata: { agent_run: "abc123" }
  })
});

if (!response.ok) throw new Error(await response.text());

const run = await response.json();
console.log(run.data.id, run.data.state);
console.log(run.exec.stdout);
console.log(run.timings.server_wait_and_exec_ms);
```

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

Response shape:

```json
{
  "data": {
    "id": "sbx_a1b2c3d4",
    "state": "running",
    "template_id": "miosa-sandbox",
    "boot_ms": 34,
    "boot_path": "warm"
  },
  "exec": {
    "stdout": "2\n",
    "stderr": "",
    "exit_code": 0
  },
  "timings": {
    "server_wait_and_exec_ms": 512
  }
}
```

## Create with full options

Use full create when you need to provision the sandbox first, write files, start a preview server, attach databases, or keep the ID for a longer session.

```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
    external_user_id="user_123",
    external_project_id="project_456",
    idempotency_key="run-2026-06-09-001",
)

print(sbx.id)
print(sbx.state)
print(sbx.boot_ms)
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",
  externalUserId: "user_123",
  externalProjectId: "project_456",
  idempotencyKey: "run-2026-06-09-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-06-09-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",
    "external_user_id": "user_123",
    "external_project_id": "project_456"
  }'
```

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. Use `120` or more for `npm install` / `pip install`. |

## 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://8080-a1b2c3d4.sandbox.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://8080-a1b2c3d4.sandbox.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(status="running")  # status: "running" | "paused" | "destroyed"

# Filter by name (prefix match)
named = miosa.sandboxes.list(name="my-dev")

# 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({ status: "running" });  // status: "running" | "paused" | "destroyed"
const named   = await miosa.sandboxes.list({ name: "my-dev" });
const byCorp  = await miosa.sandboxes.list({ externalWorkspaceId: "acme-corp" });
```

```bash
curl "https://api.miosa.ai/api/v1/sandboxes?status=running" \
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl "https://api.miosa.ai/api/v1/sandboxes?name=my-dev" \
  -H "Authorization: Bearer $MIOSA_API_KEY"
```

## Sizing reference

| Size name | vCPU | RAM | Disk | Notes |
|---|---|---|---|---|
| `xs` | 1 | 2 GB | 10 GB | Lightweight scripts |
| `small` | 2 | 4 GB | 20 GB | **Default** |
| `medium` | 4 | 8 GB | 50 GB | Recommended for npm/pip builds |
| `large` | 8 | 16 GB | 100 GB | Large builds, heavy test suites |
| `xl` | 16 | 32 GB | 200 GB | Intensive parallelism |

Pass `size: "medium"` (or equivalent `cpu_count`/`memory_mb`) for any sandbox that runs `npm install`, `pip install`, or a build tool. The default `small` is sufficient for pure code-gen or exec-only workloads.

**Raw resource overrides** (still accepted):

| Field | Default | Validation range |
|---|---|---|
| `cpu_count` | 2 | 1-16 |
| `memory_mb` | 4096 | 512-32768 |
| `disk_size_mb` | 20480 | 1024-204800 |
| `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 template images for every major language and framework. Pick the closest match to your stack.

# Templates

A **template** is a pre-built template 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://5173-abc12345.sandbox.miosa.app
```

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: 'nextjs',
});
const preview = await sandbox.previews.create({ port: 3000 });
console.log(preview.url); // https://5173-abc12345.sandbox.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.

---

---

# Evaluations

URL: https://miosa.ai/docs/evaluations
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/evaluations
Source: src/routes/docs/evaluations/+page.md
Description: Measure sandbox, desktop, and agent workflows with reproducible tasks, traces, and desktop-readiness benchmarks.

# Evaluations

Evaluations help you answer a simple question: is your agent actually getting work done on a real computer or sandbox, and how long does the work take?

MIOSA evaluations cover three layers:

| Layer | What it measures |
|---|---|
| **Sandbox workflow** | create, write files, run commands, expose a preview, publish, and clean up |
| **Desktop workflow** | boot a Computer, open a browser, screenshot, click, type, scroll, and observe the result |
| **Agent task** | give an agent a goal, collect the trace, score whether the final state matches the expected outcome |

The public docs describe the measurement model, task shape, and customer-facing outputs. The internal runner, scheduling, and scoring implementation are intentionally abstracted.

## Why evaluations matter

For app-builder products and computer-use agents, normal API uptime is not enough. You need to know:

- How quickly a workspace becomes usable.
- Whether the desktop stream is ready before the agent acts.
- Whether screenshots and actions stay responsive during real tasks.
- Whether a generated app can move from prompt to preview to publish.
- Whether a model, tool loop, or provider change improves task success.

## OSWorld-compatible benchmark direction

OSWorld is a public benchmark for multimodal agents in real computer environments. It defines real desktop tasks, setup state, agent interaction, and execution-based scoring across open-ended workflows. The public OSWorld site describes 369 real-world computer tasks, with 361 tasks commonly used when excluding Google Drive tasks that need manual configuration.

MIOSA uses the same idea for product benchmarking:

- Start from a known computer state.
- Run a task through screenshot and action APIs.
- Capture every observation and action.
- Score the final state with a deterministic evaluator where possible.
- Save the trace so failures can be replayed and compared.

## Evaluation flow

Diagram:
flowchart LR
  A[Task suite] --> B[Provision sandbox or computer]
  B --> C[Run agent loop]
  C --> D[Capture trace]
  D --> E[Score result]
  E --> F[Report success, latency, and cost]

## Desktop readiness metrics

These are the computer desktop metrics we track for V1 quality:

| Metric | Why it matters |
|---|---|
| **Provision time** | Time from create request to assigned machine. |
| **Desktop ready** | Time until the desktop stream accepts a real connection. |
| **First screenshot** | Time until the agent can observe the screen. |
| **First action** | Time until click, type, or key events are accepted. |
| **Screenshot latency** | Round-trip time for repeated screenshots during a task. |
| **Action latency** | Round-trip time for click, type, scroll, and key events. |
| **Task success** | Whether the final desktop state matches the evaluator. |
| **Trace completeness** | Whether every observation and action is captured for replay. |

## Sandbox workflow metrics

For AI app builders, the main path is:

1. Create a sandbox.
2. Write generated files.
3. Install and run the app.
4. Expose a live preview.
5. Iterate on feedback.
6. Publish to a durable deployment.
7. Destroy or pause the workspace.

MIOSA tracks timing and failure rates across that whole path, not just isolated endpoint latency.

## What customers see


    Success rate, total time, p50 and p95 latency, failed step, and resource usage.



    Screenshots, commands, preview URLs, action events, and final result state.



    Compare native MIOSA Computers, BYOC machines, and external providers through one task shape.



    Re-run the same task suite after image, SDK, agent, or provider changes.


## V1 scope

| Capability | Status |
|---|---|
| Sandbox lifecycle benchmark | Available in docs and internal release checks. |
| Desktop readiness benchmark | Available as a V1 quality target. |
| Provider comparison adapter | Available for selected external computer providers. |
| OSWorld-style task scoring | In hardening for partner use. |
| Public leaderboard | Planned after the runner and reporting format stabilize. |

## Use cases

- Validate that a ClinicIQ lead magnet builder can create, preview, and publish a generated app.
- Compare two agent prompts against the same browser task.
- Check whether a desktop image change affected first screenshot time.
- Compare a native MIOSA Computer with an external computer provider.
- Prove that a full-stack app builder still works after SDK or deploy changes.

## See also

- [Benchmarks](/docs/benchmarks/) for current production timing data.
- [Computers](/docs/computers/overview/) for desktop automation.
- [External Compute Providers](/docs/integrations/external-computers/) for provider adapters.
- [Provider Comparison](/docs/integrations/comparison/) for the wider compute landscape.

---

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

Every resource also accepts a free-form `metadata` object (up to 16 key-value string pairs). Use it to carry application-layer context  -  feature flags, plan tier, region, whatever your billing system needs  -  without bloating your own database with a MIOSA resource join.

Integrators use these fields for four main purposes:

- **Usage rollup**  -  query `GET /api/v1/sandboxes?external_workspace_id=acme-co` to aggregate compute time and costs for a downstream customer.
- **Per-end-user quotas**  -  enforce your own rate limits by counting active sandboxes per `external_user_id` before creating a new one.
- **Audit log filtering**  -  the audit log accepts `external_user_id` and `external_project_id` as filters so you can pull a customer-specific activity trail without exposing other customers' data.
- **Chargeback and billing**  -  `external_workspace_id` is the recommended key for billing rollup when you resell MIOSA compute to downstream customers. See the [Audit Log](/docs/api-reference/audit-log) and [Quotas](/docs/api-reference/quotas) references.

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",
    metadata={"plan": "pro", "region": "us-east"},
)

# 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',
  metadata: { plan: 'pro', region: 'us-east' },
});

// 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",
    "metadata": { "plan": "pro", "region": "us-east" }
  }'

# 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. Token types

MIOSA issues five distinct token types. Each covers a different caller and trust level:

| Token | Prefix | Caller | TTL | Read / Write |
|---|---|---|---|---|
| API key | `msk_*` | Your server | Until revoked | Read + Write |
| JWT | `ey...` | Admin UI / browser session | ~1 h (refresh 7 d) | Read + Write |
| Browser token | (opaque) | Your user's browser | Configurable (default 1 h) | Read-only, single resource |
| Preview token | `mp_*` | Browser / `` iframe | Configurable (default 1 h) | Read-only, sandbox preview |
| Share token | `ms_*` | Anyone  -  no account required | Configurable | Read-only, sandbox preview |

The `msk_*` API key is the root credential. All other token types are minted downstream from it by your server. Never give an `msk_*` key to a browser or end user.

For minting flows, revocation, and validation rules see [Authentication](/docs/authentication/) and [Preview Tokens](/docs/integrations/preview-tokens).

---

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

---

## 8. 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.

---

## 9. Tenant-level configuration

White-label integrators can configure four areas of tenant behavior via the API. All routes accept `msk_a_*` admin keys or admin JWTs.

### Preview domain

Map a custom subdomain (e.g., `preview.yourdomain.com`) to sandbox preview URLs. Once set, the MIOSA router serves sandbox previews on your domain instead of `*.miosa.app`. Configure DNS with a CNAME to `sandbox.miosa.app`, then register the domain:

```bash
PUT /api/v1/tenant/preview-domain
{ "domain": "preview.yourdomain.com" }
```

See [Tenant Preview Domain](/docs/api-reference/tenant-preview-domain).

### Branding

Customize the 404 and 502 error pages shown inside sandbox previews and deployments. Accepts an HTML template with `{{status}}` and `{{message}}` interpolation slots:

```bash
PUT /api/v1/tenant/branding
{ "error_page_html": "<html>...</html>", "logo_url": "https://..." }
```

See [Tenant Branding](/docs/api-reference/tenant-branding).

### Webhooks

Subscribe to sandbox and deployment lifecycle events delivered as HTTPS POST requests to your endpoint. MIOSA signs each request with an HMAC-SHA256 signature in the `X-Miosa-Signature` header:

```bash
POST /api/v1/tenant/webhooks
{ "url": "https://yourapp.com/webhooks/miosa", "events": ["sandbox.*", "deployment.*"] }
```

See [Webhooks](/docs/api-reference/webhooks) and [Integrations](/docs/integrations) for the event catalog and signature verification.

### Per-end-user quotas

Set maximum resource counts per `external_user_id` to prevent runaway usage by a single downstream user. Quotas are checked at resource creation time and return `429` with code `QUOTA_EXCEEDED` when reached:

```bash
PUT /api/v1/tenant/quotas
{ "max_sandboxes_per_user": 5, "max_computers_per_user": 2 }
```

See [Quotas](/docs/api-reference/quotas).

---

## 10. 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/).

---

## 10. 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 }
```

### Sandbox lifecycle events

| Event | When |
|---|---|
| `sandbox.created` | Sandbox resource created (not yet booted) |
| `sandbox.ready` | Boot complete, exec and file endpoints available |
| `sandbox.error` | Fatal boot or runtime error |
| `sandbox.destroyed` | Sandbox stopped and resources released |
| `sandbox.share.created` | A share token was minted for the sandbox |
| `sandbox.share.revoked` | A share token was revoked |

### Deployment lifecycle events

| Event | When |
|---|---|
| `deployment.created` | Deployment object created |
| `deployment.build_started` | Builder VM booted, build in progress |
| `deployment.build_succeeded` | Release artifact ready |
| `deployment.build_failed` | Build exited non-zero |
| `deployment.published` | Active version updated, traffic cut over |
| `deployment.rollback` | Active version reset to a prior version |

### Tenant-wide SSE stream

To receive all lifecycle events for your organization without polling per-resource endpoints, subscribe to the tenant stream:

```bash
# Mint a ticket
TICKET=$(curl -s -X POST https://api.miosa.ai/api/v1/events/ticket \
  -H "Authorization: Bearer msk_u_..." | jq -r '.ticket')

# Stream all org events
curl -N "https://api.miosa.ai/api/v1/events?ticket=$TICKET"
```

Each event on the tenant stream includes a `resource_type` and `resource_id` field so you can route to the right handler:
```jsonc
{
  "type": "sandbox.ready",
  "resource_type": "sandbox",
  "resource_id": "sbx_abc123",
  "external_user_id": "alice@acme.com",
  "ts": 1748390462
}
```

See [Events (SSE) API Reference](/docs/api-reference/events/) and [Tenant Events](/docs/api-reference/tenant-events) for the complete event catalog and filtering options.

---

## 11. 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 microVM
  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/sdks/typescript/)

---

# 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: Connect any AI agent to MIOSA's 145-tool MCP server  -  hosted (zero install) or local. Drive sandboxes, computers, deployments, databases, storage, and more from Claude Code, Cursor, Windsurf, or your own agent loop.

# MCP server

The MIOSA MCP (Model Context Protocol) server exposes **145 tools** that let AI coding assistants create sandboxes, run commands, write files, take computer screenshots, manage deployments, storage, databases, and more  -  all without leaving the editor. The server speaks the MCP transport protocol, so any compliant client can drive it.

---

## Two ways to use MCP

### Hosted (zero install)  -  recommended

Point any MCP-compatible client directly at the MIOSA API. No pip, no npm, nothing to install or run locally.

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

This is the easiest path. Your API key travels in the `Authorization` header; the hosted endpoint is always up-to-date with the latest tool catalog.

### Local server

Run the MCP server process on your machine. Useful when you need offline access, custom `MIOSA_API_URL` overrides, or want to inspect traffic.

```bash
# Python
pip install git+https://github.com/Miosa-osa/miosa-mcp.git
miosa-mcp

# TypeScript (no install)
npx @miosa/cli mcp serve
```

---

## 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: 145 tool definitions
  Editor->>MCP: call_tool("sandbox_create", { template: "nextjs" })
  MCP->>API: POST /api/v1/sandboxes
  API->>Sandbox: boot microVM
  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.

When a client sends `initialize`, the server returns an `instructions` field containing a workflow guide  -  a compact description of MIOSA resource types, lifecycle conventions, and recommended tool patterns. MCP-aware clients like Claude Code surface this to the model at session start, so the agent understands the platform without requiring extra prompting.

---

## Configuration

### Claude Code

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "miosa": {
      "url": "https://api.miosa.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer msk_u_..."
      }
    }
  }
}
```

No local process required. Restart Claude Code and the 145 MIOSA tools appear immediately.

```json
{
  "mcpServers": {
    "miosa": {
      "command": "miosa-mcp",
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/cli", "mcp", "serve"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

### Cursor

Open **Cursor → Settings → MCP** and add:

```json
{
  "miosa": {
    "url": "https://api.miosa.ai/api/v1/mcp",
    "headers": {
      "Authorization": "Bearer msk_u_..."
    }
  }
}
```

```json
{
  "miosa": {
    "command": "miosa-mcp",
    "env": { "MIOSA_API_KEY": "msk_u_..." }
  }
}
```

```json
{
  "miosa": {
    "command": "npx",
    "args": ["@miosa/cli", "mcp", "serve"],
    "env": { "MIOSA_API_KEY": "msk_u_..." }
  }
}
```

### Windsurf

In `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "miosa": {
      "url": "https://api.miosa.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer msk_u_..."
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "miosa": {
      "command": "miosa-mcp",
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/cli", "mcp", "serve"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}
```

Reload Windsurf. Tools are available in the Cascade panel.

### Environment variable reference (local server only)

| 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 (145 tools)

### Computer lifecycle (8 tools)

| Tool | Description |
|---|---|
| `computer_create` | Boot a Linux desktop VM. Accepts `template`, `size`, `name`. |
| `computer_list` | List computers. Filterable by `workspace_id`, `status`. |
| `computer_get` | Get computer status, IP, template, region. |
| `computer_update` | Update computer name or configuration. |
| `computer_destroy` | Permanently delete a computer. |
| `computer_start` | Start a stopped computer. |
| `computer_stop` | Stop a running computer. |
| `computer_restart` | Restart a running computer. |

### Desktop control (30 tools)

| Tool | Description |
|---|---|
| `desktop_screenshot` | Take a full-screen screenshot. Returns base64 PNG. |
| `desktop_click` | Left-click at coordinates. |
| `desktop_right_click` | Right-click at coordinates. |
| `desktop_double_click` | Double-click at coordinates. |
| `desktop_type` | Type text (Unicode supported). |
| `desktop_key` | Send a key or chord, e.g. `ctrl+c`. |
| `desktop_hotkey` | Send a multi-key hotkey. |
| `desktop_key_down` | Hold a key down. |
| `desktop_key_up` | Release a held key. |
| `desktop_scroll` | Scroll at a position: `direction`, `amount`. |
| `desktop_drag` | Click-drag from start to end coordinates. |
| `desktop_move_cursor` | Move the mouse cursor without clicking. |
| `desktop_mouse_down` | Press and hold a mouse button. |
| `desktop_mouse_up` | Release a mouse button. |
| `desktop_wait` | Pause execution for N seconds. |
| `desktop_list_windows` | List open windows with IDs, titles, positions. |
| `desktop_launch` | Open a named application. |
| `desktop_focus_window` | Bring a window to the front. |
| `desktop_set_window_size` | Resize a window to specific dimensions. |
| `desktop_set_window_position` | Move a window to specific coordinates. |
| `desktop_maximize_window` | Maximize a window. |
| `desktop_minimize_window` | Minimize a window to the taskbar. |
| `desktop_close_window` | Close a window by ID. |
| `desktop_get_screen_size` | Get display dimensions. |
| `desktop_get_cursor_position` | Get current cursor position. |
| `desktop_get_clipboard` | Read clipboard contents. |
| `desktop_set_clipboard` | Write text to clipboard. |
| `desktop_get_desktop_env` | Get display, session type, user, desktop environment. |
| `desktop_set_wallpaper` | Set desktop wallpaper from a URL (white-label branding). |
| `desktop_accessibility_tree` | Get the AT-SPI accessibility tree for element detection. |

### File I/O (9 tools)

| Tool | Description |
|---|---|
| `file_bash` | Run a shell command on a computer or sandbox. Returns `stdout`, `stderr`, `exit_code`. |
| `file_write` | Write a file at an absolute path. Creates parent directories. |
| `file_read` | Read a file. Returns content as string. |
| `file_list` | List directory contents. Accepts `recursive` flag. |
| `file_stat` | Get file metadata (size, permissions, mtime). |
| `file_mkdir` | Create a directory. |
| `file_rename` | Rename or move a file. |
| `file_copy` | Copy a file. |
| `file_delete` | Delete a file or directory. |

### Checkpoints (4 tools)

| Tool | Description |
|---|---|
| `checkpoint_create` | Snapshot the current computer or sandbox state. |
| `checkpoint_list` | List checkpoints for a resource. |
| `checkpoint_restore` | Restore to a named checkpoint. |
| `checkpoint_delete` | Delete a checkpoint. |

### Services (7 tools)

| Tool | Description |
|---|---|
| `service_create` | Create a long-running service on a computer. |
| `service_list` | List services attached to a computer. |
| `service_start` | Start a stopped service. |
| `service_stop` | Stop a running service. |
| `service_restart` | Restart a service. |
| `service_logs` | Stream log output for a service. |
| `service_delete` | Delete a service. |

### Env / Logs / Domains (7 tools)

| Tool | Description |
|---|---|
| `env_list` | List environment variables for a computer or sandbox. |
| `env_set` | Create or update an environment variable. |
| `env_delete` | Delete an environment variable. |
| `logs_tail` | Stream recent log lines for a computer, sandbox, or deployment. |
| `domain_add` | Attach a custom domain to a deployment or computer. |
| `domain_list` | List domains attached to a resource. |
| `domain_delete` | Remove a custom domain. |

### Sandbox (20 tools)

| Tool | Description |
|---|---|
| `sandbox_create` | Boot a new sandbox. Accepts `template`, `external_workspace_id`, `external_project_id`. |
| `sandbox_list` | List sandboxes. Filterable by `external_workspace_id`, `status`. |
| `sandbox_get` | Get sandbox status, IP, template, created_at. |
| `sandbox_exec` | Run a shell command. Returns `stdout`, `stderr`, `exit_code`. |
| `sandbox_destroy` | Permanently destroy a sandbox and release compute. |
| `sandbox_pause` | Pause a running sandbox (VM paused, not destroyed). |
| `sandbox_resume` | Resume a paused sandbox from its last state. |
| `sandbox_python` | Execute a Python snippet directly in the sandbox. |
| `sandbox_write_file` | Write a file scoped to sandbox paths. |
| `sandbox_read_file` | Read a file scoped to sandbox paths. |
| `sandbox_list_files` | List sandbox directory contents. |
| `sandbox_upload` | Upload a local file into the sandbox. |
| `sandbox_snapshot_create` | Snapshot the current sandbox state. |
| `sandbox_snapshot_list` | List snapshots for the sandbox. |
| `sandbox_snapshot_restore` | Restore a sandbox to a named snapshot. |
| `sandbox_logs` | Stream sandbox log output. |
| `sandbox_expose` | Expose a sandbox port as a public HTTPS URL. |
| `sandbox_deploy` | Deploy sandbox output to a permanent URL. |
| `sandbox_template_list` | List available sandbox templates. |
| `sandbox_template_create` | Create a custom sandbox template. |

### Deployments (11 tools)

| Tool | Description |
|---|---|
| `deployment_list` | List all deployments. Filterable by `status`, `name`. |
| `deployment_get` | Get deployment status and configuration. |
| `deployment_create` | Create a new deployment. |
| `deployment_delete` | Delete a deployment. |
| `deployment_publish` | Publish from a sandbox source to production. |
| `deployment_rollback` | Roll back to a previous version. |
| `deployment_env_list` | List environment variables for a deployment. |
| `deployment_env_set` | Set an environment variable on a deployment. |
| `deployment_logs` | Stream deployment logs. |
| `deployment_version_list` | List versions for a deployment. |
| `deployment_version_promote` | Promote a version to active. |

### Storage (8 tools)

| Tool | Description |
|---|---|
| `storage_bucket_list` | List all buckets. |
| `storage_bucket_create` | Create an object storage bucket. |
| `storage_bucket_delete` | Delete a bucket. |
| `storage_object_list` | List objects in a bucket, with optional prefix. |
| `storage_object_upload` | Upload an object to a bucket. |
| `storage_object_download` | Download an object from a bucket. |
| `storage_object_delete` | Delete an object. |
| `storage_presign` | Generate a time-limited signed URL. |

### Databases (6 tools)

| Tool | Description |
|---|---|
| `database_list` | List all databases. |
| `database_create` | Provision a managed Postgres instance. |
| `database_get` | Get database status and connection details. |
| `database_delete` | Delete a database. |
| `database_credentials` | Retrieve the connection string. |
| `database_logs` | Stream database log output. |

### Workspaces (6 tools)

| Tool | Description |
|---|---|
| `workspace_list` | List all workspaces. Filterable by `status`, `name`. |
| `workspace_create` | Create a workspace for tenant isolation. |
| `workspace_get` | Get workspace details. |
| `workspace_update` | Rename or reconfigure a workspace. |
| `workspace_stats` | Get resource counts for a workspace. |
| `workspace_usage` | Get compute usage stats for a workspace. |

### Cron (6 tools)

| Tool | Description |
|---|---|
| `cron_list` | List all cron jobs. |
| `cron_create` | Create a scheduled cron job. |
| `cron_delete` | Delete a cron job. |
| `cron_pause` | Pause a cron job without deleting it. |
| `cron_resume` | Resume a paused cron job. |
| `cron_run_now` | Trigger a cron job immediately. |

### Volumes (5 tools)

| Tool | Description |
|---|---|
| `volume_list` | List all volumes. |
| `volume_create` | Create a persistent volume. |
| `volume_delete` | Delete a volume. |
| `volume_attach` | Attach a volume to a computer or sandbox. |
| `volume_detach` | Detach a volume. |

### Webhooks (4 tools)

| Tool | Description |
|---|---|
| `webhook_list` | List all webhooks. |
| `webhook_create` | Create a webhook for an event type. |
| `webhook_delete` | Delete a webhook. |
| `webhook_test` | Send a test payload to a webhook endpoint. |

### Functions (4 tools)

| Tool | Description |
|---|---|
| `function_list` | List serverless functions. |
| `function_create` | Deploy a serverless function. |
| `function_invoke` | Invoke a function immediately. Returns `"Function deployment is not yet supported via MCP"` if no function is deployed. |
| `function_delete` | Delete a function. |

### API Keys (3 tools)

| Tool | Description |
|---|---|
| `api_key_list` | List API keys for the workspace. |
| `api_key_create` | Create a new API key with optional scopes. |
| `api_key_delete` | Revoke an API key. |

### Network (3 tools)

| Tool | Description |
|---|---|
| `network_policy_get` | Get the current network policy for a resource. |
| `network_policy_set` | Update the network policy (allowlists, egress rules). |
| `network_policy_reset` | Reset network policy to defaults. |

### Ports (3 tools)

| Tool | Description |
|---|---|
| `port_expose` | Expose a port on a computer or sandbox as a public HTTPS URL. |
| `port_list` | List exposed ports for a resource. |
| `port_preview_url` | Get the public preview URL for an exposed port. |

### Billing (2 tools)

| Tool | Description |
|---|---|
| `billing_usage` | Get compute usage for a time window. |
| `billing_plan` | Get current plan details and limits. |

### Regions (1 tool)

| Tool | Description |
|---|---|
| `region_list` | List available regions and their availability. |

### Settings (4 tools)

| Tool | Description |
|---|---|
| `settings_get` | Get workspace settings. |
| `settings_get_branding` | Get branding configuration (logo, colors, domain). |
| `settings_update_branding` | Update branding configuration. |
| `settings_compute_pricing` | Get compute pricing for the current plan. |

---

## Usage examples

### Create a computer and take a screenshot

```
You: Create a Linux desktop and take a screenshot of whatever is on screen.
```

The assistant calls `computer_create({ template: "miosa-desktop", size: "small" })`, waits for it to boot, calls `desktop_screenshot()`, and describes what it sees. It can then call `desktop_click`, `desktop_type`, and `desktop_launch` to interact.

---

### Deploy a sandbox to production

```
You: Build the Next.js app in the sandbox and deploy it to a permanent URL.
```

The assistant calls `sandbox_exec({ command: "npm run build" })`, confirms `exit_code: 0`, then calls `deployment_publish({ sourceSandboxId: "sbx_...", kind: "static", outputPath: "/workspace/.next/out" })` and returns the live URL.

---

### Set up a cron job

```
You: Create a cron job that runs a health check script every 5 minutes.
```

The assistant calls `cron_create({ schedule: "*/5 * * * *", command: "bash /workspace/health-check.sh", sandboxId: "sbx_..." })`. To trigger it immediately for a smoke test, it calls `cron_run_now({ id: "cron_..." })`.

---

### Create a database and get credentials

```
You: Provision a Postgres database and give me the connection string for my app.
```

The assistant calls `database_create({ name: "my-app-db", region: "us-east" })`, polls `database_get` until status is `running`, then calls `database_credentials({ id: "db_..." })` and returns the connection string. It can also call `deployment_env_set` to inject `DATABASE_URL` directly into a deployment.

---

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

**`401 Unauthorized` on hosted MCP**  -  Confirm the `Authorization` header value starts with `Bearer msk_u_` (not just the key alone). Check that the key is active under Dashboard → Settings → API Keys.

**`MIOSA_API_KEY is not set` (local server)**  -  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 Forbidden`**  -  Your key is valid but lacks the required scope. Check [API Keys](/docs/platform/api-keys/) to confirm the key has the scopes needed for the tools you're calling.

**`No tools appear in Cursor`**  -  Cursor requires the MCP config to be valid JSON. Run `node -e "JSON.parse(require('fs').readFileSync('cursor-mcp.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 the scopes your workflow needs. Never use an admin key for editor integrations.
- The hosted MCP endpoint and local MCP server both make outbound HTTPS requests only. Neither opens inbound ports.
- Resources created through MCP are subject to the same tenant-scoped authorization as direct 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/sdks/typescript/)

---

# Claude Code Skills

URL: https://miosa.ai/docs/guides/skills
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/guides/skills
Source: src/routes/docs/guides/skills/+page.md


# Claude Code Skills for MIOSA

Skills extend Claude Code with MIOSA-specific knowledge. Install them once and Claude automatically loads the right one when you ask for cloud infrastructure  -  no manual prompting.

## What you get

| Skill | What it does |
|---|---|
| `miosa-mcp` | Universal entry point  -  explains the 145-tool surface and routes to specific skills |
| `miosa-sandbox` | Headless code-execution VMs (Python, Node, builds, CI) |
| `miosa-computer` | Desktop VMs (browser automation, GUI, computer-use) |
| `miosa-deploy` | Git-backed web app hosting (Next.js, Vite, Flask, Django) |
| `miosa-data` | Managed Postgres/MySQL/Redis, S3 storage, volumes, cron |

Each skill ships with an `examples.md` (or `reference.md`) bundled file Claude loads on demand. SKILL.md bodies stay under 100 lines  -  minimum context cost, maximum signal.

## Install

```bash
git clone https://github.com/Miosa-osa/miosa-skills.git
cp -r miosa-skills/* ~/.claude/skills/
```

Or per-project:

```bash
cp -r miosa-skills/* .claude/skills/
```

## Verify

Open Claude Code in any project and ask:

```
What skills are available?
```

You should see all 5 `miosa-*` skills listed.

## How they activate

You don't need to invoke them manually. Each skill declares trigger phrases in its `description` and `when_to_use` frontmatter. Say things like:

- "create a sandbox and run this" → `miosa-sandbox` loads
- "take a screenshot and click the login button" → `miosa-computer` loads
- "deploy this repo to production" → `miosa-deploy` loads
- "I need a Postgres database" → `miosa-data` loads

You can also invoke directly with `/miosa-sandbox`, `/miosa-computer`, etc.

## Structure (official Agent Skills spec)

```
~/.claude/skills/miosa-sandbox/
├── SKILL.md         # YAML frontmatter + tight overview (<100 lines)
└── examples.md      # Workflow patterns, loaded on demand
```

Each `SKILL.md` includes:

- `description`  -  what the skill does, when to use it
- `when_to_use`  -  trigger phrases for automatic activation
- `allowed-tools`  -  pre-approved MCP tools (no permission prompts)

Body covers: lifecycle, sizes, conventions, the core loop, errors. Detailed examples live in the sibling file so they don't bloat context until you need them.

## What's in each skill

### miosa-mcp
- Resource map (sandbox vs computer vs deployment vs database vs storage vs volume)
- Universal conventions (IDs, status polling, sizes, paths, timeouts)
- Decision tree pointing to the right resource skill
- `reference.md` with the full 145-tool catalog by category

### miosa-sandbox
- Core loop: `create_sandbox` → `exec` → `destroy_sandbox`
- Size guidance (small=4GB, medium for builds, etc.)
- Heredoc trick for multi-file projects
- `examples.md`: build-and-serve, data processing, snapshot reuse, PR testing, benchmarks

### miosa-computer
- Screenshot → identify → click/type → screenshot → verify loop
- Coordinate system (1024×768, absolute pixels)
- Mouse/keyboard tool table
- `examples.md`: browser automation, form filling, checkpoints, services, drag-drop, hotkeys

### miosa-deploy
- GitHub → deployment flow
- Sandbox promotion via `sandbox_deploy`
- Framework auto-detection table
- `examples.md`: Next.js+DB, preview branches, rollback, env updates

### miosa-data
- Database creation + credential wiring
- Storage buckets + presigned URLs (PUT and GET)
- Volume vs storage decision table
- Cron schedule reference
- `examples.md`: full-app patterns, backup pipelines, client-direct uploads

## Customizing

The skills are intentionally tight. To extend:

1. Add an `examples.md` entry under the skill that needs the pattern
2. Add `paths:` to a skill's frontmatter to restrict it to certain file types
3. Override `allowed-tools` if you want manual approval on certain tools

To override a skill's listing (e.g. hide one):

```json
// .claude/settings.local.json
{
  "skillOverrides": {
    "miosa-computer": "off"
  }
}
```

## Why skills instead of CLAUDE.md

CLAUDE.md content loads into context on every session. Skills load only when relevant. For 145 tools across 6 resource types, that's the difference between burning ~3,000 tokens per session vs ~200 tokens (just the descriptions).

## Updating

```bash
cd ~/.claude/skills
git -C miosa-skills pull
cp -r miosa-skills/* .
```

Claude Code watches the skills directory and picks up changes mid-session  -  no restart needed.

## Related

- [MCP guide](/docs/guides/mcp)  -  the 145-tool surface these skills wrap
- [CLI](/docs/cli)  -  `miosa mcp install` to configure the MCP server
- [Quickstart](/docs/quickstart)  -  get a sandbox running in under 60s

---

# Integrations  -  Build Your Own Product on MIOSA

URL: https://miosa.ai/docs/integrations
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations
Source: src/routes/docs/integrations/+page.md
Description: Ship a white-label SaaS where your end-users never see the MIOSA brand. Isolated compute, custom domains, branded previews, usage rollup, and webhooks  -  all under your domain.

# Build your own product on MIOSA

MIOSA gives you the full compute and preview infrastructure. You own the product, the brand, and the user relationship. Your customers never see "MIOSA".

This section covers everything you need to ship a white-label SaaS on top of MIOSA: per-user provisioning, custom domains, secure iframe embeds, webhooks, usage metering, and abuse controls.

---

## What white-label tenants get

| Capability | What it means for your product |
|---|---|
| **Isolated sandboxes per user** | Each customer project runs in its own microVM with its own filesystem, network, and process tree. |
| **Custom preview domains** | Sandbox previews serve from `*.opendesigns.ai` instead of `*.miosa.app`. |
| **Short-lived preview tokens** | Mint a server-side token, pass it to the browser  -  never expose your API key client-side. |
| **Webhook lifecycle events** | Receive `sandbox.running`, `sandbox.destroyed`, and more at your own HTTPS endpoint. |
| **Usage rollup by user** | Query compute usage keyed to your own `external_user_id` for per-seat billing. |
| **Per-user quotas** | Set max sandboxes, max CPU, or max runtime per user to prevent runaway spend. |
| **Branded failure pages** | 502 and 404 errors in previews show your logo, not MIOSA's. |
| **Full filesystem and terminal access** | Expose a file tree, terminal, or run-button in your UI using the SDK  -  no shell into MIOSA required. |

---

## Architecture patterns

Three deployment patterns cover the vast majority of integrations. All three keep your `msk_*` API key server-side.

Diagram:
flowchart TB
  subgraph "Pattern 1  -  Server-side proxy"
    A1[Browser] -->|Your API routes| B1[Your backend]
    B1 -->|msk_ API key| C1[MIOSA API]
    B1 -->|Preview token| A1
    A1 -->|iframe src| D1[preview.miosa.ai / your domain]
  end

  subgraph "Pattern 2  -  Backend-for-Frontend (BFF)"
    A2[Browser] -->|REST/GraphQL| B2[BFF layer]
    B2 -->|msk_ API key| C2[MIOSA API]
    B2 -->|Short-lived JWT| A2
    A2 -->|SDK calls with JWT| C2
  end

  subgraph "Pattern 3  -  Direct with browser tokens"
    A3[Browser] -->|Auth request| B3[Your backend]
    B3 -->|Mint browser token| C3[MIOSA API]
    B3 -->|mp_ token| A3
    A3 -->|@miosa/sdk + token| C3
  end

### Pattern 1  -  Server-side proxy (recommended for most teams)

Your backend owns all MIOSA calls. The browser only receives a short-lived preview URL from your API. This is the simplest pattern and the one used in the `whitelabel-saas` example.

**When to use:** You already have a backend. You want the tightest control over what each user can do. No SDK needed in the browser.

### Pattern 2  -  Backend-for-Frontend (BFF)

A thin BFF layer authenticates the user, resolves their MIOSA workspace/project IDs, and returns a short-lived JWT. The browser then calls MIOSA directly using that token.

**When to use:** High-volume preview-heavy products where round-tripping every terminal keystroke through your backend adds latency.

### Pattern 3  -  Direct with browser tokens

Your backend mints a scoped browser token (`mp_...`) once. The browser uses `@miosa/sdk` directly with that token for file reads, exec calls, and preview embeds.

**When to use:** Interactive coding tools or IDEs where the browser needs low-latency direct access to the sandbox.

---

## Five-minute path for new integrators

1. [One-time setup](/docs/integrations/whitelabel-saas#one-time-setup)  -  register your domain, set branding, configure a webhook
2. [Provision a sandbox per user](/docs/integrations/whitelabel-saas#per-user-provisioning)  -  `client.sandboxes.create(external_user_id=...)`
3. [Embed the preview](/docs/integrations/whitelabel-saas#embed-preview)  -  mint a token server-side, drop an `<iframe>` in your UI
4. [Handle lifecycle events](/docs/integrations/whitelabel-saas#webhooks)  -  react to `sandbox.running`, `sandbox.destroyed`
5. [Bill by user](/docs/integrations/whitelabel-saas#bill-by-user)  -  query usage keyed to your `external_user_id`

---

## Example apps

Four full-stack examples you can clone and run locally:


    The canonical white-label walkthrough. OpenDesigns.ai  -  a design tool SaaS  -  provisions sandboxes per customer project, embeds previews in iframes, and verifies lifecycle webhooks.

    [Walkthrough →](/docs/integrations/whitelabel-saas)


    A React frontend with an Express BFF. Shows how to mint browser tokens server-side and use the TypeScript SDK directly from the browser for live terminal access.

    [Examples gallery →](/docs/integrations/examples)


    A Next.js App Router marketplace where each seller gets an isolated sandbox for their storefront. Uses Route Handlers for token minting and Server Components for usage display.

    [Examples gallery →](/docs/integrations/examples)


    An interactive coding tutor. Each lesson runs in a fresh sandbox. Demonstrates quota enforcement, public share links, and the file-tree SDK primitives.

    [Examples gallery →](/docs/integrations/examples)


---

## See also

- [External Compute Providers  -  bring Orgo/E2B/Daytona computers into MIOSA](/docs/integrations/external-computers)
- [Preview Tokens  -  auth deep dive](/docs/integrations/preview-tokens)
- [Webhooks reference](/docs/integrations/webhooks)
- [White-Label Setup (domains, branding)](/docs/platform/white-label)
- [External Attribution](/docs/platform/attribution)
- [Usage & Billing](/docs/platform/usage-and-billing)

---

# Compute Provider Comparison

URL: https://miosa.ai/docs/integrations/comparison
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/comparison
Source: src/routes/docs/integrations/comparison/+page.md
Description: How MIOSA compares to Orgo, AgentComputer, E2B, Daytona, and ascii Box on pricing, capabilities, and desktop/boot performance. Public data as of 2026-06-09.

# Compute Provider Comparison

How MIOSA fits alongside other agent-computer and sandbox providers on
**price**, **capabilities**, and **desktop performance**. Every external number
is from the vendor's public pricing or docs as of **2026-06-09**. Re-check before
you make a buying decision.

<div style="display:flex;align-items:center;gap:.75rem;flex-wrap:wrap;margin:1rem 0 1.5rem;">
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="/osa-orb-96.png" width="18" height="18" alt="" /> <strong>MIOSA</strong></span>
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="/integrations/orgo.png" width="18" height="16" alt="" /> Orgo</span>
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="https://www.google.com/s2/favicons?domain=agentcomputer.ai&sz=64" width="16" height="16" alt="" /> AgentComputer</span>
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="https://www.google.com/s2/favicons?domain=e2b.dev&sz=64" width="16" height="16" alt="" /> E2B</span>
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="https://www.google.com/s2/favicons?domain=daytona.io&sz=64" width="16" height="16" alt="" /> Daytona</span>
  <span style="display:inline-flex;align-items:center;gap:.45rem;padding:.35rem .7rem;border:1px solid #2a2a2a;border-radius:10px;"><img src="https://www.google.com/s2/favicons?domain=ascii.dev&sz=64" width="16" height="16" alt="" /> ascii Box</span>
</div>

## Pricing model

| Provider | Model | Entry price | Free tier |
|---|---|---|---|
| **MIOSA** | Subscription budget across computers, sandboxes, storage, and inference | Free $0 ($5 incl.) · Starter $19 · Pro $49 · Team $149 | ✅ Free plan, $5 included |
| **Orgo** | Subscription tiers, fixed # of persistent computers | Hacker $29/mo (5 computers) · Team $112 · Scale $224 | ❌ no public free tier (beta program access) |
| **AgentComputer** | Pure pay-as-you-go | usage only (see below) | ❌ none listed |
| **E2B** | Subscription + per-second usage | Hobby free · Pro $150/mo | ✅ $100 one-time credit |
| **Daytona** | Pure pay-as-you-go | usage only | ✅ $200 credit (up to $50k startups) |
| **ascii Box** | Per-second, monthly minimum | $20/mo minimum | ❌ (covered by minimum) |

## Compute cost, normalized

Same box everywhere: **4 vCPU / 8 GB RAM, running, per hour**, computed from
each vendor's unit rates. Subscription-bundled providers (MIOSA, Orgo) don't
expose a clean per-hour rate, so they're marked accordingly.

| Provider | vCPU rate | RAM rate | **4 vCPU + 8 GB / hr** |
|---|---|---|---|
| **ascii Box** | fixed 4 vCPU / 8 GB | not listed | **~$0.036** ($20 / ~555 h) |
| **E2B** | $0.0504 / vCPU-hr | $0.0162 / GiB-hr | **~$0.33** (+ $150/mo on Pro) |
| **Daytona** | $0.0504 / vCPU-hr | $0.0162 / GiB-hr | **~$0.33** (+ storage after 5 GB) |
| **AgentComputer** | $0.07 / CPU-hr | $0.04375 / GB-hr | **~$0.63** |
| **Orgo** | subscription | subscription | Scale $224/mo = 50 × persistent 4 vCPU/16 GB |
| **MIOSA** | budget ledger | budget ledger | subscription budget; PAYG tiers via plan |

ascii Box is cheapest on raw compute but only ships a single fixed 4 vCPU / 8 GB
shape. E2B and Daytona use identical per-unit rates. AgentComputer is the most
expensive per unit. Orgo and MIOSA bundle compute into a subscription budget
rather than billing raw hours.

## Cost calculator

Drag to size a box and see the estimated monthly cost per provider. Usage
providers are computed live from list rates; subscription providers (MIOSA, Orgo)
show their entry plan.

## Capability matrix

| Capability | MIOSA | Orgo | AgentComputer | E2B | Daytona | ascii Box |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| GUI desktop | ✅ | ✅ |  -  | partial |  -  | ✅ 60 fps |
| Shell access | ✅ API and terminal | WS terminal | CLI | SDK exec | ✅ | ✅ SSH+SCP |
| Dedicated IPv4 | per machine | not listed | not listed | not listed | not listed | ✅ |
| Port ingress / preview URLs | ✅ | provider-specific | not listed | ✅ | ✅ | ✅ (via IPv4) |
| Snapshot / fork | ✅ | clone (tier-gated) | not listed | beta | ✅ | ✅ fork |
| Persistent disk | ✅ | ✅ | ✅ hot/cold | session-bound | ✅ | ✅ |
| Bring your own hardware | ✅ BYOC | not listed | not listed | not listed | on-prem | not listed |
| **Use through MIOSA** | native | ✅ [adapter](/docs/integrations/external-computers) | adaptable | adaptable | adaptable | adaptable |

✅ documented · partial/beta noted · not listed means not found in public docs on 2026-06-09.

## Desktop & boot performance

MIOSA's current production sandbox benchmark runs **0.512 s p50** across 100
successful lifecycles. See the full [Benchmarks leaderboard](/docs/benchmarks/)
for sample size, run context, and metric definitions.

For the GUI-computer providers we drive directly, measured through the same
normalized adapter:

| metric | MIOSA | Orgo (measured 2026-06-09) |
|---|---|---|
| boot / provision | ~0.17-0.5 s | 0.27 s warm pool · 3.13 s cold |
| desktop-ready | sub-second (snapshot restore) | 2.09 s |
| exec round-trip p50 | measured per run | 100 ms |
| screenshot p50 | measured per run | 290 ms - 1.19 s |

Run the head-to-head yourself with a MIOSA + Orgo key:

```bash
git clone https://github.com/Miosa-osa/external-compute-orgo
cd external-compute-orgo && pip install -r requirements.txt
MIOSA_API_KEY=msk_... ORGO_API_KEY=sk_live_... python benchmark.py --runs 12 --json
```

## Where MIOSA fits best

- **One API over three substrates**: cloud, [your own hardware (BYOC)](/docs/computers/byoc/), and [external providers](/docs/integrations/external-computers).
- **Budget, not metered surprise**: your subscription is the spend ceiling across compute, storage, and inference.
- **Port ingress + custom domains** out of the box (Orgo and AgentComputer have no general ingress).
- **White-label app builders**: sandboxes, previews, deployments, browser tokens, external attribution, and domains in one product surface.
- **Provider flexibility**: plug a third-party computer into MIOSA when a customer already uses that provider.

Pricing and capabilities change. These figures are public data captured
2026-06-09; treat them as a starting point and verify against each vendor before
making a buying decision.

## See also

- [External Compute Providers](/docs/integrations/external-computers) - connect provider-backed computers to MIOSA
- [Benchmarks](/docs/benchmarks/) - MIOSA's measured boot and command-ready numbers
- [BYOC / OpenComputers](/docs/computers/byoc/) - bring your own hardware

---

# Example Apps

URL: https://miosa.ai/docs/integrations/examples
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/examples
Source: src/routes/docs/integrations/examples/+page.md
Description: Four full-stack white-label examples you can clone, run locally, and adapt to your own stack.

# Example apps

Four complete, runnable examples. Each demonstrates a different frontend stack and a different set of white-label capabilities. Clone the repo and follow the "Run locally" steps below each entry.

All examples live in `examples/` at the root of the [MIOSA GitHub repository](https://github.com/Miosa-osa/miosa).

---

## whitelabel-saas

**Stack:** Python (Flask) backend + plain HTML/JS frontend

**What it demonstrates:**

- One-time tenant setup: custom preview domain, branding, webhook registration
- Per-customer sandbox provisioning with `external_user_id`, `external_project_id`, and `metadata`
- Server-side preview token minting and iframe embed
- HMAC-SHA256 webhook signature verification
- Teardown by `external_user_id` (cancellation flow)

This is the canonical reference example. Every concept in the [white-label walkthrough](/docs/integrations/whitelabel-saas) maps directly to code in this example.

**Run locally:**

```bash
cd examples/whitelabel-saas
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env  -  fill in MIOSA_API_KEY

python setup.py      # one-time tenant setup
python app.py        # server on http://localhost:8000
# Open index.html in a browser for the embed demo
```

**GitHub:** [`examples/whitelabel-saas`](https://github.com/Miosa-osa/miosa/tree/main/examples/whitelabel-saas)

---

## whitelabel-react-saas

**Stack:** React 18 (Vite) frontend + Express.js BFF

**What it demonstrates:**

- BFF pattern: Express mints browser tokens; React uses `@miosa/sdk` directly in the browser
- Live terminal inside an iframe powered by the TypeScript SDK
- Per-user sandbox state stored in the BFF session
- Sandbox resume on page refresh (poll for `state === "running"` before showing the embed)
- Token refresh on `miosa:preview:expired` message event

**Run locally:**

```bash
cd examples/whitelabel-react-saas
pnpm install

cp .env.example .env
# Edit .env  -  fill in MIOSA_API_KEY

pnpm dev   # starts both Express (port 3001) and Vite (port 5173)
# Open http://localhost:5173
```

**GitHub:** [`examples/whitelabel-react-saas`](https://github.com/Miosa-osa/miosa/tree/main/examples/whitelabel-react-saas)

---

## whitelabel-nextjs-marketplace

**Stack:** Next.js 15 (App Router) full-stack

**What it demonstrates:**

- Next.js Route Handlers as the BFF: token minting without a separate Express server
- Seller onboarding: sandbox provisioned on first login, re-used on return
- Multi-project listing: sandboxes filtered by `external_user_id` and rendered as cards
- Usage display: per-seller compute hours fetched with `client.usage.get(external_user_id)`
- Custom `next.config.js` to proxy sandbox previews through the Next.js server (avoid CORS for embedded iframes)

**Run locally:**

```bash
cd examples/whitelabel-nextjs-marketplace
pnpm install

cp .env.local.example .env.local
# Edit .env.local  -  fill in MIOSA_API_KEY

pnpm dev   # starts on http://localhost:3000
```

**GitHub:** [`examples/whitelabel-nextjs-marketplace`](https://github.com/Miosa-osa/miosa/tree/main/examples/whitelabel-nextjs-marketplace)

---

## whitelabel-vue-tutor

**Stack:** Vue 3 (Vite) frontend + Express.js backend

**What it demonstrates:**

- Per-lesson sandbox lifecycle: fresh sandbox per lesson, destroyed on completion
- Quota enforcement: custom middleware rejects `sandbox.create` if the user has reached their limit
- Public share links with a 15-minute TTL for peer review
- File-tree component: reads the sandbox filesystem via `client.files.list(sandboxId, "/")`
- Run-button component: streams exec output via `client.exec.stream(sandboxId, "npm test")`

**Run locally:**

```bash
cd examples/whitelabel-vue-tutor
pnpm install

cp .env.example .env
# Edit .env  -  fill in MIOSA_API_KEY

pnpm dev   # starts both Express (port 3001) and Vite (port 5174)
# Open http://localhost:5174
```

**GitHub:** [`examples/whitelabel-vue-tutor`](https://github.com/Miosa-osa/miosa/tree/main/examples/whitelabel-vue-tutor)

---

## Feature matrix

| Capability | whitelabel-saas | whitelabel-react-saas | whitelabel-nextjs-marketplace | whitelabel-vue-tutor |
|---|:---:|:---:|:---:|:---:|
| Preview token (server-side) | Yes | Yes | Yes | Yes |
| Iframe embed | Yes | Yes | Yes | Yes |
| Webhook verification | Yes |  -  |  -  |  -  |
| Browser token (client SDK) |  -  | Yes |  -  |  -  |
| Live terminal |  -  | Yes |  -  | Yes |
| File tree |  -  |  -  |  -  | Yes |
| Exec streaming |  -  |  -  |  -  | Yes |
| Usage display |  -  |  -  | Yes |  -  |
| Quota enforcement |  -  |  -  |  -  | Yes |
| Public share links |  -  |  -  |  -  | Yes |
| Teardown by user | Yes |  -  |  -  |  -  |

---

## Contributing an example

If you build something on MIOSA and want to share it, open a pull request in the [MIOSA GitHub repository](https://github.com/Miosa-osa/miosa). Examples must:

- Include a working `README.md` with local setup instructions
- Not commit `MIOSA_API_KEY` or any secrets
- Use `external_user_id` for all resource attribution
- Verify webhook signatures if a webhook endpoint is included

---

## See also

- [End-to-end walkthrough](/docs/integrations/whitelabel-saas)
- [Preview Tokens](/docs/integrations/preview-tokens)
- [Webhooks reference](/docs/integrations/webhooks)

---

# External Compute Providers

URL: https://miosa.ai/docs/integrations/external-computers
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/external-computers
Source: src/routes/docs/integrations/external-computers/+page.md
Description: Connect third-party computer providers to MIOSA while keeping one product API, one billing model, and one user experience.

# External Compute Providers

<div style="display:flex;align-items:center;gap:1rem;flex-wrap:wrap;margin:1rem 0 1.5rem;">
  <span style="font-size:1.05rem;opacity:.7;">Available providers:</span>
  <span style="display:inline-flex;align-items:center;gap:.5rem;padding:.4rem .8rem;border:1px solid var(--docs-border,#2a2a2a);border-radius:10px;">
    <img src="/integrations/orgo.png" alt="Orgo" width="22" height="20" style="display:block;" />
    <strong>Orgo</strong>
    <span style="font-size:.8rem;opacity:.6;">live</span>
  </span>
  <span style="display:inline-flex;align-items:center;gap:.5rem;padding:.4rem .8rem;border:1px dashed var(--docs-border,#2a2a2a);border-radius:10px;opacity:.6;">E2B <span style="font-size:.8rem;">soon</span></span>
  <span style="display:inline-flex;align-items:center;gap:.5rem;padding:.4rem .8rem;border:1px dashed var(--docs-border,#2a2a2a);border-radius:10px;opacity:.6;">Daytona <span style="font-size:.8rem;">soon</span></span>
</div>

MIOSA runs computers on three substrates behind **one** API:

| Source | Where it runs |
|---|---|
| `miosa-cloud` | MIOSA-managed cloud computers |
| `opencomputers` | the user's own hardware ([BYOC](/docs/computers/byoc/)) over an outbound WebSocket |
| **`external`** | **a third-party provider such as Orgo, E2B, Daytona, and similar services** |

This page covers the third option. A user connects a provider key, provider-backed
computers show up inside your MIOSA application, and your product drives them
through the same `computers.*` surface as a native MIOSA Computer. The provider
supplies capacity. MIOSA keeps the product surface, attribution, routing, and
user experience consistent.

Use this when a customer already has a provider account, when you want a fallback
capacity source, or when a specific task needs a provider that your product already
supports.

## The adapter contract

Every provider maps into a normalized computer shape. Your application depends on
the MIOSA Computer API and does not need to branch on each vendor for common actions.

Diagram:
flowchart LR
  H["Your product or agent"] --> EC["MIOSA Computer API"]
  EC --> O["OrgoProvider"]
  EC --> M["MiosaProvider"]
  EC --> X["E2B / Daytona / ..."]
  O --> ORGO["Orgo API"]
  M --> FLEET["MIOSA Cloud"]

```python
class ExternalComputer(abc.ABC):
    @property
    def info(self) -> ComputerInfo: ...
    def exec(self, command, *, timeout=None) -> ExecResult: ...
    def shell_endpoint(self) -> ShellEndpoint: ...                # interactive shell/PTY
    def screenshot(self) -> bytes: ...                            # optional
    def left_click(self, x, y): ...                              # optional
    def write_file(self, path, content): ...                     # optional
    def preview_url(self, port, path="/") -> str: ...            # optional (port ingress)
    def stop(self): ...
    def destroy(self): ...
```

## Provider mapping example

| `ExternalComputer` | Orgo |
|---|---|
| `exec()` | `POST /computers/{id}/bash` → `{output, exit_code}` |
| `python()` | `POST /computers/{id}/exec` |
| `shell_endpoint()` | WebSocket terminal endpoint |
| `screenshot()` | `GET /computers/{id}/screenshot` |
| `left_click/type/key/scroll` | `POST /computers/{id}/{action}` |
| `read_file/write_file` | via `bash` (Orgo's `/files` API is workspace-scoped multipart) |
| `preview_url(port)` | Provider-dependent. Use a MIOSA tunnel when direct ingress is unavailable. |
| `stop/destroy` | `POST /stop`, `DELETE /computers/{id}` |

Some providers expose desktop control but do not expose arbitrary application
ports. In that case, route the port through a <a href="/docs/computers/byoc/#tunnels">MIOSA edge tunnel</a>
so the external computer still serves previews under your domain.

## Orchestrate it with your driver

The computer handle is provider-neutral, so your backend, hosted agent, or custom loop can drive it:

```python
from external_compute import OrgoProvider
from miosa import Miosa

computer = OrgoProvider().create(name="user-123-box")
client = Miosa(api_key=MIOSA_API_KEY)

cmd = client.completions.create(
    model="miosa-coder",
    prompt=f"Emit ONE shell command to: {goal}",
).text.strip()

print(computer.exec(cmd).output)   # runs on the Orgo box
```

```python
# Bind your agent session to the normalized computer handle.
session = optimal.sessions.create(
    resource_type="external_computer",
    exec=computer.exec,
    shell=computer.shell_endpoint(),
)
session.run("set up a node project and start the dev server")
```

```python
from external_compute import ExternalComputer

class MyDriver:
    def run(self, computer: ExternalComputer, goal: str) -> str:
        # your own loop: screenshot, decide, act, repeat
        shot = computer.screenshot()
        computer.left_click(640, 360)
        return computer.exec("echo done").output
```

## Bring your own harness

Building your own agent on your own platform? You don't need our loop — you need
the controls. `tools.py` (and `tools.ts`) expose the computer as standard
tool/function schemas plus a dispatcher, so you drop external-computer control
straight into your own agent:

```python
from external_compute import OrgoProvider
from tools import TOOL_SCHEMAS, dispatch

computer = OrgoProvider().create(name="agent-box")

# advertise the tools to your model (OpenAI-style; tools.anthropic_tools() for Anthropic)
resp = your_llm.create(model=..., tools=TOOL_SCHEMAS, messages=[...])
for call in resp.tool_calls:
    result = dispatch(computer, call.name, call.arguments)   # runs on the box
```

Tools provided: `exec`, `screenshot`, `left_click`, `type`, `key`, `write_file`,
`read_file` — the same primitives the built-in harnesses use. A
`ClaudeComputerUseHarness` (Anthropic computer-use loop) ships in `harness.py`.

## Display it in your UI

Render the computer and the agent's actions back to your users. The
`ExternalComputerPanel` shows status, the latest screenshot, and the tool-call
log — feed it live data from your `platform_server`:

## Set it up

<div style="display:flex;align-items:center;gap:.6rem;margin:.5rem 0;">
  <img src="/integrations/orgo.png" alt="Orgo" width="28" height="25" />
  <strong style="font-size:1.1rem;">Connect Orgo</strong>
</div>

1. **Get a provider API key** from the provider dashboard.
2. **Store it per user, server-side, encrypted.** Never ship it to the browser.
3. **Scope a MIOSA workspace per user** so external boxes roll up to the right tenant for usage and billing.
4. **Instantiate the provider** and hand the computer to your driver:

```python
from external_compute import OrgoProvider

provider = OrgoProvider(api_key=user.orgo_key)   # or ORGO_API_KEY env
computer = provider.create(name=f"user-{user.id}-box")

result = computer.exec("uname -a")               # drives the Orgo box
print(result.output, result.exit_code)
computer.destroy()
```

The provider auto-discovers the user's Orgo workspace, so you don't need to pass
a workspace ID. Override with <code>OrgoProvider(workspace_id=...)</code> if the
account has more than one.

## Benchmarks

MIOSA ships a like-for-like benchmark that drives providers through the
*same* interface: provision/boot, **desktop-ready** (first command accepted),
exec round-trip, and screenshot latency.

### Example provider run (2026-06-09, US client, real API calls)

| metric | orgo | notes |
|---|---|---|
| boot  -  warm pool | **272 ms** | `fromPool` instance |
| boot  -  cold | **3.13 s** | fresh metal instance |
| desktop-ready (first command accepted) | **2.09 s** | |
| exec round-trip (`bash`) p50 / p95 | **100 ms / 116 ms** | |
| python exec p50 | **206 ms** | |
| file write p50 | **100 ms** | via `bash` |
| click (computer-use) p50 | **200 ms** | |
| screenshot p50 | **290 ms - 1.19 s** | varies with capture path |
| clone | ❌ `404` | not available on this plan tier |
| reported specs | 1 vCPU / 4 GB / 1280×720 | `nproc` reports 8 cores |

For reference, MIOSA sandbox snapshot restore boots **about 166 ms p50** in the
current published benchmark (see [Benchmarks](/docs/benchmarks/)). Run the adapter with a `MIOSA_API_KEY` to
print both columns side by side:

```bash
MIOSA_API_KEY=msk_... python benchmark.py --runs 12 --json
```

## Get the code

The full, runnable adapter examples and benchmark live in the repo:


    Provider contract, provider implementations, driver examples, an
    end-to-end demo, and a comparison benchmark.

    [View on GitHub →](https://github.com/Miosa-osa/external-compute-orgo)


```text
examples/external-compute-orgo/
  external_compute/
    provider.py        # the contract: ComputeProvider + ExternalComputer
    orgo_provider.py   # Orgo implementation (verified against the live API)
    miosa_provider.py  # MIOSA implementation for like-for-like comparison
  drivers.py           # probe, model-backed driver, and custom driver examples
  demo.py              # connect -> drive -> teardown
  benchmark.py         # Orgo vs MIOSA on boot/exec/screenshot
```

## See also

- [BYOC / OpenComputers](/docs/computers/byoc/)  -  the other "bring your own" path (your hardware)
- [Computers / Overview](/docs/computers/overview/)  -  the unified computer surface
- [Benchmarks](/docs/benchmarks/)  -  MIOSA's own boot/exec numbers

---

# Preview Tokens

URL: https://miosa.ai/docs/integrations/preview-tokens
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/preview-tokens
Source: src/routes/docs/integrations/preview-tokens/+page.md
Description: Mint short-lived server-side tokens to embed sandbox previews in iframes without exposing your API key to the browser.

# Preview tokens

A preview token (`mp_...`) is a short-lived credential that grants read-only access to a specific sandbox preview. You mint it server-side and pass it to the browser. The browser uses it as the `src` of an `<iframe>`. Your `msk_*` API key never leaves your server.

---

## Why preview tokens exist

Sandbox previews are live HTTP services running inside isolated VMs. To embed one in your product UI, the browser needs to make an authenticated request to the MIOSA preview proxy.

The wrong approach  -  passing your API key to the browser  -  would let any user call the MIOSA API as your account. Preview tokens are the correct boundary: scoped to one sandbox, one port, and a short TTL.

Diagram:
sequenceDiagram
  participant Browser
  participant YourBackend
  participant MiosaAPI
  participant PreviewProxy

  Browser->>YourBackend: GET /embed-url?sandbox_id=sbx_...
  YourBackend->>MiosaAPI: POST /sandboxes/{id}/previews (msk_ key)
  MiosaAPI-->>YourBackend: preview_id
  YourBackend->>MiosaAPI: POST /sandboxes/{id}/previews/{preview_id}/share
  MiosaAPI-->>YourBackend: { share_url, token }
  YourBackend-->>Browser: { embed_url: share_url, expires_in: 3600 }
  Browser->>PreviewProxy: iframe src = share_url (token in URL)
  PreviewProxy-->>Browser: proxied sandbox content

---

## Token format

Preview tokens are opaque strings prefixed `mp_` followed by a base64url-encoded payload:

```
mp_<base64url-encoded-payload>
```

Do not parse or validate the payload in your application code. Treat the token as an opaque string. MIOSA verifies it at the proxy edge on every request.

---

## TTL strategy

| Use case | Recommended TTL |
|---|---|
| Interactive work session | 3 600 s (1 hour)  -  refresh when the user returns |
| Short demo or share link | 900 s (15 minutes) |
| Public share with explicit expiry | Up to 86 400 s (24 hours) |
| Permanent share | No TTL  -  use `sandbox.share.create()` with no expiry, manage revocation manually |

When a token expires, the iframe shows a "session expired" message from the preview proxy. Your UI should catch the `message` event from the iframe and re-mint a token transparently.

---

## Server-side mint flow

```python
from miosa import Miosa

client = Miosa(api_key="msk_live_...")

# 1. Get or create a preview record for the port your app listens on.
previews = client.sandboxes.get("sbx_abc123").preview.list()
preview = next((p for p in previews if p["port"] == 3000), None)
if not preview:
    preview = client.sandboxes.get("sbx_abc123").preview.create(port=3000)

# 2. Mint a time-limited share token.
share = client.sandboxes.get("sbx_abc123").preview.share(
    preview["id"],
    ttl_seconds=3600,
)

embed_url = share["share_url"]   # pass this to the browser
```

```typescript

const client = new Miosa({ apiKey: "msk_live_..." });

// 1. Get or create a preview record for the port your app listens on.
const previews = await client.sandboxes.preview.list("sbx_abc123");
let preview = previews.find((p) => p.port === 3000);
if (!preview) {
  preview = await client.sandboxes.preview.create("sbx_abc123", { port: 3000 });
}

// 2. Mint a time-limited share token.
const share = await client.sandboxes.preview.share("sbx_abc123", preview.id, {
  ttlSeconds: 3600,
});

const embedUrl = share.shareUrl; // pass this to the browser
```

---

## Iframe attachment

Once you have the `embed_url`, set it as the `src` of an `<iframe>`:

```html
<iframe
  src="https://preview.opendesigns.ai/p/sbx_abc123?token=mp_..."
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  style="width: 100%; height: 600px; border: none;"
  title="Design workspace"
></iframe>
```

**`sandbox` attribute guidance:**

| Flag | Required? | Reason |
|---|---|---|
| `allow-scripts` | Yes | Preview content runs JavaScript. |
| `allow-same-origin` | Yes | Lets the preview proxy set session cookies. |
| `allow-forms` | Recommended | Many sandbox apps submit forms. |
| `allow-popups` | Optional | Only if your sandbox app opens new windows. |
| `allow-downloads` | Optional | Only if your sandbox app serves file downloads. |

Do not add `allow-top-navigation`  -  it would let sandbox content redirect your top-level page.

---

## Token refresh

Detect expiry by listening for the `message` event from the iframe:

```javascript
window.addEventListener("message", async (event) => {
  // The preview proxy emits this message when the token expires.
  if (event.data?.type === "miosa:preview:expired") {
    const res = await fetch(`/api/embed-url?sandbox_id=${sandboxId}`);
    const { embed_url } = await res.json();
    document.getElementById("sandbox-frame").src = embed_url;
  }
});
```

---

## Permission scoping

When you mint a token for an end user, scope it to the minimum permissions they need:

```python
token = client.browser_tokens.create(
    workspace_id="550e8400-...",
    project_id="660e8400-...",
    external_user_id="user_42",
    permissions=["sandbox:read", "preview:read"],
    ttl_seconds=3600,
)
```

```typescript
const token = await client.browserTokens.create({
  workspaceId: "550e8400-...",
  projectId: "660e8400-...",
  externalUserId: "user_42",
  permissions: ["sandbox:read", "preview:read"],
  ttlSeconds: 3600,
});
```

Available permission scopes:

| Scope | Grants |
|---|---|
| `sandbox:read` | Read sandbox metadata and state |
| `sandbox:exec` | Run commands inside the sandbox |
| `preview:read` | Embed and view previews |
| `preview:share` | Create public share links |
| `files:read` | Read the sandbox filesystem |
| `files:write` | Write files to the sandbox |

Admin-scoped tokens can delete sandboxes and modify configuration. Reserve those operations for your server-side API key.

---

## Early revocation

Revoke a preview token before it expires  -  for example, when a user logs out or loses access:

```python
client.sandboxes.get("sbx_abc123").preview.revoke_share(preview_id="prev_xyz")
```

```typescript
await client.sandboxes.preview.revokeShare("sbx_abc123", "prev_xyz");
```

---

## See also

- [End-to-end white-label walkthrough](/docs/integrations/whitelabel-saas)
- [Webhooks reference](/docs/integrations/webhooks)
- [Browser Tokens](/docs/platform/browser-tokens)

---

# Webhooks

URL: https://miosa.ai/docs/integrations/webhooks
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/webhooks
Source: src/routes/docs/integrations/webhooks/+page.md
Description: Subscribe to sandbox and deployment lifecycle events, verify HMAC-SHA256 signatures, handle retries, and test locally.

# Webhooks

MIOSA sends HTTP `POST` requests to your endpoint whenever a sandbox or deployment changes state. Use webhooks to update your database, notify users, trigger downstream actions, or bill for compute.

---

## Event taxonomy

### Sandbox events

| Event | Fires when |
|---|---|
| `sandbox.created` | The sandbox row is inserted. The VM may still be booting. |
| `sandbox.running` | The sandbox is fully booted and ready. `external_user_id` is available. |
| `sandbox.paused` | The sandbox was paused due to an idle timeout or an explicit API call. |
| `sandbox.resumed` | A paused sandbox was resumed. |
| `sandbox.destroyed` | The sandbox was permanently deleted. |
| `sandbox.error` | The sandbox failed to boot or encountered a runtime error. |

### Deployment events

| Event | Fires when |
|---|---|
| `deployment.created` | A new deployment was created. |
| `deployment.build_started` | A build started for a new version. |
| `deployment.build_succeeded` | A build finished successfully. |
| `deployment.build_failed` | A build failed. The `error` field contains the failure reason. |
| `deployment.published` | A version was promoted to the active release. |
| `deployment.domain_attached` | A custom domain was verified and attached. |

---

## Payload structure

Every webhook delivery has the same envelope:

```json
{
  "id": "evt_01hzqmrkntq6g9gxnqhvpa8c7t",
  "type": "sandbox.running",
  "created_at": "2026-05-25T14:32:10Z",
  "data": {
    "id": "sbx_01hzq5pnmpgt6vdwp0r8d23c5n",
    "state": "running",
    "external_user_id": "user_42",
    "external_project_id": "proj_opendesigns_1",
    "metadata": {
      "customer_id": "user_42",
      "project_name": "brand-refresh",
      "source": "opendesigns-whitelabel"
    },
    "preview_url": "https://3000-sbx01hzq.sandbox.opendesigns.ai"
  }
}
```

The `id` field is a unique event ID. Use it to deduplicate deliveries.

---

## HMAC-SHA256 signature verification

Every delivery includes a `Miosa-Signature` header:

```
Miosa-Signature: t=1716645130,v1=a3f2c8...
```

- `t`  -  Unix timestamp (seconds) when MIOSA signed the request
- `v1`  -  HMAC-SHA256 hex digest of `"<t>.<raw_body>"`

The signed payload is `timestamp + "." + raw request body bytes`. Verify before parsing the JSON.

Reject events where the timestamp `t` is more than 300 seconds (5 minutes) in the past or future. This prevents replay attacks using captured valid signatures.

```python

def verify_miosa_signature(body: bytes, header: str, secret: str) -> bool:
    """Return True if the signature is valid."""
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = parts["t"]
        received = parts["v1"]
    except (KeyError, ValueError):
        return False

    # Reject stale events.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    signed = f"{timestamp}.{body.decode('utf-8')}"
    expected = hmac.new(
        secret.encode("utf-8"),
        signed.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, received)

# Flask example
from flask import request, jsonify

@app.post("/webhooks/miosa")
def miosa_webhook():
    raw = request.get_data()
    sig = request.headers.get("Miosa-Signature", "")

    if not verify_miosa_signature(raw, sig, WEBHOOK_SECRET):
        return jsonify({"error": "invalid signature"}), 401

    event = request.get_json()
    handle_event(event)
    return jsonify({"ok": True}), 200
```

```typescript

function verifyMiosaSignature(
  rawBody: Buffer,
  header: string,
  secret: string,
): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=") as [string, string]),
  );
  const { t: timestamp, v1: received } = parts;
  if (!timestamp || !received) return false;

  // Reject stale events.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const signed = `${timestamp}.${rawBody.toString("utf8")}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  );
}

// Express example
app.post("/webhooks/miosa", express.raw({ type: "*/*" }), (req: Request, res: Response) => {
  const sig = req.headers["miosa-signature"] as string ?? "";
  if (!verifyMiosaSignature(req.body, sig, process.env.MIOSA_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: "invalid signature" });
  }
  const event = JSON.parse(req.body.toString());
  handleEvent(event);
  res.json({ ok: true });
});
```

```go
package main

    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "math"
    "net/http"
    "strconv"
    "strings"
    "time"
)

func verifyMiosaSignature(body []byte, header, secret string) bool {
    parts := map[string]string{}
    for _, part := range strings.Split(header, ",") {
        kv := strings.SplitN(part, "=", 2)
        if len(kv) == 2 {
            parts[kv[0]] = kv[1]
        }
    }
    ts, ok1 := parts["t"]
    received, ok2 := parts["v1"]
    if !ok1 || !ok2 {
        return false
    }

    tsInt, err := strconv.ParseInt(ts, 10, 64)
    if err != nil || math.Abs(float64(time.Now().Unix()-tsInt)) > 300 {
        return false
    }

    signed := fmt.Sprintf("%s.%s", ts, string(body))
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signed))
    expected := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(expected), []byte(received))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    sig := r.Header.Get("Miosa-Signature")

    if !verifyMiosaSignature(body, sig, webhookSecret) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    // parse and handle body ...
    w.WriteHeader(http.StatusOK)
}
```

---

## Idempotency

MIOSA may deliver the same event more than once (network retries, at-least-once semantics). Make your handler idempotent by storing the event `id` and discarding duplicates:

```python
processed_events = set()  # use a database or cache in production

def handle_event(event: dict) -> None:
    event_id = event["id"]
    if event_id in processed_events:
        return  # duplicate  -  skip
    processed_events.add(event_id)

    match event["type"]:
        case "sandbox.running":
            notify_user(event["data"]["external_user_id"])
        case "sandbox.destroyed":
            release_resources(event["data"]["id"])
        case "sandbox.error":
            alert_oncall(event["data"])
```

---

## Retry policy

| Attempt | Delay |
|---|---|
| 1 (initial) | Immediate |
| 2 | 5 seconds |
| 3 | 30 seconds |
| 4 | 5 minutes |
| 5 | 30 minutes |

MIOSA stops retrying after five attempts. If your endpoint is unreachable for more than 30 minutes, check the webhook delivery log in the MIOSA dashboard.

Return a `2xx` status code within **10 seconds** to acknowledge receipt. If your processing takes longer, acknowledge immediately and handle the event asynchronously.

---

## Register a webhook

```python
hook = client.webhooks.create(
    url="https://opendesigns.ai/webhooks/miosa",
    events=[
        "sandbox.created",
        "sandbox.running",
        "sandbox.paused",
        "sandbox.destroyed",
        "sandbox.error",
    ],
    description="OpenDesigns lifecycle events",
)

# The secret is returned only on creation. Store it immediately.
print(hook["secret"])  # MIOSA_WEBHOOK_SECRET=...
```

```typescript
const hook = await client.webhooks.create({
  url: "https://opendesigns.ai/webhooks/miosa",
  events: [
    "sandbox.created",
    "sandbox.running",
    "sandbox.paused",
    "sandbox.destroyed",
    "sandbox.error",
  ],
  description: "OpenDesigns lifecycle events",
});

// The secret is returned only on creation. Store it immediately.
console.log(hook.secret); // MIOSA_WEBHOOK_SECRET=...
```

The webhook secret is returned once at creation. If you lose it, delete the webhook and create a new one.

---

## Local testing

Use a tunnel to expose your local server during development:

```bash
# Option 1  -  ngrok
ngrok http 8000
# Copy the https URL, set MIOSA_WEBHOOK_URL in .env

# Option 2  -  cloudflared
cloudflared tunnel --url http://localhost:8000
```

Then run the one-time setup script to register the tunnel URL as your webhook endpoint. When you restart the tunnel and get a new URL, update the webhook:

```python
# Update an existing webhook's URL
client.webhooks.update("whk_abc123", url="https://new-tunnel.ngrok.io/webhooks/miosa")
```

---

## See also

- [End-to-end white-label walkthrough](/docs/integrations/whitelabel-saas)
- [Preview Tokens](/docs/integrations/preview-tokens)
- [Sandbox API reference](/docs/api-reference/sandboxes)

---

# White-Label SaaS  -  End-to-End Walkthrough

URL: https://miosa.ai/docs/integrations/whitelabel-saas
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/integrations/whitelabel-saas
Source: src/routes/docs/integrations/whitelabel-saas/+page.md
Description: Build a product like OpenDesigns.ai on MIOSA. Per-user sandboxes, custom domains, iframe embeds, webhooks, usage billing, and quota controls  -  all from scratch to production.

# White-label SaaS  -  end-to-end walkthrough

This walkthrough builds **OpenDesigns**, a design-tool SaaS where each customer gets an isolated workspace. OpenDesigns's end users never see the MIOSA brand: the domain is `opendesigns.ai`, the product name is "OpenDesigns Workspaces", and the failure pages show the OpenDesigns logo.

Everything here maps directly to working code in [`examples/whitelabel-saas`](https://github.com/Miosa-osa/miosa/tree/main/examples/whitelabel-saas).

---

## Prerequisites

- A MIOSA account with a workspace-scoped API key (`msk_w_...`)
- DNS access to your domain (for preview domain setup)
- Python 3.9+ or Node 18+ depending on which code tabs you follow

---

## One-time setup

Run this once after account creation. It is safe to re-run  -  each step checks the current state and skips if already configured.

Diagram:
flowchart LR
  A[Set branding] --> B[Register preview domain]
  B --> C[Add DNS CNAME]
  C --> D[Register webhook]
  D --> E[Store webhook secret]

### Set branding

```python
from miosa import Miosa

client = Miosa(api_key="msk_w_live_...")

client.settings.update_branding(
    product_name="OpenDesigns Workspaces",
    logo_url="https://opendesigns.ai/logo.png",
    favicon_url="https://opendesigns.ai/favicon.ico",
    primary_color="#6366f1",
    support_email="support@opendesigns.ai",
)
```

```typescript

const client = new Miosa({ apiKey: "msk_w_live_..." });

await client.settings.updateBranding({
  productName: "OpenDesigns Workspaces",
  logoUrl: "https://opendesigns.ai/logo.png",
  faviconUrl: "https://opendesigns.ai/favicon.ico",
  primaryColor: "#6366f1",
  supportEmail: "support@opendesigns.ai",
});
```

### Register a preview domain

```python
result = client.custom_domains.create(domain="opendesigns.ai")
print(result["status"])  # "pending_dns"
```

```typescript
const result = await client.customDomains.create({ domain: "opendesigns.ai" });
console.log(result.status); // "pending_dns"
```

Add two wildcard CNAME records at your DNS provider before continuing:

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

Use DNS-only (gray cloud) for these records. Orange-cloud proxying intercepts the TLS handshake and will break preview certificates.

Verify after DNS propagates (typically 1-5 minutes):

```python
status = client.custom_domains.verify("opendesigns.ai")
print(status["verified"])  # True
```

```typescript
const status = await client.customDomains.verify("opendesigns.ai");
console.log(status.verified); // true
```

### Register a webhook

```python
hook = client.webhooks.create(
    url="https://opendesigns.ai/webhooks/miosa",
    events=[
        "sandbox.created",
        "sandbox.running",
        "sandbox.paused",
        "sandbox.destroyed",
        "sandbox.error",
    ],
    description="OpenDesigns lifecycle events",
)

# Copy the secret  -  it is only returned once.
print(f"MIOSA_WEBHOOK_SECRET={hook['secret']}")
```

```typescript
const hook = await client.webhooks.create({
  url: "https://opendesigns.ai/webhooks/miosa",
  events: [
    "sandbox.created",
    "sandbox.running",
    "sandbox.paused",
    "sandbox.destroyed",
    "sandbox.error",
  ],
  description: "OpenDesigns lifecycle events",
});

// Copy the secret  -  it is only returned once.
console.log(`MIOSA_WEBHOOK_SECRET=${hook.secret}`);
```

---

## Per-user provisioning

Create one sandbox per customer project. Pass your own IDs so you can look up, filter, and bill these resources later.

```python

def slug_from_name(name: str) -> str:
    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")[:60] or "project"

sandbox = client.sandboxes.create(
    template_id="miosa-sandbox",
    name=slug_from_name("Brand Refresh 2026"),   # "brand-refresh-2026"
    external_user_id="user_42",                  # your customer's ID
    external_project_id="proj_opendesigns_1",    # your project's ID
    metadata={
        "customer_id": "user_42",
        "project_name": "Brand Refresh 2026",
        "source": "opendesigns-whitelabel",
    },
)

print(sandbox.id)     # "sbx_01hzq5pnmpgt6vdwp0r8d23c5n"
print(sandbox.state)  # "provisioning"  -  becomes "running" in ~2 seconds
```

```typescript
function slugFromName(name: string): string {
  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "project";
}

const sandbox = await client.sandboxes.create({
  templateId: "miosa-sandbox",
  name: slugFromName("Brand Refresh 2026"),   // "brand-refresh-2026"
  externalUserId: "user_42",                 // your customer's ID
  externalProjectId: "proj_opendesigns_1",   // your project's ID
  metadata: {
    customerId: "user_42",
    projectName: "Brand Refresh 2026",
    source: "opendesigns-whitelabel",
  },
});

console.log(sandbox.id);     // "sbx_01hzq5pnmpgt6vdwp0r8d23c5n"
console.log(sandbox.state);  // "provisioning"  -  becomes "running" in ~2s
```

**Field reference:**

| Field | Purpose | Example |
|---|---|---|
| `external_user_id` | Your customer's stable identifier. Used for usage rollup, quota checks, and filtering. | `"user_42"` |
| `external_project_id` | Your project's identifier within a customer. | `"proj_opendesigns_1"` |
| `name` | URL-safe slug that appears in preview URLs until a custom domain is set. | `"brand-refresh-2026"` |
| `metadata` | Arbitrary key-value pairs returned in webhook payloads and API responses. | `&#123;"source": "opendesigns"&#125;` |

---

## Pretty URLs

By default, sandbox previews use `*.sandbox.opendesigns.ai` after you register your preview domain. To give each sandbox a human-readable subdomain, update the slug after creation:

```python
client.sandboxes.update("sbx_01hzq5...", slug="brand-refresh-2026")
# Preview URL becomes:
# https://3000-brand-refresh-2026.sandbox.opendesigns.ai
```

```typescript
await client.sandboxes.update("sbx_01hzq5...", { slug: "brand-refresh-2026" });
// Preview URL becomes:
// https://3000-brand-refresh-2026.sandbox.opendesigns.ai
```

Slugs must be unique within your workspace. If a slug is already taken, MIOSA returns a `409` conflict.

---

## Embed a preview in an iframe
Never expose your API key to the browser. Your backend mints a short-lived preview token; the browser sets it as the `<iframe src>`.

```python
# Step 1: get or create a preview record for port 3000.
previews = client.sandboxes.get("sbx_01hzq5...").preview.list()
preview = next((p for p in previews if p["port"] == 3000), None)
if not preview:
    preview = client.sandboxes.get("sbx_01hzq5...").preview.create(port=3000)

# Step 2: mint a 1-hour share token.
share = client.sandboxes.get("sbx_01hzq5...").preview.share(
    preview["id"],
    ttl_seconds=3600,
)

return jsonify({
    "embed_url": share["share_url"],
    "expires_in": 3600,
})
```

```typescript
// Step 1: get or create a preview record for port 3000.
const previews = await client.sandboxes.preview.list("sbx_01hzq5...");
let preview = previews.find((p) => p.port === 3000);
if (!preview) {
  preview = await client.sandboxes.preview.create("sbx_01hzq5...", { port: 3000 });
}

// Step 2: mint a 1-hour share token.
const share = await client.sandboxes.preview.share("sbx_01hzq5...", preview.id, {
  ttlSeconds: 3600,
});

return res.json({
  embedUrl: share.shareUrl,
  expiresIn: 3600,
});
```

In the browser:

```html
<iframe
  id="workspace-frame"
  src="https://3000-brand-refresh-2026.sandbox.opendesigns.ai?token=mp_..."
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  style="width: 100%; height: 700px; border: none;"
  title="OpenDesigns Workspace"
></iframe>
```

See [Preview Tokens](/docs/integrations/preview-tokens) for token refresh, permission scoping, and early revocation.

---

## Get notified: webhook subscription
The `POST /webhooks/miosa` handler verifies the HMAC-SHA256 signature and dispatches events:

```python

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["MIOSA_WEBHOOK_SECRET"]

def _verify(body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = parts.get("t", ""), parts.get("v1", "")
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        f"{ts}.{body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

@app.post("/webhooks/miosa")
def miosa_webhook():
    raw = request.get_data()
    if not _verify(raw, request.headers.get("Miosa-Signature", "")):
        return jsonify({"error": "invalid signature"}), 401

    event = json.loads(raw)
    match event["type"]:
        case "sandbox.running":
            # Notify customer: their workspace is ready.
            notify_customer(event["data"]["external_user_id"], event["data"]["preview_url"])
        case "sandbox.destroyed":
            # Release reserved resources.
            release_project(event["data"]["id"])
        case "sandbox.error":
            # Alert on-call.
            alert_oncall(event["data"])

    return jsonify({"ok": True}), 200
```

```typescript

const app = express();
const WEBHOOK_SECRET = process.env.MIOSA_WEBHOOK_SECRET!;

function verify(rawBody: Buffer, header: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const { t: ts, v1: sig } = parts;
  if (!ts || !sig) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(sig, "hex"));
}

app.post("/webhooks/miosa", express.raw({ type: "*/*" }), (req, res) => {
  if (!verify(req.body, req.headers["miosa-signature"] as string ?? "")) {
    return res.status(401).json({ error: "invalid signature" });
  }
  const event = JSON.parse(req.body.toString());
  switch (event.type) {
    case "sandbox.running":
      notifyCustomer(event.data.externalUserId, event.data.previewUrl);
      break;
    case "sandbox.destroyed":
      releaseProject(event.data.id);
      break;
  }
  res.json({ ok: true });
});
```

For the complete signature verification spec and retry policy, see [Webhooks](/docs/integrations/webhooks).

---

## Customize after create

Update sandbox settings at any time without recreating the VM:

```python
client.sandboxes.update(
    "sbx_01hzq5...",
    slug="brand-refresh-2026",    # pretty URL slug
    timeout_sec=7200,             # idle timeout (2 hours)
    always_on=False,              # allow idle-pause
    metadata={"phase": "v2"},     # merge into existing metadata
)
```

```typescript
await client.sandboxes.update("sbx_01hzq5...", {
  slug: "brand-refresh-2026",
  timeoutSec: 7200,
  alwaysOn: false,
  metadata: { phase: "v2" },
});
```

---

## Bill by user
Query compute usage keyed to your `external_user_id`. Use this for per-seat billing, usage dashboards, or chargeback reports.

```python
usage = client.usage.get(
    external_user_id="user_42",
    period_start="2026-05-01T00:00:00Z",
    period_end="2026-06-01T00:00:00Z",
)

print(usage["compute_seconds"])  # total sandbox-seconds
print(usage["sandbox_count"])    # distinct sandboxes created
print(usage["cost_usd"])         # dollar amount for billing
```

```typescript
const usage = await client.usage.get({
  externalUserId: "user_42",
  periodStart: "2026-05-01T00:00:00Z",
  periodEnd: "2026-06-01T00:00:00Z",
});

console.log(usage.computeSeconds); // total sandbox-seconds
console.log(usage.sandboxCount);   // distinct sandboxes created
console.log(usage.costUsd);        // dollar amount for billing
```

---

## Per-user quotas

Prevent a single customer from consuming your entire compute budget. Set quotas at the workspace or project level, or enforce them in your own API layer:

```python
# List sandboxes for this user and reject if at the limit.
SANDBOX_LIMIT_PER_USER = 5

existing = client.sandboxes.list(external_user_id="user_42", state="running")
if len(existing) >= SANDBOX_LIMIT_PER_USER:
    return jsonify({"error": "sandbox limit reached"}), 429
```

```typescript
const SANDBOX_LIMIT_PER_USER = 5;

const existing = await client.sandboxes.list({
  externalUserId: "user_42",
  state: "running",
});
if (existing.length >= SANDBOX_LIMIT_PER_USER) {
  return res.status(429).json({ error: "sandbox limit reached" });
}
```

---

## Branded failure pages

502 and 404 errors in previews will show your branding once `product_name` and `logo_url` are set (see [one-time setup](#one-time-setup)). No additional configuration is needed. The preview proxy reads your tenant branding automatically.

---

## Public sharing

Create a public share link for a sandbox preview  -  useful for design reviews or peer feedback:

```python
share = client.sandboxes.get("sbx_01hzq5...").share.create(
    expires_in=3600,  # optional  -  omit for a permanent link
)
print(share["share_url"])  # https://3000-brand-refresh-2026.sandbox.opendesigns.ai/share/...
```

```typescript
const share = await client.sandboxes.share.create("sbx_01hzq5...", {
  expiresIn: 3600,
});
console.log(share.shareUrl);
```

Revoke a share before it expires:

```python
client.sandboxes.get("sbx_01hzq5...").share.revoke(share["id"])
```

```typescript
await client.sandboxes.share.revoke("sbx_01hzq5...", share.id);
```

---

## End-user file tree, terminal, and run buttons

Give your users a native feel with file browsing, terminal, and run-button components backed by the MIOSA SDK. All three require a browser token with the appropriate scopes (see [Preview Tokens  -  permission scoping](/docs/integrations/preview-tokens#permission-scoping)).

### File tree

```typescript

const client = new Miosa({ apiKey: browserToken }); // mp_ token from your backend

async function loadFileTree(sandboxId: string, path = "/workspace") {
  const entries = await client.files.list(sandboxId, path);
  return entries.map((e) => ({
    name: e.name,
    type: e.type,   // "file" | "directory"
    path: e.path,
    size: e.size,
  }));
}
```

### Terminal

```typescript
// Stream terminal output as an async iterable.
const stream = client.exec.stream(sandboxId, "bash", {
  cols: 80,
  rows: 24,
});

for await (const chunk of stream) {
  terminalEmulator.write(chunk.data);
}
```

### Run button

```typescript
// One-shot exec with streaming output.
const result = await client.exec.run(sandboxId, "npm test", {
  workingDir: "/workspace",
  timeoutMs: 30_000,
});

console.log(result.stdout);
console.log(result.exitCode); // 0 = pass
```

---

## Teardown on cancellation

Destroy all sandboxes when a customer cancels their account:

```python
sandboxes = client.sandboxes.list(external_user_id="user_42")
for sandbox in sandboxes:
    client.sandboxes.delete(sandbox["id"])
    print(f"Destroyed {sandbox['id']}")
```

```typescript
const sandboxes = await client.sandboxes.list({ externalUserId: "user_42" });
for (const sandbox of sandboxes) {
  await client.sandboxes.delete(sandbox.id);
  console.log(`Destroyed ${sandbox.id}`);
}
```

---

## End-to-end checklist

- [ ] Set branding: `product_name`, `logo_url`, `support_email`
- [ ] Register preview domain and add DNS CNAMEs
- [ ] Verify DNS propagation
- [ ] Register webhook and store the secret in your environment
- [ ] Create sandboxes with `external_user_id`, `external_project_id`, and `metadata`
- [ ] Mint preview tokens server-side only  -  never expose `msk_*` to the browser
- [ ] Verify HMAC-SHA256 on every webhook delivery
- [ ] Reject stale webhook timestamps (>5 min)
- [ ] Deduplicate webhook events by `event.id`
- [ ] Query usage by `external_user_id` for billing
- [ ] Enforce per-user sandbox quotas before creating
- [ ] Destroy sandboxes on cancellation

---

## See also


    Token format, TTL strategy, iframe attachment, refresh, and permission scoping.

    [Preview Tokens →](/docs/integrations/preview-tokens)


    Full event taxonomy, HMAC verification in 3 languages, idempotency, retries.

    [Webhooks →](/docs/integrations/webhooks)


    Domains, branding, workspace and project scoping, domain precedence.

    [White-Label Setup →](/docs/platform/white-label)


    Ownership fields, external IDs, usage reconciliation.

    [Attribution →](/docs/platform/attribution)

---

# Availability & Roadmap

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: Current MIOSA product availability, what is generally available, what is in hardening, and what is planned next.

# Availability & Roadmap

This page gives customers a clean read on what is ready for production today, what is available for selected partners, and what is still on the roadmap.

Last updated: 2026-06-09. We update this page when a platform capability changes release stage.

## Release stages

| Stage | Meaning |
|---|---|
| **Generally available** | Supported for production use with documented APIs and normal support paths. |
| **Partner preview** | Available to approved customers while we finish polish, SDK parity, or operating runbooks. |
| **In hardening** | Built or partially available, but not ready to promise as a stable public surface. |
| **Planned** | On the roadmap, not available for production use yet. |

## Generally available


    Create isolated Linux workspaces for code generation, build steps, test runs, long-running commands, file operations, and live previews.



    Expose a running process on a public preview URL, with private preview tokens for embedded product experiences.



    Turn a sandbox into a durable deployment version, promote it, list versions, and roll back when needed.



    Use external IDs, browser tokens, custom branding, preview domains, webhooks, and usage rollups to build MIOSA into your own product.


## Partner preview

These surfaces are being used with selected customers while we continue polishing public docs and SDK parity.

| Surface | Current scope |
|---|---|
| **Computers** | Full Linux desktops for browser automation, screenshot loops, and computer-use agents. |
| **Dynamic deployments** | Production server processes created from a sandbox publish. |
| **Tenant deployment domains** | Branded app domains for generated apps, separate from sandbox preview domains. |
| **External computer providers** | Bring third-party computer providers into the same MIOSA computer abstraction. |
| **Evaluations** | Desktop and agent workflow benchmarks using reproducible tasks, traces, and scoring. |

## In hardening

| Area | Status |
|---|---|
| **Desktop computer provisioning** | Desktop images, resume behavior, and stream readiness are being hardened for faster and more predictable starts. |
| **Dynamic runtime routing** | Dynamic runtimes support public serving, health checks, and replacement. We continue tightening route reporting across CLI and API surfaces. |
| **Managed data services** | Postgres, Redis, object storage, auth, and volumes are documented as target surfaces. Production rollout is staged by customer need. |
| **SDK parity** | Python is the deepest SDK today. TypeScript, Go, Java, and Elixir are being brought to the same coverage over time. |
| **Cross-workspace analytics** | Resource attribution is live. Higher-level dashboards and billing views are expanding. |

## Planned

| Capability | Notes |
|---|---|
| Native GPU sandboxes | Planned for workloads that need accelerated inference or rendering. |
| Edge functions | Planned as a deployment target separate from origin runtimes. |
| Native nameservers | Planned for customers who want MIOSA to manage more of the domain lifecycle. |
| OTLP export | Planned for teams that want platform traces in their own observability stack. |
| Test-mode API keys | Planned to separate production billing from integration testing. |

## Deliberate product boundaries

MIOSA is not trying to be a generic Kubernetes replacement, commodity VPS provider, or blockchain platform. The product is focused on AI-generated software, isolated execution, live previews, desktop automation, white-label SaaS infrastructure, and durable deployment.

## See also

- [Benchmarks](/docs/benchmarks/) for measured sandbox and computer readiness.
- [Evaluations](/docs/evaluations/) for agent task scoring and desktop workflow benchmarks.
- [Provider comparison](/docs/integrations/comparison/) for the compute-provider landscape.
- [Changelog](/docs/changelog/) for shipped product changes.

---

# MCP Server

URL: https://miosa.ai/docs/mcp
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/mcp
Source: src/routes/docs/mcp/+page.md
Description: Connect Claude Code, Cursor, Gemini CLI, OpenCode, or any MCP-aware AI client to MIOSA. One-command install, browser-based auth, sandbox + desktop + deploy tools.

# MCP Server

MIOSA ships a public **Model Context Protocol** server at
`https://api.miosa.ai/api/v1/mcp`. Any MCP-aware AI client  -  Claude Code,
Cursor, Gemini CLI, OpenCode, Hermes, custom GPTs  -  can connect with a single
command and immediately gain MIOSA's sandbox + desktop + deploy toolbelt.

```bash
npx -y @miosa/cli mcp install
```

That's it. Browser opens, you log in to MIOSA, and Claude Code is wired.

---

## One-command install (recommended)

```bash
npx -y @miosa/cli mcp install
```

What happens:

1. The CLI starts MIOSA's [device-code flow](/docs/authentication)
2. Your browser opens to **miosa.ai/cli/auth**  -  log in and approve the request
3. The CLI receives a fresh `msk_u_*` user key, scoped to your account
4. It runs `claude mcp add` for you  -  your Claude Code is now connected

Verify:

```bash
claude mcp list
# miosa  https://api.miosa.ai/api/v1/mcp  ✓ Connected
```

Open any Claude Code session and ask:

> Create a MIOSA sandbox, run `python -c "print(2+2)"` inside it, then destroy it.

Claude will discover the tools (`create_sandbox`, `exec`, `destroy_sandbox`)
and run them against your account.

---

## Install for other clients

```bash
npx -y @miosa/cli mcp install
# or, if the `miosa` binary is already on your PATH:
miosa mcp install
```

Install globally if you prefer:

```bash
npm install -g @miosa/cli
miosa mcp install
```

For project-local scope instead of user-global:

```bash
miosa mcp install --scope project
```

```bash
miosa mcp install --client cursor
```

The command prints a JSON snippet to paste into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "miosa": {
      "transport": "http",
      "url": "https://api.miosa.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer msk_u_your_key_here"
      }
    }
  }
}
```

```bash
miosa mcp install --client gemini
```

Prints the equivalent `gemini mcp add` command for you to run.

If you'd rather paste your API key by hand:

1. Sign in at [miosa.ai/dashboard/api-keys](https://miosa.ai/dashboard/api-keys)
   and create a new key (starts with `msk_u_`).
2. Run:

```bash
claude mcp add --transport http --scope user miosa \
  https://api.miosa.ai/api/v1/mcp \
  --header "Authorization: Bearer msk_u_..."
```

```bash
curl -sS -X POST https://api.miosa.ai/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer msk_u_your_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .
```

You should see the full tool catalogue.

---

## What you get  -  the tool catalogue

The hosted MCP exposes MIOSA primitives as MCP tools. All tools are scoped
to your tenant via the bearer token  -  you only ever see and act on your own
resources, with the same plan limits and credit checks as the REST API.

| Tool | Purpose |
|------|---------|
| `create_sandbox` | Boot a Debian 12 microVM (Python 3.12 + Node 20). |
| `create_desktop` | Start a full desktop for browser/GUI work. |
| `list_sandboxes` | List your active computers (sandboxes + desktops). |
| `destroy_sandbox` | Delete a computer. |
| `exec` | Run a shell command. Returns stdout/stderr/exit_code. |
| `exec_python` | Run a Python snippet inline. |
| `read_file` | Read a file from the VM filesystem. |
| `write_file` | Write a file inside the VM. |
| `list_files` | `ls` a directory inside the VM. |

Surface is expanding  -  call `tools/list` to see what's current.

---

## Drop-in skills for Claude Code

If your client supports Anthropic-style **skills** (Claude Code does), drop
these markdown files into `.claude/skills/` to make MCP usage feel native to
your agent. Each skill is a single `.md` file with frontmatter.

```markdown
---
name: miosa-sandbox
description: Use MIOSA microVM sandboxes for safe code execution, package installs, and ephemeral builds. Triggered by: "run code", "test this", "scratch environment", "ephemeral build", "sandbox", or anything that needs a clean Linux box.
---

# MIOSA Sandbox

You have access to MIOSA microVM sandboxes via the `miosa` MCP server.
Use them whenever the user asks you to RUN code (not just write it),
install packages, scrape, or do anything that benefits from a clean Linux
box you can throw away.

## Lifecycle

1. **Create** with `create_sandbox(name="<descriptive-name>")`.
   Sandbox boots in 2-3 seconds (warm pool) or up to 30s (cold).
2. **Poll** with `list_sandboxes` if you need to confirm `status=running`.
3. **Use**: `exec` for shell, `exec_python` for inline Python, `write_file`
   / `read_file` for file I/O, `list_files` to explore.
4. **Destroy** with `destroy_sandbox(sandbox_id=...)` when finished  -
   sandboxes are billed per-minute.

## Tips

- For multi-step work, keep one sandbox alive across calls (cheaper +
  faster than recreating).
- `exec_python` accepts arbitrary Python with stdlib + `requests` +
  `numpy` + `pandas` pre-installed.
- The sandbox has network access  -  `pip install` and `apt-get` both work.
- Persistent state across sandboxes? Use MIOSA volumes (separate API).
```

```markdown
---
name: miosa-desktop
description: Use MIOSA full desktop environments for GUI work  -  browser automation, scraping behind logins, OCR, visual tasks. Triggered by: "open browser", "GUI", "click", "screenshot", "computer use", "browser automation", "desktop".
---

# MIOSA Desktop (Computer Use)

You have access to MIOSA cloud desktops via the `miosa` MCP server. Use
them for any task that benefits from a real GUI: browser automation,
scraping JS-heavy sites, working behind logins, OCR/CAPTCHA loops, or
operating desktop apps.

## Workflow

1. `create_desktop(name="<descriptive-name>", size="medium")`  -  boots
   Debian + Xfce in ~10-20s, returns a computer ID.
2. Wait until `list_sandboxes` shows `status=running`.
3. Drive it: `exec` to launch apps (`firefox`, `xterm`, `gedit`), then  -
   if your tool surface includes them  -  `click`, `type`, `key`, `hotkey`,
   `screenshot`.
4. `destroy_sandbox(sandbox_id=...)` when done.

## Tips

- Screenshot **before AND after** every UI action  -  the visual state is
  your ground truth.
- Coordinate system is screen pixels, top-left = (0, 0). The MIOSA
  desktop defaults to 1280x800.
- Use `hotkey(["ctrl", "l"])` to focus a browser address bar before
  typing a URL.
- For long-running browser sessions, snapshot the desktop and restore
  later instead of recreating (saves boot time and login state).
```

```markdown
---
name: miosa-deploy
description: Promote a MIOSA sandbox to a live deployment with a public URL, custom domain, env vars, and rollback. Triggered by: "deploy", "ship it", "go live", "production", "publish", "make this public".
---

# MIOSA Deploy

When the user wants to take work from a sandbox to a live, public URL,
use the deployment flow. Deployments are versioned, support env vars,
custom domains, and one-click rollback.

## Workflow

1. Get the sandbox working end-to-end first  -  exposed port, app running,
   smoke tests passing. Don't deploy broken code.
2. Promote: today, the hosted MCP exposes sandbox+exec tooling. Use the
   REST `/api/v1/deployments` endpoint (via `exec` of `curl` from inside
   a sandbox, or directly from the user's machine) to create the
   deployment.
3. Once published, share the deployment URL with the user. Don't claim
   "deployed" until you've actually `curl`'d the live URL and got a 200.

## Tips

- Default region is `us-mia`. For other regions, ask the user.
- Custom domain? Use the `domains` API surface to register and verify.
- Env vars are scoped per deployment-environment. Don't bake secrets
  into the code; set them via the API.
```

The skills above live in the [`Miosa-osa/miosa-skills`](https://github.com/Miosa-osa/miosa-skills) repository. To install all five at once:

```bash
git clone https://github.com/Miosa-osa/miosa-skills.git
cp -r miosa-skills/* ~/.claude/skills/
```

See the [Claude Code Skills](/docs/guides/skills/) page for the full skill catalog and customization guide. A `miosa mcp install --with-skills` flag is coming  -  until then, clone or copy the skills directory above.

---

## Drop this into a fresh agent

Paste the block below into a **fresh** Claude Code (or OpenCode / Hermes /
Cursor) session. The agent will pick up everything it needs.

```text
You're connected (or about to connect) to MIOSA  -  a platform that gives
you cloud microVM sandboxes, full Linux desktops, and one-click deploys.

Step 1: If `claude mcp list` does NOT show a 'miosa' server, run:
    npx -y @miosa/cli mcp install

That opens a browser. Ask me (the user) to approve the login. Once the
command finishes, the 'miosa' MCP server is connected.

Step 2: Read https://miosa.ai/docs/mcp end-to-end. The "drop-in skills"
section has three skills (miosa-sandbox, miosa-desktop, miosa-deploy)
that describe how to use the tools properly.

Step 3: From here on, prefer MIOSA sandboxes over your local tools when
the user asks you to RUN code, INSTALL packages, BUILD a project, or
operate a GUI. Use `exec` / `exec_python` / `write_file` / `read_file`
from the 'miosa' MCP.

Step 4: When the user is happy with what you built, deploy it (the
miosa-deploy skill explains how).

If anything fails with HTTP 401, your MCP key has expired  -  run
`miosa mcp install` again.
```

---

## Auth model

The hosted MCP today authenticates with any valid `msk_u_*` user API key
in the `Authorization: Bearer ...` header. Our API key auth layer that
protects every REST endpoint also protects the MCP, so the MCP surface
inherits all existing guarantees: tenant scoping, plan limits, credit
checks, audit logging.

**Coming soon:** MCP-spec OAuth 2.1 + PKCE Dynamic Client Registration, so
clients that prefer the discovery flow can connect with zero manual key
paste. The 401 challenge will include
`WWW-Authenticate: Bearer resource_metadata=...` pointing at the standard
well-known endpoint.

---

## Troubleshooting

Your key is invalid, expired, or revoked. Re-run `miosa mcp install` to mint
a fresh one, or rotate at <https://miosa.ai/dashboard/api-keys>.

Install Claude Code first: <https://claude.com/claude-code>. Then re-run
`miosa mcp install`.

`create_sandbox` returns immediately while the VM boots in the background.
Poll `list_sandboxes` until `status=running`  -  usually 2-3s warm, up to 30s
cold. If it never reaches `running`, the workspace may be over plan limits.
Check <https://miosa.ai/dashboard/plan>.

Your plan caps the number of concurrent sandboxes, or the size you can
boot. Upgrade at <https://miosa.ai/billing>, or destroy unused computers
with `destroy_sandbox`.

---

## Hosted HTTP vs local stdio

| Mode | When to use |
|------|------|
| **Hosted HTTP** (`https://api.miosa.ai/api/v1/mcp`) | Recommended. Works with any modern MCP client. No local install. This is what `miosa mcp install` wires for you. |
| **Local stdio** (`miosa mcp serve` or `pip install miosa-mcp`) | Useful when your client doesn't yet support remote MCP, or you want to wrap the bridge with custom logic. Both modes call the same REST API under the hood. |

Both modes are first-class. The hosted path is just easier to share.

---

# 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://5173-abc12345.sandbox.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

---

# Custom Preview Domains

URL: https://miosa.ai/docs/platform/custom-domains
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/platform/custom-domains
Source: src/routes/docs/platform/custom-domains/+page.md
Description: Serve your sandboxes and computers at <slug>.<your-domain> instead of <slug>.miosa.app  -  one CNAME record, zero dashboard configuration.

Custom preview domains let your sandboxes and computers appear at `<slug>.your-domain.com` instead of `<slug>.miosa.app`. Your users see your brand at every URL, with no MIOSA branding visible.

## Add this CNAME record at your DNS provider

That is the entire setup. One record:

| Field | Value |
|---|---|
| Type | `CNAME` |
| Host | `*` (wildcard) |
| Value | `proxy.miosa.ai` |
| TTL | `300` - `600` seconds |
| Proxy status (Cloudflare only) | **DNS only**  -  gray cloud |

Within a few minutes, visit any sandbox URL at `<slug>.<your-domain>` and MIOSA will auto-bind your domain. No further steps in MIOSA's dashboard required.

If you're using Cloudflare as your DNS provider, make sure the wildcard CNAME has the proxy status set to **DNS only** (gray cloud), not **Proxied** (orange cloud). When proxied, Cloudflare terminates TLS itself and MIOSA never receives the request to issue a certificate  -  your sandbox URLs will fail with a TLS error. Other DNS providers (Route 53, Namecheap, GoDaddy, Porkbun) don't have this issue.

## How it works

You set one CNAME record. The first time someone visits `<slug>.<your-domain>` in your tenant, MIOSA's edge:

1. Detects your domain's CNAME points at us.
2. Looks up the slug  -  confirms it belongs to your tenant.
3. Auto-binds `<your-domain>` to your tenant.
4. Issues a TLS certificate for the wildcard.
5. Routes the request to your sandbox.

**Security note:** Slugs are unguessable UUID prefixes, so only the tenant that owns the sandbox can trigger the auto-bind for a given domain.

## Troubleshooting

**My sandbox URL returns a TLS error or cert warning**

- DNS hasn't propagated yet  -  wait a few minutes.
- If using Cloudflare, verify proxy status is **DNS only** (gray cloud).
- Confirm the record exists:

```bash
dig +short "*.your-domain.com" CNAME
# Expected: proxy.miosa.ai.
```

**My sandbox URL returns 502 or 503**

Your sandbox isn't running, or no HTTP server is listening on the port you're requesting. The DNS chain is correct  -  your sandbox just needs to serve traffic.

**My sandbox URL returns 400 or "URL not connected"**

The slug doesn't match any sandbox in your tenant. Confirm the sandbox is in `running` state and that the slug (first 8 hex chars of the sandbox UUID) matches the leftmost label of the hostname.

## Disconnecting

To stop using your custom domain: remove the CNAME from your DNS provider, or open **Settings → Domains** in MIOSA and click **Disconnect**. After disconnecting, the next request to `<slug>.<your-domain>` will fail to issue a certificate. The domain becomes available to bind to a different tenant after the cache expires.

## Optional  -  explicit registration via Settings → Domains

If you prefer to register your domain in MIOSA before sending traffic (instead of using auto-discovery), open **Settings → Domains** and enter your domain. MIOSA will show you the same CNAME instructions and verify DNS on demand. The end result is identical.

## See also

- [White-Label Setup](/docs/platform/white-label)  -  branding, logo, accent color
- [Domains (Deploy)](/docs/deploy/domains)  -  per-deployment custom domains and TLS details
- [External Attribution](/docs/platform/attribution)  -  scoping resources to your end-users

---

# 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, create workspaces/projects for downstream customers, configure preview and deployment domains separately, then attach exact custom domains where a customer needs their own hostname.

---

## 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[Configure preview domain for sandbox previews]
  F --> G[Configure deployment domain for durable apps]
  G --> H[Attach exact customer domains when needed]
  H --> I[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. URL layers

White-label production has distinct URL layers. Do not mix them:

| Resource | Default URL shape |
|---|---|
| Sandbox preview | `https://{port}-{sandbox_slug}.sandbox.{preview_domain}` |
| Computer desktop | `https://{computer_slug}.computer.miosa.ai/desktop/index.html` |
| Durable deployment | `https://{deployment_slug}.{deployment_domain}` |
| Deployment fallback | `https://{deployment_slug}.{organization_slug}.miosa.app` |
| Exact custom domain | `https://customer-owned.example.com` |

For ClinicIQ, a deployment named `Lead Magnet` defaults to something like:

```text
https://lead-magnet.cliniciq.miosa.app
```

The fallback is always available. If a tenant deployment domain is configured, deployment responses return that branded URL instead. SDKs, CLIs, and frontends should display the returned `public_url` / `url`, not construct hostnames.

## 4. Organization preview domain

Set a tenant preview domain when generated sandbox preview URLs should use your organization's domain instead of the MIOSA fallback.

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. Deployment domain

Set a tenant deployment domain when published apps should use your branded production URL base.

Recommended ClinicIQ setup:

```text
*.sandbox.cliniciq.com  CNAME proxy.miosa.ai
*.apps.cliniciq.com     CNAME proxy.miosa.ai
```

Then generated URLs look like:

| Surface | Example |
|---|---|
| Sandbox preview | `https://5173-sbx01j9x.sandbox.cliniciq.com` |
| Durable deployment | `https://lead-magnet.apps.cliniciq.com` |
| Managed fallback | `https://lead-magnet.cliniciq.miosa.app` |

Current V1 note: public tenant preview-domain routes are exposed. Tenant deployment-domain resolution exists in backend settings/routing; public tenant-level management routes are still operator-managed. Your client code should consume returned deployment `public_url` values.

## 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 | Tenant deployment domain | `lead-magnet.apps.cliniciq.com` |
| 3 | MIOSA managed fallback | `lead-magnet.cliniciq.miosa.app` |

Sandbox preview domains are separate from deployment domains. Computer desktop URLs are separate from both. 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 returned MIOSA fallback URLs until DNS is configured.
- [ ] Configure preview domain if sandbox previews should use your domain.
- [ ] Configure deployment domain if generated apps should use your domain by default.
- [ ] 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.

> **Building a white-label product?** If your goal is to ship a SaaS where your customers never see the MIOSA brand, start with the [White-Label Integrator Guide](/docs/integrations) instead. It covers per-user provisioning, custom domains, iframe embeds, webhooks, and usage billing from scratch.

---

## 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 or tooling installed for your language

```bash
npm install @miosa/cli @miosa/sdk
# or: pnpm add @miosa/cli @miosa/sdk
```

```bash
pip install miosa==1.1.0
# or: pip install miosa  (latest)
# PyPI: https://pypi.org/project/miosa/
```

```elixir
# mix.exs  -  published on Hex.pm: https://hex.pm/packages/miosa
{:miosa, "~> 1.1"}
```

Then run `mix deps.get`.

**Zero-install option  -  just a URL + API key:**

```json
{
  "mcpServers": {
    "miosa": {
      "url": "https://api.miosa.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer msk_u_..."
      }
    }
  }
}
```

Add this to `~/.claude/mcp.json` (Claude Code), Cursor's MCP settings, or Windsurf's `mcp_config.json`. No pip, no npm  -  145 tools appear immediately after a client restart. This is the easiest way to get started.

**Local server (optional):**

```bash
pip install git+https://github.com/Miosa-osa/miosa-mcp.git
```

Or via the TypeScript CLI:

```bash
npx @miosa/cli mcp serve
```

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://5173-abc12345.sandbox.miosa.app
```

```python
preview = sandbox.previews.create(port=3000)
print(preview.url)
# https://5173-abc12345.sandbox.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` | Created an isolated sandbox from the `miosa-node` template |
| `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://5173-abc12345.sandbox.miosa.app?token=mp_...
```

```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://5173-abc12345.sandbox.miosa.app?token=mp_...
```

   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.
- **Build your own product on MIOSA.** The [Platform / White-label overview](/docs/platform/overview/) covers preview tokens, share URLs, tenant branding, per-user quotas, webhook subscriptions, and the audit log  -  everything introduced in 1.1.0.
- **Drop in UI components.** `@miosa/react`, `@miosa/vue`, and `@miosa/svelte` (v0.2.0) provide `MiosaPreview`, `MiosaTerminal`, `MiosaFileTree`, and `MiosaUsage`  -  all handle token minting and SSE reconnect automatically. See [UI Components](/docs/ui-components/).
- **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.
- **Extend Claude Code with MIOSA skills.** 5 pre-built skills at [github.com/Miosa-osa/miosa-skills](https://github.com/Miosa-osa/miosa-skills) give Claude Code sandbox, computer, and deploy primitives. See [Skills](/docs/guides/skills/).
- **API wire format.** [API Reference](/docs/api-reference/) documents every endpoint.

---

# Egress SDK reference

URL: https://miosa.ai/docs/sdks/egress
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/sdks/egress
Source: src/routes/docs/sdks/egress/+page.md
Description: Every Secrets, Connect Accounts, Network Allowlist, and Audit Log SDK method across Python, TypeScript, Go, Java, and Elixir  -  side by side.

# Egress SDK reference

Side-by-side reference for every egress security method across all five MIOSA SDKs. Use this as a lookup table  -  for conceptual background, see the individual feature pages.

---

## Secrets

### `secrets.set`  -  Store a secret

```python
sandbox.secrets.set(
    name: str,
    value: str,
    expose_as_env: str,
    scope: str = "sandbox",            # "sandbox" | "user" | "external_user" | "external_workspace" | "tenant"
    external_user_id: str | None = None,
    external_workspace_id: str | None = None,
)
```

Returns `None`. Raises `MiosaAPIError` on validation failure.

```python
sandbox.secrets.set(
    name="openai_key",
    value=os.environ["MY_OPENAI_KEY"],
    expose_as_env="OPENAI_API_KEY",
)
```

```typescript
await sandbox.secrets.set({
  name: string,
  value: string,
  exposeAsEnv: string,
  scope?: 'sandbox' | 'user' | 'external_user' | 'external_workspace' | 'tenant',
  externalUserId?: string,
  externalWorkspaceId?: string,
}): Promise<void>
```

```typescript
await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});
```

```go
err := sandbox.Secrets.Set(ctx, miosa.SecretSet{
    Name:                string,
    Value:               string,
    ExposeAsEnv:         string,
    Scope:               string,   // "sandbox" | "user" | "external_user" | "external_workspace" | "tenant"
    ExternalUserID:      string,   // optional
    ExternalWorkspaceID: string,   // optional
})
```

```go
err := sandbox.Secrets.Set(ctx, miosa.SecretSet{
    Name:        "openai_key",
    Value:       os.Getenv("MY_OPENAI_KEY"),
    ExposeAsEnv: "OPENAI_API_KEY",
})
```

```java
sandbox.secrets().set(SecretSet.builder()
    .name(String name)
    .value(String value)
    .exposeAsEnv(String exposeAsEnv)
    .scope(String scope)              // optional
    .externalUserId(String id)        // optional
    .externalWorkspaceId(String id)   // optional
    .build());
```

```java
sandbox.secrets().set(SecretSet.builder()
    .name("openai_key")
    .value(System.getenv("MY_OPENAI_KEY"))
    .exposeAsEnv("OPENAI_API_KEY")
    .build());
```

```elixir
Miosa.Secrets.set(sandbox_id, %{
  name: String.t(),
  value: String.t(),
  expose_as_env: String.t(),
  scope: String.t() | nil,               # optional
  external_user_id: String.t() | nil,    # optional
  external_workspace_id: String.t() | nil
})
# Returns {:ok, nil} | {:error, reason}
```

```elixir
{:ok, _} = Miosa.Secrets.set(sandbox.id, %{
  name: "openai_key",
  value: System.get_env("MY_OPENAI_KEY"),
  expose_as_env: "OPENAI_API_KEY"
})
```

---

### `secrets.list`  -  List secrets on a sandbox

Returns metadata only. The `value` field is never returned.

```python
secrets = sandbox.secrets.list()
# Returns List[SecretMeta]
# SecretMeta: name, type, expose_as_env, scope, preview (last 4 chars), last_used_at

for s in secrets:
    print(s.name, s.expose_as_env, s.last_used_at)
```

```typescript
const secrets = await sandbox.secrets.list();
// Returns SecretMeta[]
// SecretMeta: { name, type, exposeAsEnv, scope, preview, lastUsedAt }

for (const s of secrets) {
  console.log(s.name, s.exposeAsEnv, s.lastUsedAt);
}
```

```go
secrets, err := sandbox.Secrets.List(ctx)
// Returns []miosa.SecretMeta

for _, s := range secrets {
    fmt.Println(s.Name, s.ExposeAsEnv, s.LastUsedAt)
}
```

```java
List secrets = sandbox.secrets().list();
for (SecretMeta s : secrets) {
    System.out.println(s.getName() + " " + s.getExposeAsEnv());
}
```

```elixir
{:ok, secrets} = Miosa.Secrets.list(sandbox.id)
Enum.each(secrets, fn s ->
  IO.puts("#{s.name} → #{s.expose_as_env}")
end)
```

---

### `secrets.rotate`  -  Update a secret's value

The placeholder token is unchanged. All sandboxes using this secret pick up the new value on their next request.

```python
sandbox.secrets.rotate("openai_key", new_value="sk-proj-newvalue...")
```

```typescript
await sandbox.secrets.rotate({ name: 'openai_key', newValue: 'sk-proj-newvalue...' });
```

```go
err := sandbox.Secrets.Rotate(ctx, "openai_key", "sk-proj-newvalue...")
```

```java
sandbox.secrets().rotate("openai_key", "sk-proj-newvalue...");
```

```elixir
{:ok, _} = Miosa.Secrets.rotate(sandbox.id, "openai_key", "sk-proj-newvalue...")
```

---

### `secrets.delete`  -  Remove a secret

Removes the binding. The sandbox's env var is unset on the next exec.

```python
sandbox.secrets.delete("openai_key")
```

```typescript
await sandbox.secrets.delete('openai_key');
```

```go
err := sandbox.Secrets.Delete(ctx, "openai_key")
```

```java
sandbox.secrets().delete("openai_key");
```

```elixir
{:ok, _} = Miosa.Secrets.delete(sandbox.id, "openai_key")
```

---

## Connect Accounts (OAuth)

### `secrets.connect`  -  Initiate an OAuth flow

```python
flow = sandbox.secrets.connect(
    provider: str,           # "github" | "google" | "slack" | …
    expose_as_env: str,
    scopes: list[str] | None = None,
)
# Returns OAuthFlow
# OAuthFlow: authorize_url (str), wait_for_completion(timeout: int)

print(flow.authorize_url)
flow.wait_for_completion(timeout=300)
```

```typescript
const flow = await sandbox.secrets.connect({
  provider: string,        // 'github' | 'google' | 'slack' | …
  exposeAsEnv: string,
  scopes?: string[],
});
// Returns OAuthFlow
// OAuthFlow: { authorizeUrl: string, waitForCompletion(opts): Promise<void> }

console.log(flow.authorizeUrl);
await flow.waitForCompletion({ timeoutSec: 300 });
```

```go
flow, err := sandbox.Secrets.Connect(ctx, miosa.OAuthConnect{
    Provider:    string,   // "github" | "google" | "slack"
    ExposeAsEnv: string,
    Scopes:      []string,
})
// flow.AuthorizeURL string
// flow.WaitForCompletion(ctx, timeoutSec int) error

fmt.Println(flow.AuthorizeURL)
err = flow.WaitForCompletion(ctx, 300)
```

```java
OAuthFlow flow = sandbox.secrets().connect(OAuthConnect.builder()
    .provider("github")
    .exposeAsEnv("GITHUB_TOKEN")
    .scopes(List.of("repo", "read:user"))
    .build());

System.out.println(flow.getAuthorizeUrl());
flow.waitForCompletion(Duration.ofSeconds(300));
```

```elixir
{:ok, flow} = Miosa.Secrets.connect(sandbox.id, %{
  provider: "github",
  expose_as_env: "GITHUB_TOKEN",
  scopes: ["repo", "read:user"]
})

IO.puts(flow.authorize_url)
{:ok, _} = Miosa.Secrets.wait_for_oauth(flow.id, timeout: 300)
```

---

### `secrets.reauthorize`  -  Re-run an OAuth flow for an existing connection

Use when a token was revoked or scopes changed.

```python
flow = sandbox.secrets.reauthorize(provider="github")
print(flow.authorize_url)
flow.wait_for_completion(timeout=300)
```

```typescript
const flow = await sandbox.secrets.reauthorize({ provider: 'github' });
await flow.waitForCompletion({ timeoutSec: 300 });
```

```go
flow, err := sandbox.Secrets.Reauthorize(ctx, "github")
err = flow.WaitForCompletion(ctx, 300)
```

```java
OAuthFlow flow = sandbox.secrets().reauthorize("github");
flow.waitForCompletion(Duration.ofSeconds(300));
```

```elixir
{:ok, flow} = Miosa.Secrets.reauthorize(sandbox.id, "github")
{:ok, _} = Miosa.Secrets.wait_for_oauth(flow.id, timeout: 300)
```

---

## Network Allowlist

### `network.allow`  -  Add a host to the allowlist

```python
sandbox.network.allow(
    host: str,                  # e.g. "api.openai.com" or "*.openai.com"
    methods: list[str] | None,  # ["GET", "POST"]  -  None means all
    warn_only: bool = False,    # allow but flag in audit log
)
```

```python
sandbox.network.allow("api.openai.com")
sandbox.network.allow("*.anthropic.com", methods=["POST"])
sandbox.network.allow("api.experimental.io", warn_only=True)
```

```typescript
await sandbox.network.allow(
  host: string,
  opts?: { methods?: string[]; warnOnly?: boolean }
)
```

```typescript
await sandbox.network.allow('api.openai.com');
await sandbox.network.allow('*.anthropic.com', { methods: ['POST'] });
await sandbox.network.allow('api.experimental.io', { warnOnly: true });
```

```go
err := sandbox.Network.Allow(ctx, "api.openai.com", miosa.AllowOpts{})
err = sandbox.Network.Allow(ctx, "*.anthropic.com", miosa.AllowOpts{
    Methods:  []string{"POST"},
})
err = sandbox.Network.Allow(ctx, "api.experimental.io", miosa.AllowOpts{
    WarnOnly: true,
})
```

```java
sandbox.network().allow("api.openai.com");
sandbox.network().allow("*.anthropic.com", AllowOpts.builder().methods(List.of("POST")).build());
```

```elixir
{:ok, _} = Miosa.Network.allow(sandbox.id, "api.openai.com")
{:ok, _} = Miosa.Network.allow(sandbox.id, "*.anthropic.com", methods: ["POST"])
```

---

### `network.deny`  -  Explicitly block a host

Deny rules win over allow rules.

```python
sandbox.network.deny("169.254.169.254")
```

```typescript
await sandbox.network.deny('169.254.169.254');
```

```go
err := sandbox.Network.Deny(ctx, "169.254.169.254")
```

```java
sandbox.network().deny("169.254.169.254");
```

```elixir
{:ok, _} = Miosa.Network.deny(sandbox.id, "169.254.169.254")
```

---

### `network.lockdown` and `network.observe`

```python
sandbox.network.lockdown()   # enforce mode  -  apply allowlist
sandbox.network.observe()    # audit-only  -  log everything, block nothing
```

```typescript
await sandbox.network.lockdown();
await sandbox.network.observe();
```

```go
err := sandbox.Network.Lockdown(ctx)
err = sandbox.Network.Observe(ctx)
```

```java
sandbox.network().lockdown();
sandbox.network().observe();
```

```elixir
{:ok, _} = Miosa.Network.lockdown(sandbox.id)
{:ok, _} = Miosa.Network.observe(sandbox.id)
```

---

### `network.suggestions`  -  Hosts observed in a time window

```python
hosts = sandbox.network.suggestions(since: str = "7d")
# Returns List[HostSuggestion]
# HostSuggestion: host, request_count, last_seen, methods

for h in hosts:
    print(h.host, h.request_count)
```

```typescript
const hosts = await sandbox.network.suggestions({ since?: string });
// Returns HostSuggestion[]
// HostSuggestion: { host, requestCount, lastSeen, methods }
```

```go
hosts, err := sandbox.Network.Suggestions(ctx, miosa.SuggestionsOpts{Since: "7d"})
// returns []miosa.HostSuggestion
```

```java
List hosts = sandbox.network().suggestions(SuggestionsOpts.builder()
    .since("7d").build());
```

```elixir
{:ok, hosts} = Miosa.Network.suggestions(sandbox.id, since: "7d")
```

---

### `network.pending`  -  Blocked hosts since lockdown

```python
pending = sandbox.network.pending()
# Returns List[PendingHost]
# PendingHost: host, request_count, first_seen

for p in pending:
    print(p.host, p.request_count, "blocked")
```

```typescript
const pending = await sandbox.network.pending();
// Returns PendingHost[]
// PendingHost: { host, requestCount, firstSeen }
```

```go
pending, err := sandbox.Network.Pending(ctx)
```

```java
List pending = sandbox.network().pending();
```

```elixir
{:ok, pending} = Miosa.Network.pending(sandbox.id)
```

---

### `network.get_policy`  -  Inspect current mode and rules

```python
policy = sandbox.network.get_policy()
print(policy.mode)         # "observe" | "enforce"
print(policy.allow_rules)  # List of AllowRule
print(policy.deny_rules)   # List of DenyRule
```

```typescript
const policy = await sandbox.network.getPolicy();
console.log(policy.mode);        // 'observe' | 'enforce'
console.log(policy.allowRules);
console.log(policy.denyRules);
```

```go
policy, err := sandbox.Network.GetPolicy(ctx)
fmt.Println(policy.Mode)  // "observe" | "enforce"
```

```java
NetworkPolicy policy = sandbox.network().getPolicy();
System.out.println(policy.getMode());
```

```elixir
{:ok, policy} = Miosa.Network.get_policy(sandbox.id)
IO.puts(policy.mode)
```

---

## Audit Log

### `audit.list`  -  Query audit events

Every row has: `timestamp`, `host`, `method`, `path`, `action`, `status_code`, `duration_ms`, `bytes_in`, `bytes_out`, `request_transforms`, `mcp`.

```python
events = sandbox.audit.list(
    since: str = "1h",                # "15m" | "1h" | "24h" | "7d" | "30d" | ISO8601
    host: str | None = None,          # exact or glob, e.g. "*.openai.com"
    method: str | None = None,        # "GET" | "POST" | …
    action: str | None = None,        # "allow" | "reject" | "stub" | "error"
    limit: int = 100,                 # max 1000
    external_user_id: str | None = None,
    external_workspace_id: str | None = None,
)
# Returns List[AuditEvent]
```

```python
events = sandbox.audit.list(since="1h", host="api.openai.com", action="allow")
for e in events:
    print(e.timestamp, e.host, e.status_code, e.duration_ms, "ms")
```

```typescript
const events = await sandbox.audit.list({
  since?: string,
  host?: string,
  method?: string,
  action?: 'allow' | 'reject' | 'stub' | 'error',
  limit?: number,
  externalUserId?: string,
  externalWorkspaceId?: string,
}): Promise<AuditEvent[]>
```

```typescript
const events = await sandbox.audit.list({ since: '1h', action: 'reject' });
for (const e of events) {
  console.log(e.timestamp, e.host, e.statusCode, e.durationMs, 'ms');
}
```

```go
events, err := sandbox.Audit.List(ctx, miosa.AuditListOpts{
    Since:  "1h",
    Host:   "api.openai.com",
    Action: "allow",
    Limit:  100,
})
for _, e := range events {
    fmt.Println(e.Timestamp, e.Host, e.StatusCode, e.DurationMs, "ms")
}
```

```java
List events = sandbox.audit().list(AuditListOpts.builder()
    .since("1h")
    .host("api.openai.com")
    .action("allow")
    .limit(100)
    .build());

for (AuditEvent e : events) {
    System.out.println(e.getTimestamp() + " " + e.getHost() + " " + e.getStatusCode());
}
```

```elixir
{:ok, events} = Miosa.Audit.list(sandbox.id, since: "1h", host: "api.openai.com", action: "allow")
Enum.each(events, fn e ->
  IO.puts("#{e.timestamp} #{e.host} #{e.status_code} #{e.duration_ms}ms")
end)
```

---

### `audit.tail`  -  Live stream of audit events

Blocks and yields events as they arrive over a WebSocket.

```python
# Blocks forever; break out when needed
for event in sandbox.audit.tail():
    print(event.host, event.action, event.status_code)
    if event.action == "reject":
        break
```

```typescript
for await (const event of sandbox.audit.tail()) {
  console.log(event.host, event.action, event.statusCode);
  if (event.action === 'reject') break;
}
```

```go
stream, err := sandbox.Audit.Tail(ctx)
for {
    event, err := stream.Next()
    if err != nil { break }
    fmt.Println(event.Host, event.Action, event.StatusCode)
    if event.Action == "reject" { break }
}
```

```java
try (AuditStream stream = sandbox.audit().tail()) {
    for (AuditEvent event : stream) {
        System.out.println(event.getHost() + " " + event.getAction());
        if ("reject".equals(event.getAction())) break;
    }
}
```

```elixir
Miosa.Audit.tail(sandbox.id, fn event ->
  IO.puts("#{event.host} #{event.action} #{event.status_code}")
  if event.action == "reject", do: :stop, else: :continue
end)
```

---

### `audit.export`  -  Export as CSV or JSON

```python
sandbox.audit.export(
    since: str = "30d",
    format: str = "csv",   # "csv" | "json"
    path: str,             # local file path
)

sandbox.audit.export(since="30d", format="csv", path="audit-30d.csv")
```

```typescript
await sandbox.audit.export({
  since?: string,
  format: 'csv' | 'json',
  path: string,
}): Promise<void>

await sandbox.audit.export({ since: '30d', format: 'json', path: 'audit.json' });
```

```go
err := sandbox.Audit.Export(ctx, miosa.AuditExportOpts{
    Since:  "30d",
    Format: "csv",
    Path:   "audit-30d.csv",
})
```

```java
sandbox.audit().export(AuditExportOpts.builder()
    .since("30d")
    .format("csv")
    .path("audit-30d.csv")
    .build());
```

```elixir
{:ok, _} = Miosa.Audit.export(sandbox.id, since: "30d", format: "csv", path: "audit-30d.csv")
```

---

## Tenant-level methods

Some operations apply across your entire tenant rather than a single sandbox. These use `client` rather than `sandbox`.

### `client.secrets.set`  -  Scope a secret at tenant or workspace level

```python
# Tenant-wide credential  -  all sandboxes in the tenant resolve it
client.secrets.set(
    name="openai_key",
    value="sk-proj-...",
    scope="tenant",
    expose_as_env="OPENAI_API_KEY",
)

# External-user credential
client.secrets.set(
    name="user_openai_key",
    value="sk-proj-...",
    scope="external_user",
    external_user_id="dr_smith@clinic1.example",
    expose_as_env="OPENAI_API_KEY",
)
```

```typescript
await client.secrets.set({
  name: 'openai_key',
  value: 'sk-proj-...',
  scope: 'tenant',
  exposeAsEnv: 'OPENAI_API_KEY',
});
```

```go
err := client.Secrets.Set(ctx, miosa.SecretSet{
    Name:        "openai_key",
    Value:       "sk-proj-...",
    Scope:       "tenant",
    ExposeAsEnv: "OPENAI_API_KEY",
})
```

```java
client.secrets().set(SecretSet.builder()
    .name("openai_key")
    .value("sk-proj-...")
    .scope("tenant")
    .exposeAsEnv("OPENAI_API_KEY")
    .build());
```

```elixir
{:ok, _} = Miosa.Secrets.set_tenant("openai_key", "sk-proj-...", %{
  scope: "tenant",
  expose_as_env: "OPENAI_API_KEY"
})
```

### `client.audit.list`  -  Tenant-wide audit query

Same parameters as `sandbox.audit.list` plus optional `external_user_id` / `external_workspace_id` filter.

```python
# All activity by one end-user across all sandboxes
events = client.audit.list(
    since="7d",
    external_user_id="dr_smith@clinic1.example",
)

# All activity for one workspace
events = client.audit.list(
    since="30d",
    external_workspace_id="clinic1",
)
```

```typescript
const events = await client.audit.list({
  since: '7d',
  externalUserId: 'dr_smith@clinic1.example',
});
```

```go
events, err := client.Audit.List(ctx, miosa.AuditListOpts{
    Since:          "7d",
    ExternalUserID: "dr_smith@clinic1.example",
})
```

```java
List events = client.audit().list(AuditListOpts.builder()
    .since("7d")
    .externalUserId("dr_smith@clinic1.example")
    .build());
```

```elixir
{:ok, events} = Miosa.Audit.list_tenant(%{since: "7d", external_user_id: "dr_smith@clinic1.example"})
```

---

## See also

- [Secrets  -  Quickstart](/docs/security/secrets)
- [Connect Accounts](/docs/security/connect-accounts)
- [Network Allowlist](/docs/security/network)
- [Audit Log](/docs/security/audit-log)
- [Security troubleshooting](/docs/security/troubleshooting)

---

# 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, "~> 1.1"}
```

Then run `mix deps.get`.

  `miosa` is live on Hex.pm. Documentation: [hexdocs.pm/miosa](https://hexdocs.pm/miosa). The package requires Elixir 1.15+ and OTP 25+.

## What's new in 1.1.0

| Area | What shipped |
|---|---|
| Sandbox lifecycle | `Miosa.Sandboxes.update/3`, `Miosa.Sandboxes.preview_token/3`, `Miosa.Sandboxes.fork/3` |
| Tenant preview domain | `Miosa.Tenant.get_preview_domain/1`, `set_preview_domain/2`, `verify_preview_domain/1`, `delete_preview_domain/1` |
| Tenant branding | `Miosa.Tenant.get_branding/1`, `set_branding/2`, `delete_branding/1` |
| Webhooks | `Miosa.Webhooks.create/2`, `list/1`, `get/2`, `delete/2`, `test/2` |
| Files advanced | `Miosa.Sandbox.Files.tree/3`, `write_many/3`, `watch/2` |
| Sandbox env | `Miosa.Sandbox.Env.list/2`, `set/4`, `delete/3` |
| Processes | `Miosa.Sandbox.Processes.start/3`, `list/2`, `stop/3`, `logs/3` |
| Fork + templates | `Miosa.Sandboxes.fork/3`, `Miosa.SandboxTemplates.*` |
| Usage / quotas | `Miosa.Usage.get/2`, `Miosa.Quotas.set/3`, `get/2`, `delete/2` |
| Audit log | `Miosa.AuditLog.list/2` with cursor pagination |
| Sharing | `Miosa.Sandbox.Share.create/3`, `list/2`, `revoke/3` |
| Workspace members | `Miosa.WorkspaceMembers.*`, `Miosa.WorkspaceInvites.*` |
| Org invites | `Miosa.OrgInvites.*` |

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

## Authentication

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

```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: 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)
```

---

## Phase 1-5 API Reference

### Sandbox lifecycle (Phase 1)

`Miosa.Sandboxes`

```elixir
# Create  -  full options
{:ok, sandbox} = Miosa.Sandboxes.create(client, %{
  name: "my-sandbox",
  slug: "acme-backend",
  external_user_id: "usr_123",
  external_project_id: "proj_456",
  external_workspace_id: "ws_789",
  metadata: %{"env" => "staging"},
  timeout_sec: 300,
  always_on: false,
  idempotency_key: UUID.uuid4()
})

{:ok, sandbox} = Miosa.Sandboxes.get(client, sandbox_id)
{:ok, list}    = Miosa.Sandboxes.list(client)
:ok            = Miosa.Sandboxes.delete(client, sandbox_id)

# Update mutable fields
{:ok, updated} = Miosa.Sandboxes.update(client, sandbox_id, %{
  name: "updated-name",
  slug: "new-slug",
  timeout_sec: 600,
  always_on: true,
  metadata: %{"version" => "2"}
})

# Mint a short-lived preview token
{:ok, token} = Miosa.Sandboxes.preview_token(client, sandbox_id,
  expires_in: 3600,
  scope: "read"
)
# token["token"], token["url"], token["expires_at"]

# Fork from a snapshot or running sandbox
{:ok, new_sb} = Miosa.Sandboxes.fork(client, sandbox_id,
  snapshot_id: "snap_abc",
  name: "forked-sandbox",
  external_user_id: "usr_123"
)

# Wait until ready (streams SSE, falls back to polling)
{:ok, true} = Miosa.Sandboxes.wait_until_ready(client, sandbox_id, timeout: 30)
```

### Tenant preview domain (Phase 1)

`Miosa.Tenant`  -  flat functions, no sub-struct

```elixir
{:ok, info}   = Miosa.Tenant.get_preview_domain(client)
# %{"domain" => "preview.acme.com", "verified_at" => "...", "cname_target" => "..."}

{:ok, _}      = Miosa.Tenant.set_preview_domain(client, "preview.acme.com")
{:ok, result} = Miosa.Tenant.verify_preview_domain(client)
# %{"verified" => true, "target" => "...", "records" => [...]}

{:ok, _}      = Miosa.Tenant.delete_preview_domain(client)
```

### Tenant branding (Phase 1)

`Miosa.Tenant`

```elixir
{:ok, branding} = Miosa.Tenant.get_branding(client)

{:ok, _} = Miosa.Tenant.set_branding(client, %{
  product_name: "Acme AI",
  logo_url: "https://cdn.acme.com/logo.png",
  support_url: "https://acme.com/support",
  support_email: "help@acme.com",
  primary_color: "#ff6600",
  background_color: "#ffffff"
})

{:ok, _} = Miosa.Tenant.delete_branding(client)
```

| Key | Description |
|---|---|
| `product_name` | White-label product name shown in UI |
| `logo_url` | URL to your logo image |
| `support_url` | Support page URL |
| `support_email` | Support email address |
| `primary_color` | Hex color for primary UI accents |
| `background_color` | Hex color for desktop background |

### Webhooks (Phase 1)

`Miosa.Webhooks`

```elixir
{:ok, wh} = Miosa.Webhooks.create(client, %{
  url: "https://example.com/webhooks/miosa",
  events: ["sandbox.created", "sandbox.ready", "sandbox.destroyed"]
})

{:ok, list} = Miosa.Webhooks.list(client)
{:ok, wh}   = Miosa.Webhooks.get(client, wh_id)
{:ok, _}    = Miosa.Webhooks.delete(client, wh_id)
{:ok, _}    = Miosa.Webhooks.test(client, wh_id)
```

**Supported events:** `sandbox.created`, `sandbox.ready`, `sandbox.destroyed`, `sandbox.error`, `computer.started`, `computer.stopped`, `computer.error`

### Files advanced (Phase 2)

`Miosa.Sandbox.Files`

```elixir
# Recursive directory tree
{:ok, tree} = Miosa.Sandbox.Files.tree(client, sandbox_id, path: "/workspace", depth: 5)

# Batch file write
{:ok, result} = Miosa.Sandbox.Files.write_many(client, sandbox_id, [
  %{path: "/workspace/app.ex", content: ~s(IO.puts("hello"))},
  %{path: "/workspace/config.json", content: "{}"}
])

# Watch for file-system changes (SSE with callback)
Miosa.Sandbox.Files.watch(client, sandbox_id, fn event ->
  IO.puts("#{event["event"]} #{event["path"]}")
  :continue
end)
```

### Sandbox environment variables (Phase 2)

`Miosa.Sandbox.Env`

```elixir
{:ok, vars}  = Miosa.Sandbox.Env.list(client, sandbox_id)
{:ok, _}     = Miosa.Sandbox.Env.set(client, sandbox_id, "DATABASE_URL", "postgres://...")
{:ok, _}     = Miosa.Sandbox.Env.delete(client, sandbox_id, "DATABASE_URL")
```

### Processes (Phase 2)

`Miosa.Sandbox.Processes`

```elixir
# Start a long-running background process
{:ok, proc} = Miosa.Sandbox.Processes.start(client, sandbox_id, %{
  command: "npm run dev",
  env: %{"NODE_ENV" => "development"},
  name: "dev-server"
})

{:ok, list} = Miosa.Sandbox.Processes.list(client, sandbox_id)
{:ok, _}    = Miosa.Sandbox.Processes.stop(client, sandbox_id, proc["pid"])
{:ok, logs} = Miosa.Sandbox.Processes.logs(client, sandbox_id, proc["pid"], tail: 100)
```

### Usage and quotas (Phase 3)

`Miosa.Usage`  -  `Miosa.Quotas`

```elixir
# Usage rollup
{:ok, report} = Miosa.Usage.get(client, %{
  external_user_id: "usr_123",
  group_by: "external_user_id",
  period: "30d"
})

# Set per-user quotas
{:ok, quota} = Miosa.Quotas.set(client, "usr_123", %{
  max_sandboxes: 5,
  max_concurrent: 2,
  max_storage_gb: 10,
  max_credit_cents: 10_000
})

{:ok, quota} = Miosa.Quotas.get(client, "usr_123")
{:ok, _}     = Miosa.Quotas.delete(client, "usr_123")
```

### Audit log (Phase 3)

`Miosa.AuditLog`

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

### Sharing (Phase 4)

`Miosa.Sandbox.Share`

```elixir
# Create a public share URL (no API key required to access)
{:ok, share} = Miosa.Sandbox.Share.create(client, sandbox_id, expires_in: 3600)
# share["share_id"], share["share_url"], share["expires_at"]

{:ok, shares} = Miosa.Sandbox.Share.list(client, sandbox_id)
{:ok, _}      = Miosa.Sandbox.Share.revoke(client, sandbox_id, share_id)
```

---

## White-label integrator flow

```elixir
client = Miosa.Client.new(System.fetch_env!("MIOSA_API_KEY"))

# 1. Configure tenant branding once
{:ok, _} = Miosa.Tenant.set_branding(client, %{
  product_name: "Acme AI",
  logo_url: "https://cdn.acme.com/logo.png",
  primary_color: "#ff6600"
})

# 2. Set and verify a custom preview domain
{:ok, _} = Miosa.Tenant.set_preview_domain(client, "preview.acme.com")
{:ok, result} = Miosa.Tenant.verify_preview_domain(client)
IO.inspect(result["verified"])

# 3. Register webhook
{:ok, wh} = Miosa.Webhooks.create(client, %{
  url: "https://api.acme.com/webhooks/miosa",
  events: ["sandbox.created", "sandbox.ready", "sandbox.destroyed"]
})

# 4. Cap per-user resources
{:ok, _} = Miosa.Quotas.set(client, "usr_dr_smith", %{
  max_sandboxes: 3,
  max_concurrent: 1
})

# 5. Create a sandbox attributed to a user + project
{:ok, sandbox} = Miosa.Sandboxes.create(client, %{
  name: "smile-dental",
  external_user_id: "usr_dr_smith",
  external_project_id: "proj_landing_page",
  external_workspace_id: "ws_smile_dental",
  metadata: %{"plan" => "pro"}
})

# 6. Wait until ready, then write files
{:ok, true} = Miosa.Sandboxes.wait_until_ready(client, sandbox.id, timeout: 30)

{:ok, _} = Miosa.Sandbox.Files.write_many(client, sandbox.id, [
  %{path: "/workspace/index.html", content: "<h1>Hello</h1>"}
])

# 7. Mint a preview token for the end user
{:ok, token} = Miosa.Sandboxes.preview_token(client, sandbox.id, expires_in: 3600)
preview_url = token["url"]

# 8. Create a public share link
{:ok, share} = Miosa.Sandbox.Share.create(client, sandbox.id, expires_in: 86_400)
public_url = share["share_url"]

# 9. Query usage
{:ok, report} = Miosa.Usage.get(client, %{
  external_user_id: "usr_dr_smith",
  period: "30d"
})

# 10. Clean up
:ok = Miosa.Computer.destroy(client, sandbox.id)
```

---

## Module reference

Every resource group maps to a dedicated module under the `Miosa` namespace. All public functions accept a `%Miosa.Client{}` as their first argument.

| Module | Key functions |
|---|---|
| `Miosa.Client` | `new/1`, `new/2`, `stream_sse/3` |
| `Miosa.Sandboxes` | `create/2`, `get/2`, `list/1`, `delete/2`, `update/3`, `preview_token/3`, `fork/3`, `wait_until_ready/3` |
| `Miosa.Sandbox.Files` | `write/4`, `read/3`, `list/3`, `delete/3`, `mkdir/3`, `move/4`, `tree/3`, `write_many/3`, `watch/3` |
| `Miosa.Sandbox.Exec` | `run/3`, `bash/3`, `python/3` |
| `Miosa.Sandbox.Events` | `stream/3` |
| `Miosa.Sandbox.Env` | `list/2`, `set/4`, `delete/3` |
| `Miosa.Sandbox.Processes` | `start/3`, `list/2`, `stop/3`, `logs/4` |
| `Miosa.Sandbox.Share` | `create/3`, `list/2`, `revoke/3` |
| `Miosa.Sandbox.Previews` | `create/3`, `list/2`, `share/3`, `destroy/3` |
| `Miosa.Sandbox.Snapshots` | `create/3`, `restore/3`, `list/2` |
| `Miosa.Sandbox.Tags` | `add/3`, `remove/3`, `list/2` |
| `Miosa.Sandbox.Terminal` | `open/2`, `resize/4` |
| `Miosa.SandboxTemplates` | `list/1`, `get/2`, `create/2`, `delete/2` |
| `Miosa.Tenant` | `current/1`, `get_preview_domain/1`, `set_preview_domain/2`, `verify_preview_domain/1`, `delete_preview_domain/1`, `get_branding/1`, `set_branding/2`, `delete_branding/1` |
| `Miosa.Computers` | `create/2`, `get/2`, `list/2`, `update/3`, `delete/2` |
| `Miosa.Computer` | `start/2`, `stop/2`, `restart/2`, `clone/2`, `resize/3`, `move/3`, `destroy/2` |
| `Miosa.Computer.Env` | `list/2`, `create/3`, `update/3`, `delete/3` |
| `Miosa.Computer.Ports` | `list/2`, `create/3`, `update/3`, `delete/3` |
| `Miosa.Computer.AutoStop` | `get/2`, `update/3` |
| `Miosa.Computer.Metrics` | `get/3` |
| `Miosa.Desktop` | `screenshot/2`, `click/4`, `type/3`, `key/3`, `drag/6`, `scroll/5`, `set_wallpaper/3`, `accessibility_tree/2` |
| `Miosa.Workspaces` | `list/1`, `create/2`, `get/2`, `update/3`, `delete/2`, `stats/2`, `usage/3` |
| `Miosa.Webhooks` | `create/2`, `get/2`, `list/1`, `update/3`, `delete/2`, `test/2` |
| `Miosa.Usage` | `get/2`, `current/1`, `sessions/2`, `report/3` |
| `Miosa.Quotas` | `get/2`, `set/3`, `delete/2` |
| `Miosa.AuditLog` | `list/2` |
| `Miosa.ApiKeys` | `create/2`, `get/2`, `list/1`, `revoke/2` |
| `Miosa.Snapshots` | `create/3`, `get/2`, `list/2`, `restore/3`, `delete/2` |
| `Miosa.Deployments` | `create/2`, `get/2`, `list/1`, `update/3`, `delete/2`, `publish/2`, `rollback/3` |
| `Miosa.Databases` | `create/2`, `get/2`, `list/1`, `update/3`, `delete/2`, `credentials/2` |
| `Miosa.Storage` | `create_bucket/2`, `list_buckets/1`, `upload_object/4`, `download_object/3`, `signed_url/4` |
| `Miosa.Volumes` | `create/2`, `get/2`, `list/1`, `resize/3`, `attach/4`, `detach/3`, `delete/2` |
| `Miosa.Completions` | `create/2`, `stream/3` |
| `Miosa.Embeddings` | `create/2` |
| `Miosa.CommandCenter` | `create_session/2`, `get_session/2`, `list_sessions/1`, `cancel_session/2` |
| `Miosa.WorkspaceMembers` | `list/2`, `get/3`, `update/4`, `remove/3` |
| `Miosa.WorkspaceInvites` | `create/3`, `list/2`, `get/3`, `cancel/3`, `accept/2` |
| `Miosa.OrgInvites` | `create/2`, `list/1`, `get/2`, `cancel/2`, `accept/2` |
| `Miosa.Admin.Tenants` | `list/1`, `get/2`, `suspend/2`, `unsuspend/2` |
| `Miosa.Credits` | `balance/1`, `history/2` |
| `Miosa.Error` | struct: `:message`, `:status`, `:code`, `:body` |

---

## Common patterns

### Idempotency key

```elixir
{:ok, sandbox} = Miosa.Sandboxes.create(client, %{
  name: "my-sandbox",
  idempotency_key: UUID.uuid4()
})
```

### 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-osa/miosa-go@v0.4.0
```

  If goproxy has not indexed the release yet, use `GOPROXY=direct go get github.com/Miosa-osa/miosa-go@v0.4.0`.

## What's new in v0.4.0

| Area | What shipped |
|---|---|
| Sandbox lifecycle | `Sandboxes.Update()`, `Sandboxes.PreviewToken()`, `Sandboxes.Fork()` |
| Tenant preview domain | `Tenant.GetPreviewDomain()`, `SetPreviewDomain()`, `VerifyPreviewDomain()`, `DeletePreviewDomain()` |
| Tenant branding | `Tenant.GetBranding()`, `SetBranding()`, `DeleteBranding()` |
| Webhooks | `Webhooks.Create/List/Get/Delete/Test()` |
| Files advanced | `SandboxFiles.Tree()`, `WriteMany()`, `Watch()` |
| Sandbox env | `SandboxEnv.List/Set/Delete()` |
| Processes | `SandboxProcesses.Start/List/Get/Stop/Logs/Stream()` |
| Templates + fork | `SandboxTemplates.*`, `Sandboxes.Fork()` |
| Usage / quotas | `Usage.Get()`, `Quotas.Set/Get/Delete()` |
| Sharing | `SandboxShare.Create/List/Revoke()` |
| Workspace members | `WorkspaceMembers.*`, `WorkspaceInvites.*` |
| Org invites | `OrgInvites.*` |

## First request

```go
package main

    "context"
    "fmt"

    miosa "github.com/Miosa-osa/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-osa/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

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

## Error handling

Use `errors.As` to match typed errors:

```go

    "errors"
    "fmt"
    miosa "github.com/Miosa-osa/miosa-go"
)

_, err := client.Computers.Get(ctx, "nonexistent-id")
if err != nil {
    var notFound *miosa.NotFoundError
    var rateLimit *miosa.RateLimitError
    switch {
    case errors.As(err, &notFound):
        fmt.Println("Computer not found")
    case errors.As(err, &rateLimit):
        fmt.Printf("Rate limited  -  retry after %.0fs\n", rateLimit.RetryAfter)
    default:
        fmt.Println("Error:", err)
    }
}
```

## Streaming events

```go
stream, err := computer.Events.Subscribe(ctx, miosa.EventSubscribeOptions{
    Subscribe: []miosa.EventProducer{
        miosa.ProducerWindow,
        miosa.ProducerFile,
        miosa.ProducerProcess,
    },
    Paths: []string{"/workspace"},
})
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.

---

## Phase 1-5 API Reference

### Sandbox lifecycle (Phase 1)

`client.Sandboxes`  -  `*SandboxesService`

```go
// Create  -  full input struct
sandbox, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{
    Name:                "my-sandbox",
    Slug:                "acme-backend",
    ExternalUserID:      "usr_123",
    ExternalProjectID:   "proj_456",
    ExternalWorkspaceID: "ws_789",
    Metadata:            map[string]interface{}{"env": "staging"},
    TimeoutSec:          300,
    AlwaysOn:            false,
    IdempotencyKey:      uuid.NewString(),
})

sandbox, err = client.Sandboxes.Get(ctx, sandboxID)
list, err    := client.Sandboxes.List(ctx, miosa.SandboxListParams{State: "running"})
err          = client.Sandboxes.Delete(ctx, sandboxID)

// Update mutable fields
updated, err := client.Sandboxes.Update(ctx, sandboxID, miosa.UpdateSandboxInput{
    Name:      "updated-name",
    Slug:      "new-slug",
    TimeoutSec: 600,
    AlwaysOn:  true,
})

// Mint a short-lived preview token
token, err := client.Sandboxes.PreviewToken(ctx, sandboxID, miosa.PreviewTokenInput{
    ExpiresIn: 3600,
    Scope:     "read",
})
// token.Token, token.URL, token.ExpiresAt

// Fork from a snapshot or running sandbox
forked, err := client.Sandboxes.Fork(ctx, sandboxID, miosa.ForkSandboxInput{
    SnapshotID:     "snap_abc",
    Name:           "forked-sandbox",
    ExternalUserID: "usr_123",
})
```

| Field | Type | Description |
|---|---|---|
| `Name` | `string` | Display name |
| `Slug` | `string` | URL-safe identifier |
| `ExternalUserID` | `string` | White-label user attribution |
| `ExternalProjectID` | `string` | White-label project attribution |
| `ExternalWorkspaceID` | `string` | White-label workspace attribution |
| `Metadata` | `map[string]interface{}` | Arbitrary key-value pairs |
| `TimeoutSec` | `int` | Lifetime in seconds |
| `AlwaysOn` | `bool` | Stay alive past idle timeout |
| `IdempotencyKey` | `string` | Deduplication key for retries |

### Tenant preview domain (Phase 1)

`client.Tenant`  -  `*TenantService`

```go
// Get current custom preview domain
info, err := client.Tenant.GetPreviewDomain(ctx)
// info.Domain, info.VerifiedAt, info.CnameTarget

// Set custom preview domain
updated, err := client.Tenant.SetPreviewDomain(ctx, "preview.acme.com")

// Trigger DNS verification
result, err := client.Tenant.VerifyPreviewDomain(ctx)
// result["verified"], result["target"], result["records"]

// Remove custom domain
err = client.Tenant.DeletePreviewDomain(ctx)
```

### Tenant branding (Phase 1)

`client.Tenant`  -  `*TenantService`

```go
// Get current branding
branding, err := client.Tenant.GetBranding(ctx)

// Set branding
updated, err := client.Tenant.SetBranding(ctx, miosa.BrandingData{
    ProductName:     "Acme AI",
    LogoURL:         "https://cdn.acme.com/logo.png",
    SupportURL:      "https://acme.com/support",
    SupportEmail:    "help@acme.com",
    PrimaryColor:    "#ff6600",
    BackgroundColor: "#ffffff",
})

// Reset to platform defaults
err = client.Tenant.DeleteBranding(ctx)
```

### Webhooks (Phase 1)

`client.Webhooks`  -  `*WebhooksService`

```go
// Create a webhook
wh, err := client.Webhooks.Create(ctx, miosa.CreateWebhookInput{
    URL:    "https://example.com/webhooks/miosa",
    Events: []string{"sandbox.created", "sandbox.ready", "sandbox.destroyed"},
})

list, err := client.Webhooks.List(ctx)
wh, err    = client.Webhooks.Get(ctx, whID)
err        = client.Webhooks.Delete(ctx, whID)
err        = client.Webhooks.Test(ctx, whID)
```

**Supported events:** `sandbox.created`, `sandbox.ready`, `sandbox.destroyed`, `sandbox.error`, `computer.started`, `computer.stopped`, `computer.error`

### Files advanced (Phase 2)

`client.SandboxFiles(sandboxID)`  -  `*SandboxFilesService`

```go
files := client.SandboxFiles(sandboxID)

// Recursive directory tree
tree, err := files.Tree(ctx, "/workspace", 5) // path, depth

// Batch file write
result, err := files.WriteMany(ctx, []miosa.WriteFileInput{
    {Path: "/workspace/app.go", ContentBase64: base64.StdEncoding.EncodeToString([]byte("package main"))},
})

// Watch for file-system changes (SSE channel)
events, err := files.Watch(ctx)
if err != nil {
    panic(err)
}
for ev := range events {
    fmt.Println(ev.Type, ev.Data)
}
```

### Sandbox environment variables (Phase 2)

`client.SandboxEnv(sandboxID)`  -  `*SandboxEnvService`

```go
env := client.SandboxEnv(sandboxID)

vars, err := env.List(ctx)
_, err     = env.Set(ctx, []miosa.EnvVar{{Key: "DATABASE_URL", Value: "postgres://..."}})
err        = env.Delete(ctx, "DATABASE_URL")
```

### Processes (Phase 2)

`client.SandboxProcesses(sandboxID)`  -  `*SandboxProcessesService`

```go
procs := client.SandboxProcesses(sandboxID)

// Start a long-running background process
proc, err := procs.Start(ctx, miosa.StartProcessInput{
    Command: "npm run dev",
    Env:     map[string]string{"NODE_ENV": "development"},
    Name:    "dev-server",
})

list, err := procs.List(ctx)
one, err   := procs.Get(ctx, proc.PID)
err        = procs.Stop(ctx, proc.PID)
logs, err  := procs.Logs(ctx, proc.PID, 100)

// Streaming process output (SSE channel)
stream, err := procs.Stream(ctx, proc.PID)
for ev := range stream {
    fmt.Print(ev.Data)
}
```

### Usage and quotas (Phase 3)

`client.Usage`  -  `client.Quotas`

```go
// Usage rollup
report, err := client.Usage.Get(ctx, miosa.UsageParams{
    ExternalUserID: "usr_123",
    GroupBy:        "external_user_id",
    Period:         "30d",
})

// Set per-user quotas
quota, err := client.Quotas.Set(ctx, "usr_123", miosa.QuotaInput{
    MaxSandboxes:    5,
    MaxConcurrent:   2,
    MaxStorageGB:    10,
    MaxCreditCents:  10000,
})

quota, err = client.Quotas.Get(ctx, "usr_123")
err        = client.Quotas.Delete(ctx, "usr_123")
```

### Audit log (Phase 3)

`client.AuditLog`

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

### Sharing (Phase 4)

`client.SandboxShare(sandboxID)`  -  `*SandboxShareService`

```go
share := client.SandboxShare(sandboxID)

// Create a public share URL (no API key required to access)
expiresIn := 3600
data, err := share.Create(ctx, miosa.CreateShareInput{
    ExpiresIn: &expiresIn,
    Scope:     "read",
})
// data.ShareID, data.ShareURL, data.ExpiresAt

shares, err := share.List(ctx)
err          = share.Revoke(ctx, shareID)
```

---

## White-label integrator flow

```go
package main

    "context"
    "fmt"
    "os"

    "github.com/google/uuid"
    miosa "github.com/Miosa-osa/miosa-go"
)

func main() {
    ctx := context.Background()
    client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))

    // 1. Configure tenant branding once
    client.Tenant.SetBranding(ctx, miosa.BrandingData{
        ProductName:  "Acme AI",
        LogoURL:      "https://cdn.acme.com/logo.png",
        PrimaryColor: "#ff6600",
    })

    // 2. Set and verify a custom preview domain
    client.Tenant.SetPreviewDomain(ctx, "preview.acme.com")
    client.Tenant.VerifyPreviewDomain(ctx)

    // 3. Register webhook
    client.Webhooks.Create(ctx, miosa.CreateWebhookInput{
        URL:    "https://api.acme.com/webhooks/miosa",
        Events: []string{"sandbox.created", "sandbox.ready", "sandbox.destroyed"},
    })

    // 4. Set per-user quotas
    client.Quotas.Set(ctx, "usr_dr_smith", miosa.QuotaInput{
        MaxSandboxes:  3,
        MaxConcurrent: 1,
    })

    // 5. Create a sandbox attributed to a user + project
    sandbox, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{
        Name:                "smile-dental",
        ExternalUserID:      "usr_dr_smith",
        ExternalProjectID:   "proj_landing_page",
        ExternalWorkspaceID: "ws_smile_dental",
        Metadata:            map[string]interface{}{"plan": "pro"},
        IdempotencyKey:      uuid.NewString(),
    })
    if err != nil {
        panic(err)
    }

    // 6. Write files
    import64 := func(s string) string {
        return base64.StdEncoding.EncodeToString([]byte(s))
    }
    client.SandboxFiles(sandbox.ID).WriteMany(ctx, []miosa.WriteFileInput{
        {Path: "/workspace/index.html", ContentBase64: import64("<h1>Hello</h1>")},
    })

    // 7. Mint a preview token
    expiresIn := 3600
    token, _ := client.Sandboxes.PreviewToken(ctx, sandbox.ID, miosa.PreviewTokenInput{
        ExpiresIn: expiresIn,
        Scope:     "read",
    })
    fmt.Println("Preview URL:", token.URL)

    // 8. Create a public share link
    shareExpiresIn := 86400
    share, _ := client.SandboxShare(sandbox.ID).Create(ctx, miosa.CreateShareInput{
        ExpiresIn: &shareExpiresIn,
        Scope:     "read",
    })
    fmt.Println("Public URL:", share.ShareURL)

    // 9. Query usage
    report, _ := client.Usage.Get(ctx, miosa.UsageParams{
        ExternalUserID: "usr_dr_smith",
        Period:         "30d",
    })
    fmt.Println(report)

    // 10. Clean up
    client.Sandboxes.Delete(ctx, sandbox.ID)
}
```

---

## Common patterns

### 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,
})
```

### Idempotency key

```go

sandbox, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{
    Name:           "my-sandbox",
    IdempotencyKey: uuid.NewString(),
})
```

### Custom base URL (self-hosted)

```go
client := miosa.NewClient(
    "msk_live_...",
    miosa.WithBaseURL("https://api.your-domain.com/api/v1"),
)
```

---

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, delete, update, previewToken, fork) | ✓ |
| Sandbox files (tree, writeMany, watch) | ✓ |
| Sandbox env, processes, share | ✓ |
| Computers (CRUD + lifecycle) | ✓ |
| Computer sub-resources (terminal, env, ports, volumes, logs, auto-stop, metrics) | ✓ |
| Desktop | ✓ |
| Files (upload, download, list, delete) | ✓ |
| Exec | ✓ |
| Deployments | ✓ |
| Databases (managed Postgres) | ✓ |
| Storage (object storage) | ✓ |
| Volumes | ✓ |
| Custom domains | ✓ |
| Functions / cron jobs / health checks / webhooks | ✓ |
| Sandbox templates | ✓ |
| API keys | ✓ |
| Tenant (plan, preview domain, branding) | ✓ |
| Regions / settings | ✓ |
| Dashboard / analytics / audit log / usage / quotas | ✓ |
| Channels / integrations | ✓ |
| External keys | ✓ |
| MCP | ✓ |
| Models / completions / embeddings | ✓ |
| Command center / builder sessions / community | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | ✓ |
| Workspace members + invites | ✓ |
| Org invites | ✓ |
| Admin | ✓ |
| Snapshots (standalone) | ✓ |
| Credits | ✓ |

---

## 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.4.0</version>
</dependency>
```

```groovy
implementation 'ai.miosa:miosa-sdk:0.4.0'
```

```kotlin
implementation("ai.miosa:miosa-sdk:0.4.0")
```

```scala
libraryDependencies += "ai.miosa" % "miosa-sdk" % "0.4.0"
```

  Available on Maven Central as `ai.miosa:miosa-sdk:0.4.0`.

## What's new in 0.4.0

| Area | What shipped |
|---|---|
| Sandbox lifecycle | `SandboxesResource.create()` with attribution, `update()`, `previewToken()`, `fork()`, `waitUntilReady()` |
| Tenant preview domain | `TenantResource.getPreviewDomain()`, `setPreviewDomain()`, `verifyPreviewDomain()`, `deletePreviewDomain()` |
| Tenant branding | `TenantResource.getBranding()`, `setBranding()`, `deleteBranding()` |
| Webhooks | `WebhooksResource.create/list/get/delete/test()` |
| Files advanced | `SandboxFilesResource.tree()`, `writeMany()`, `watch()` |
| Sandbox env | `SandboxEnvResource.list/set/delete()` |
| Processes | `SandboxProcessesResource.start/list/get/stop/logs()` |
| Templates + fork | `SandboxTemplatesResource.*`, `SandboxesResource.fork()` |
| Usage / quotas | `UsageResource.get()`, `QuotasResource.set/get/delete()` |
| Sharing | `SandboxShareResource.create/list/revoke()` |
| Workspace members | `WorkspaceMembersResource.*`, `WorkspaceInvitesResource.*` |
| Org invites | `OrgInvitesResource.*` |

## 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");
        sandbox.start();

        ExecResult result = sandbox.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:

```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()
);

sub.onEvent(event -> {
    System.out.printf("[%s] %s%n", event.getType(), event.getPayload());
});

// Close when done
sub.close();
```

---

## Phase 1-5 API Reference

### Sandbox lifecycle (Phase 1)

`client.sandboxes()`  -  `SandboxesResource`

```java

// Create  -  simple (defaults to miosa-sandbox template, small size)
Computer sandbox = client.sandboxes().create("my-sandbox");

// Create with explicit size
sandbox = client.sandboxes().create("my-sandbox", "medium");

// Create with white-label attribution
Map<String, String> attribution = Map.of(
    "external_workspace_id", "ws_smile_dental",
    "external_user_id",      "usr_dr_smith",
    "external_project_id",   "proj_landing_page"
);
Map<String, String> metadata = Map.of("plan", "pro");
sandbox = client.sandboxes().create(
    "smile-dental", "small", metadata, attribution
);

// Get, list, delete
Computer found     = client.sandboxes().get(sandboxId);
var list           = client.sandboxes().list();
client.sandboxes().delete(sandboxId);

// Wait until ready (streams SSE, falls back to polling)
boolean ready = client.sandboxes().waitUntilReady(
    sandboxId,
    SandboxesResource.WaitOptions.builder()
        .timeout(Duration.ofSeconds(30))
        .stream(true)
        .build()
);

// Update mutable fields
Map<String, Object> updates = Map.of(
    "name", "updated-name",
    "timeout_sec", 600,
    "always_on", true
);
var updated = client.sandboxes().update(sandboxId, updates);

// Mint a short-lived preview token
Map<String, Object> tokenInfo = client.sandboxes().previewToken(
    sandboxId, 3600, "read"
);
// tokenInfo.get("token"), tokenInfo.get("url"), tokenInfo.get("expires_at")

// Fork from a snapshot or running sandbox
Computer forked = client.sandboxes().fork(sandboxId,
    ForkOptions.builder()
        .snapshotId("snap_abc")
        .name("forked-sandbox")
        .externalUserId("usr_123")
        .build()
);
```

| Argument | Type | Description |
|---|---|---|
| `name` | `String` | Display name |
| `size` | `String` | `"xs"`, `"small"`, `"medium"`, `"large"`, `"xl"` |
| `metadata` | `Map<String, String>` | Arbitrary key-value pairs |
| `attribution` | `Map<String, String>` | External IDs for white-label attribution |

### Tenant preview domain (Phase 1)

`client.tenant()`  -  `TenantResource`

```java
// Get current custom preview domain
Map<String, Object> info = client.tenant().getPreviewDomain();
// info.get("domain"), info.get("verified_at"), info.get("cname_target")

// Set custom preview domain
client.tenant().setPreviewDomain("preview.acme.com");

// Trigger DNS verification
Map<String, Object> result = client.tenant().verifyPreviewDomain();
// result.get("verified"), result.get("target"), result.get("records")

// Remove custom domain
client.tenant().deletePreviewDomain();
```

### Tenant branding (Phase 1)

`client.tenant()`  -  `TenantResource`

```java
// Get current branding
Map<String, Object> branding = client.tenant().getBranding();

// Set branding
client.tenant().setBranding(Map.of(
    "product_name",    "Acme AI",
    "logo_url",        "https://cdn.acme.com/logo.png",
    "support_url",     "https://acme.com/support",
    "support_email",   "help@acme.com",
    "primary_color",   "#ff6600",
    "background_color","#ffffff"
));

// Reset to platform defaults
client.tenant().deleteBranding();
```

| Key | Description |
|---|---|
| `product_name` | White-label product name shown in UI |
| `logo_url` | URL to your logo image |
| `support_url` | Support page URL |
| `support_email` | Support email address |
| `primary_color` | Hex color for primary UI accents |
| `background_color` | Hex color for desktop background |

### Webhooks (Phase 1)

`client.webhooks()`  -  `WebhooksResource`

```java
// Create a webhook
var wh = client.webhooks().create(Map.of(
    "url",    "https://example.com/webhooks/miosa",
    "events", List.of("sandbox.created", "sandbox.ready", "sandbox.destroyed")
));

var list = client.webhooks().list();
var one  = client.webhooks().get(whId);
client.webhooks().delete(whId);

// Send a test ping to verify the endpoint is reachable
client.webhooks().test(whId);
```

**Supported events:** `sandbox.created`, `sandbox.ready`, `sandbox.destroyed`, `sandbox.error`, `computer.started`, `computer.stopped`, `computer.error`

### Files advanced (Phase 2)

`client.sandboxFiles(sandboxId)`  -  `SandboxFilesResource`

```java
var files = client.sandboxFiles(sandboxId);

// Recursive directory tree
Map<String, Object> tree = files.tree("/workspace", true);

// Batch file write
files.writeMany(List.of(
    new FileWrite("/workspace/App.java", "public class App {}"),
    new FileWrite("/workspace/config.json", "{}")
));

// Watch for file-system changes
files.watch(event -> {
    System.out.println(event.getType() + " " + event.getPath());
    return true; // return false to stop watching
});
```

### Sandbox environment variables (Phase 2)

`client.sandboxEnv(sandboxId)`  -  `SandboxEnvResource`

```java
var env = client.sandboxEnv(sandboxId);

List<Map<String, Object>> vars = env.list();
env.set("DATABASE_URL", "postgres://...");
env.delete("DATABASE_URL");
```

### Processes (Phase 2)

`client.sandboxProcesses(sandboxId)`  -  `SandboxProcessesResource`

```java
var procs = client.sandboxProcesses(sandboxId);

// Start a long-running background process
var proc = procs.start("npm run dev", Map.of("NODE_ENV", "development"), "dev-server");

var list = procs.list();
var one  = procs.get(proc.getPid());
procs.stop(proc.getPid());

String logs = procs.logs(proc.getPid(), 100);
```

### Usage and quotas (Phase 3)

`client.usage()`  -  `client.quotas()`

```java
// Usage rollup
var report = client.usage().get(Map.of(
    "external_user_id", "usr_123",
    "group_by",         "external_user_id",
    "period",           "30d"
));

// Set per-user quotas
client.quotas().set("usr_123", Map.of(
    "max_sandboxes",   5,
    "max_concurrent",  2,
    "max_storage_gb",  10,
    "max_credit_cents",10000
));

var quota = client.quotas().get("usr_123");
client.quotas().delete("usr_123"); // revert to tenant default
```

### Audit log (Phase 3)

`client.auditLog()`  -  `AuditLogResource`

```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();
}
```

### Sharing (Phase 4)

`client.sandboxShare(sandboxId)`  -  `SandboxShareResource`

```java
var share = client.sandboxShare(sandboxId);

// Create a public share URL (no API key required to access)
var shareData = share.create(3600, "read");
// shareData.get("share_id"), shareData.get("share_url"), shareData.get("expires_at")

var shares = share.list();
share.revoke(shareId);
```

---

## White-label integrator flow

```java

public class WhiteLabelExample {
    public static void main(String[] args) {
        MiosaClient client = new MiosaClient(System.getenv("MIOSA_API_KEY"));

        // 1. Configure tenant branding once at startup
        client.tenant().setBranding(Map.of(
            "product_name", "Acme AI",
            "logo_url",     "https://cdn.acme.com/logo.png",
            "primary_color","#ff6600"
        ));

        // 2. Set and verify a custom preview domain
        client.tenant().setPreviewDomain("preview.acme.com");
        client.tenant().verifyPreviewDomain();

        // 3. Register webhook for lifecycle events
        client.webhooks().create(Map.of(
            "url",    "https://api.acme.com/webhooks/miosa",
            "events", List.of("sandbox.created", "sandbox.ready", "sandbox.destroyed")
        ));

        // 4. Cap per-user resources
        client.quotas().set("usr_dr_smith", Map.of(
            "max_sandboxes",  3,
            "max_concurrent", 1
        ));

        // 5. Create a sandbox attributed to a user + project
        Map<String, String> attribution = Map.of(
            "external_workspace_id", "ws_smile_dental",
            "external_user_id",      "usr_dr_smith",
            "external_project_id",   "proj_landing_page"
        );
        Computer sandbox = client.sandboxes().create(
            "smile-dental", "small",
            Map.of("plan", "pro"),
            attribution
        );

        // 6. Wait until ready
        boolean ready = client.sandboxes().waitUntilReady(
            sandbox.getId(),
            SandboxesResource.WaitOptions.builder()
                .timeout(Duration.ofSeconds(30))
                .build()
        );

        // 7. Write files
        client.sandboxFiles(sandbox.getId()).writeMany(List.of(
            new FileWrite("/workspace/index.html", "<h1>Hello</h1>")
        ));

        // 8. Mint a preview token for the end user
        var tokenInfo = client.sandboxes().previewToken(sandbox.getId(), 3600, "read");
        String previewUrl = (String) tokenInfo.get("url");
        System.out.println("Preview URL: " + previewUrl);

        // 9. Create a public share link
        var shareData = client.sandboxShare(sandbox.getId()).create(86400, "read");
        String publicUrl = (String) shareData.get("share_url");
        System.out.println("Public URL: " + publicUrl);

        // 10. Query usage
        var report = client.usage().get(Map.of(
            "external_user_id", "usr_dr_smith",
            "period",           "30d"
        ));

        // 11. Clean up
        sandbox.destroy();
    }
}
```

---

## Common patterns

### Async operations

```java

CompletableFuture future = client.sandboxes().createAsync("async-agent");

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();
```

### Webhook verification

```java

boolean verifyWebhook(byte[] payload, String signature, String secret) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
    String expected = HexFormat.of().formatHex(mac.doFinal(payload));
    return MessageDigest.isEqual(expected.getBytes(), signature.getBytes());
}
```

---

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, delete, update, previewToken, fork, waitUntilReady) | ✓ |
| Sandbox files (tree, writeMany, watch) | ✓ |
| Sandbox env, processes, share | ✓ |
| 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 (plan, preview domain, branding) | ✓ |
| Regions / settings | ✓ |
| Dashboard / analytics / audit log / usage / quotas | ✓ |
| Channels / integrations / project integrations | ✓ |
| External keys | ✓ |
| OpenComputers (hosts, jobs, files, tunnels, agents, clusters) | ✓ |
| Admin | ✓ |
| Workspace members + invites | ✓ |
| Org invites | ✓ |
| Snapshots (standalone) | ✓ |
| Builder sessions / community | ✓ |
| Models / completions / embeddings | ✓ |
| MCP | ✓ |
| Credits | ✓ |

---

## 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==1.1.0
```

```bash
uv pip install miosa==1.1.0
```

```bash
poetry add miosa==1.1.0
```

## What's new in 1.1.0

| Area | What shipped |
|---|---|
| Sandbox lifecycle | `create_sandbox` with `slug`, `external_user_id`, `external_project_id`; `sandbox.update()`; `sandbox.preview_token()` |
| Tenant preview domain | `client.tenant.preview_domain.get/set/verify/delete()` |
| Tenant branding | `client.tenant.branding.get/set/delete()` |
| Webhooks | `client.webhooks.create/list/get/delete/test()` |
| Files advanced | `sandbox.files.tree()`, `sandbox.files.write_files()`, `sandbox.files.watch_dir()` |
| Sandbox env | `sandbox.env.list/set/delete()` |
| Processes | `sandbox.processes.start/list/stop/logs()` |
| Templates + fork | `client.sandbox_templates.*`, `client.sandboxes.fork()` |
| Usage / quotas | `client.usage.get()`, `client.quotas.get/set/delete()` |
| Audit log | `client.audit_log.list()` |
| Tenant events (SSE) | `client.events.stream(tenant_wide=True)` |
| Sharing | `sandbox.share.create/list/revoke()` |

## 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 default headers (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
```

---

## Phase 1-5 API Reference

### Sandbox lifecycle (Phase 1)

`client.sandboxes`  -  `sandbox` handle returned by `create()`

```python
# Create  -  full signature
sandbox = client.sandboxes.create(
    image="miosa-sandbox",          # template image
    name="my-sandbox",              # optional display name
    slug="acme-backend",            # optional URL-safe identifier
    external_user_id="usr_123",     # white-label user attribution
    external_project_id="proj_456", # white-label project attribution
    external_workspace_id="ws_789", # white-label workspace attribution
    metadata={"env": "staging"},    # arbitrary key-value pairs
    timeout_sec=300,                # sandbox lifetime in seconds
    always_on=False,                # keep alive past idle timeout
    vcpus=1,
    memory_mb=512,
    idempotency_key="uuid-v4",      # safe for retries
)

sandbox = client.sandboxes.get(sandbox_id)
sandboxes = client.sandboxes.list(state="running")
client.sandboxes.destroy(sandbox_id)

# Update mutable fields on an existing sandbox
sandbox.update({
    "name": "updated-name",
    "slug": "new-slug",
    "timeout_sec": 600,
    "always_on": True,
    "metadata": {"version": "2"},
})

# Mint a short-lived preview token
token_info = sandbox.preview_token(expires_in=3600)
# Returns: {"token": "mp_...", "url": "https://...", "expires_at": "..."}

# Fork from an existing snapshot or running sandbox
new_sandbox = client.sandboxes.fork(
    sandbox_id,
    snapshot_id="snap_abc",   # optional
    name="forked-sandbox",
)
```

| Parameter | Type | Description |
|---|---|---|
| `name` | `str` | Display name |
| `slug` | `str` | URL-safe identifier |
| `external_user_id` | `str` | White-label user attribution |
| `external_project_id` | `str` | White-label project attribution |
| `external_workspace_id` | `str` | White-label workspace attribution |
| `metadata` | `dict` | Arbitrary key-value pairs |
| `timeout_sec` | `int` | Lifetime in seconds |
| `always_on` | `bool` | Stay alive past idle timeout |
| `idempotency_key` | `str` | Deduplication key for retries |

### Tenant preview domain (Phase 1)

`client.tenant.preview_domain`

```python
# Get current custom preview domain
info = client.tenant.preview_domain.get()
# Returns: {"domain": "preview.acme.com", "verified_at": "...", "cname_target": "..."}

# Set custom preview domain
client.tenant.preview_domain.set("preview.acme.com")

# Trigger DNS verification
result = client.tenant.preview_domain.verify()
# Returns: {"verified": true, "target": "...", "records": [...]}

# Remove custom domain
client.tenant.preview_domain.delete()
```

### Tenant branding (Phase 1)

`client.tenant.branding`

```python
# Get current branding
branding = client.tenant.branding.get()

# Set branding (all keys optional)
client.tenant.branding.set({
    "product_name": "Acme AI",
    "logo_url": "https://cdn.acme.com/logo.png",
    "support_url": "https://acme.com/support",
    "support_email": "help@acme.com",
    "primary_color": "#ff6600",
    "background_color": "#ffffff",
})

# Reset to platform defaults
client.tenant.branding.delete()
```

| Key | Description |
|---|---|
| `product_name` | White-label product name shown in UI |
| `logo_url` | URL to your logo image |
| `support_url` | Support page URL |
| `support_email` | Support email address |
| `primary_color` | Hex color for primary UI accents |
| `background_color` | Hex color for desktop background |

### Webhooks (Phase 1)

`client.webhooks`

```python
# Create a webhook
wh = client.webhooks.create(
    url="https://example.com/webhooks/miosa",
    events=["sandbox.created", "sandbox.ready", "sandbox.destroyed"],
)

# List, get, delete
whs = client.webhooks.list()
wh  = client.webhooks.get(wh_id)
client.webhooks.delete(wh_id)

# Send a test event to verify the endpoint is reachable
client.webhooks.test(wh_id)
```

**Supported events:** `sandbox.created`, `sandbox.ready`, `sandbox.destroyed`, `sandbox.error`, `computer.started`, `computer.stopped`, `computer.error`

### Files advanced (Phase 2)

`sandbox.files`

```python
# Recursive directory tree
tree = sandbox.files.tree("/workspace", recursive=True)

# Batch file write
sandbox.files.write_files([
    FileWriteItem(path="/workspace/app.py", data="print('hello')"),
    FileWriteItem(path="/workspace/config.json", data=b'{"debug": true}'),
])

# Watch for file-system changes (SSE iterator)
for event in sandbox.files.watch_dir("/workspace"):
    print(event.event, event.path)  # "modified", "/workspace/app.py"
    # event.event: "created" | "modified" | "deleted" | "renamed"
    # event.old_path: set when event == "renamed"
```

### Sandbox environment variables (Phase 2)

`sandbox.env`

```python
# List all env vars
vars = sandbox.env.list()

# Set a variable
sandbox.env.set("DATABASE_URL", "postgres://...")

# Delete a variable
sandbox.env.delete("DATABASE_URL")
```

### Processes (Phase 2)

`sandbox.processes`

```python
# Start a long-running background process
proc = sandbox.processes.start("npm run dev", env={"NODE_ENV": "development"})
# Returns ProcessInfo with pid, status, started_at

# List all running processes
procs = sandbox.processes.list()

# Stop a process (SIGTERM then SIGKILL)
sandbox.processes.stop(proc.pid)

# Get tail of process output
logs = sandbox.processes.logs(proc.pid, tail=100)
```

### Usage and quotas (Phase 3)

`client.usage`  -  `client.quotas`

```python
# Usage rollup  -  filter by user or group by dimension
report = client.usage.get(
    external_user_id="usr_123",
    group_by="external_user_id",   # or "external_project_id", "workspace_id"
    period="30d",                  # or pass start=/end= ISO timestamps
)
# Returns: {"period_start": "...", "period_end": "...", "results": [...]}

# Current period summary
summary = client.usage.current()

# Set per-user quotas
client.quotas.set(
    "usr_123",
    max_sandboxes=5,
    max_concurrent=2,
    max_storage_gb=10,
    max_credit_cents=10000,  # $100.00
)

# Get current quotas + live usage for a user
quota = client.quotas.get("usr_123")

# Revert to tenant default
client.quotas.delete("usr_123")
```

### Audit log (Phase 3)

`client.audit_log`

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

### Tenant-wide event stream (Phase 3)

```python
# SSE stream of all events across the tenant (requires admin scope)
for event in client.events.stream(tenant_wide=True):
    print(event.type, event.data)
```

### Sharing (Phase 4)

`sandbox.share`

```python
# Create a public share URL (no API key required to access)
share = sandbox.share.create(expires_in=3600)
# Returns: {"share_id": "ms_...", "share_url": "https://...", "expires_at": "...", "scope": "read"}

# List active shares
shares = sandbox.share.list()

# Revoke a share
sandbox.share.revoke(share["share_id"])
```

---

## 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)
sandboxes = client.sandboxes.list(status="running")   # filter: status, name
sandboxes = client.sandboxes.list(name="my-dev")
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",                       # "xs" | "small" | "medium" | "large" | "xl"  -  default: "small"
    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")  # also accepts: status="running", name="dev"
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.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)

# 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"])

# Clipboard
text = client.desktop.get_clipboard(computer_id)
client.desktop.set_clipboard(computer_id, text="Hello, World!")

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

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

# Observability
stats = client.workspaces.stats(workspace_id)
usage = client.workspaces.usage(workspace_id, window="7d", granularity="day")
```

### Tenant / Settings / Regions

`client.tenant`  -  `client.settings`  -  `client.regions`

```python
# Tenant plan + counters
plan = client.tenant.current()

# 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")
```

### Webhooks

`client.webhooks`

```python
wh   = client.webhooks.create(url="https://example.com/hook", events=["sandbox.created", "sandbox.ready"])
wh   = client.webhooks.get(wh_id)
whs  = client.webhooks.list()
client.webhooks.update(wh_id, events=["sandbox.created", "sandbox.destroyed"])
client.webhooks.delete(wh_id)
client.webhooks.test(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)
```

### Models / Completions / Embeddings

`client.models`  -  `client.completions`  -  `client.embeddings`

```python
# Completions (hosted 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)

# Embeddings
result  = client.embeddings.create(model="nomic-embed-text", input="The quick brown fox")
vectors = result.embeddings  # list[list[float]]
```

---

## White-label integrator flow

This is the marquee pattern for platforms building on MIOSA: create sandboxes on behalf of end users, scope by project, and expose previews without sharing API keys.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# 1. Configure tenant branding once
client.tenant.branding.set({
    "product_name": "Acme AI",
    "logo_url": "https://cdn.acme.com/logo.png",
    "primary_color": "#ff6600",
})

# 2. Optionally set a custom preview domain so previews appear on your domain
client.tenant.preview_domain.set("preview.acme.com")
client.tenant.preview_domain.verify()

# 3. Register a webhook to track lifecycle events
client.webhooks.create(
    url="https://api.acme.com/webhooks/miosa",
    events=["sandbox.created", "sandbox.ready", "sandbox.destroyed"],
)

# 4. Set per-user quotas before provisioning
client.quotas.set(
    "usr_dr_smith",
    max_sandboxes=3,
    max_concurrent=1,
)

# 5. Create a sandbox attributed to a specific user + project
sandbox = client.sandboxes.create(
    image="miosa-sandbox",
    name="smile-dental",
    external_user_id="usr_dr_smith",
    external_project_id="proj_landing_page",
    external_workspace_id="ws_smile_dental",
    metadata={"plan": "pro"},
)

# 6. Write files and run a build
sandbox.files.write_files([
    FileWriteItem(path="/workspace/index.html", data="<h1>Hello</h1>"),
])
result = sandbox.run("echo build done")

# 7. Mint a preview token for the end user (no API key needed on their end)
token = sandbox.preview_token(expires_in=3600)
preview_url = token["url"]   # share this with the end user

# 8. Create a public share link
share = sandbox.share.create(expires_in=86400)
public_url = share["share_url"]

# 9. Query usage per project
report = client.usage.get(
    external_user_id="usr_dr_smith",
    period="30d",
)

# 10. Clean up
sandbox.destroy()
```

---

## 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 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",
    external_project_id="proj_api",
)
```

### Idempotency key

```python

sandbox = client.sandboxes.create(
    image="miosa-sandbox",
    idempotency_key=str(uuid.uuid4()),
)
```

### Pagination

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

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

---

## 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@1.1.0
```

```bash
pnpm add @miosa/sdk@1.1.0
```

```bash
yarn add @miosa/sdk@1.1.0
```

```bash
bun add @miosa/sdk@1.1.0
```

```typescript

```

## What's new in 1.1.0

| Area | What shipped |
|---|---|
| Sandbox lifecycle | `slug`, `externalUserId`, `externalProjectId` on create; `sandbox.update()`; `sandbox.previewToken()` |
| Tenant preview domain | `client.tenant.previewDomain.get/set/verify/delete()` |
| Tenant branding | `client.tenant.branding.get/set/delete()` |
| Webhooks | `client.webhooks.create/list/get/delete/test()` |
| Files advanced | `sandbox.files.tree()`, `sandbox.files.writeMany()`, `sandbox.files.watch()` |
| Sandbox env | `sandbox.env.list/set/delete()` |
| Processes | `sandbox.processes.start/list/get/stop/logs/stream()` |
| Templates + fork | `client.sandboxTemplates.*`, `sandbox.fork()` |
| Usage / quotas | `client.usage.get()`, `client.quotas.get/set/delete()` |
| Audit log | `client.auditLog.list()` |
| Tenant events (SSE) | `client.events.stream({ tenantWide: true })` |
| Sharing | `sandbox.share.create/list/revoke()` |
| Workspace members | `client.workspaceMembers.*`, `client.workspaceInvites.*` |
| Org invites | `client.orgInvites.*` |

## 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" },
});
```

## 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 RateLimitError) {
    console.log(`Rate limited  -  retry after ${err.retryAfter}s`);
  } else if (err instanceof MiosaError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}
```

## Streaming events

`sandbox.events.stream()` returns an `AsyncIterableIterator`:

```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"].includes(type ?? "")) break;
}
```

---

## Phase 1-5 API Reference

### Sandbox lifecycle (Phase 1)

```typescript

// Create  -  full signature
const sandbox = await client.sandboxes.create({
  templateId: "miosa-sandbox",       // template image
  name: "my-sandbox",                // optional display name
  slug: "acme-backend",              // optional URL-safe identifier
  externalUserId: "usr_123",         // white-label user attribution
  externalProjectId: "proj_456",     // white-label project attribution
  externalWorkspaceId: "ws_789",     // white-label workspace attribution
  metadata: { env: "staging" },      // arbitrary key-value pairs
  timeoutSec: 300,                   // sandbox lifetime in seconds
  alwaysOn: false,                   // keep alive past idle timeout
  idempotencyKey: randomUUID(),      // safe for retries
});

const found = await client.sandboxes.get(sandboxId);
const list  = await client.sandboxes.list({ state: "running" });
await client.sandboxes.destroy(sandboxId);

// Update mutable fields
await sandbox.update({
  name: "updated-name",
  slug: "new-slug",
  timeoutSec: 600,
  alwaysOn: true,
  metadata: { version: "2" },
});

// Mint a short-lived preview token
const tokenInfo = await sandbox.previewToken({ expiresIn: 3600 });
// Returns: { token: "mp_...", url: "https://...", expiresAt: "..." }

// Fork from a snapshot or running sandbox
const forked = await sandbox.fork({ snapshotId: "snap_abc", name: "forked" });
```

| Parameter | Type | Description |
|---|---|---|
| `name` | `string` | Display name |
| `slug` | `string` | URL-safe identifier |
| `externalUserId` | `string` | White-label user attribution |
| `externalProjectId` | `string` | White-label project attribution |
| `externalWorkspaceId` | `string` | White-label workspace attribution |
| `metadata` | `Record<string, unknown>` | Arbitrary key-value pairs |
| `timeoutSec` | `number` | Lifetime in seconds |
| `alwaysOn` | `boolean` | Stay alive past idle timeout |
| `idempotencyKey` | `string` | Deduplication key for retries |

### Tenant preview domain (Phase 1)

`client.tenant.previewDomain`

```typescript
// Get current custom preview domain
const info = await client.tenant.previewDomain.get();
// { domain: "preview.acme.com", verifiedAt: "...", cnameTarget: "..." }

// Set custom preview domain
await client.tenant.previewDomain.set("preview.acme.com");

// Trigger DNS verification
const result = await client.tenant.previewDomain.verify();
// { verified: true, target: "...", records: [...] }

// Remove custom domain
await client.tenant.previewDomain.delete();
```

### Tenant branding (Phase 1)

`client.tenant.branding`

```typescript
// Get current branding
const branding = await client.tenant.branding.get();

// Set branding
await client.tenant.branding.set({
  productName: "Acme AI",
  logoUrl: "https://cdn.acme.com/logo.png",
  supportUrl: "https://acme.com/support",
  supportEmail: "help@acme.com",
  primaryColor: "#ff6600",
  backgroundColor: "#ffffff",
});

// Reset to platform defaults
await client.tenant.branding.delete();
```

### Webhooks (Phase 1)

`client.webhooks`

```typescript
// Create a webhook
const wh = await client.webhooks.create({
  url: "https://example.com/webhooks/miosa",
  events: ["sandbox.created", "sandbox.ready", "sandbox.destroyed"],
});

const list = await client.webhooks.list();
const one  = await client.webhooks.get(wh.id);
await client.webhooks.delete(wh.id);

// Send a test ping to verify the endpoint is reachable
await client.webhooks.test(wh.id);
```

**Supported events:** `sandbox.created`, `sandbox.ready`, `sandbox.destroyed`, `sandbox.error`, `computer.started`, `computer.stopped`, `computer.error`

### Files advanced (Phase 2)

`sandbox.files`

```typescript
// Recursive directory tree
const tree = await sandbox.files.tree("/workspace", { recursive: true });

// Batch file write
await sandbox.files.writeMany([
  { path: "/workspace/app.ts", content: 'console.log("hello")' },
  { path: "/workspace/config.json", content: new TextEncoder().encode('{}') },
]);

// Watch for file-system changes (SSE async iterator)
for await (const event of sandbox.files.watch()) {
  console.log(event.type, event.path); // "modified", "/workspace/app.ts"
}
```

### Sandbox environment variables (Phase 2)

`sandbox.env`

```typescript
const vars = await sandbox.env.list();
await sandbox.env.set("DATABASE_URL", "postgres://...");
await sandbox.env.delete("DATABASE_URL");
```

### Processes (Phase 2)

`sandbox.processes`

```typescript
// Start a long-running background process
const proc = await sandbox.processes.start({
  command: "npm run dev",
  env: { NODE_ENV: "development" },
});

const list = await sandbox.processes.list();
const one  = await sandbox.processes.get(proc.pid);
await sandbox.processes.stop(proc.pid);

const logs = await sandbox.processes.logs(proc.pid);

// Streaming process output (SSE)
for await (const line of sandbox.processes.stream(proc.pid)) {
  process.stdout.write(line.data ?? "");
}
```

### Usage and quotas (Phase 3)

`client.usage`  -  `client.quotas`

```typescript
// Usage rollup
const report = await client.usage.get({
  externalUserId: "usr_123",
  groupBy: "externalUserId",   // or "externalProjectId", "workspaceId"
  period: "30d",               // or pass start/end ISO strings
});

// Set per-user quotas
await client.quotas.set("usr_123", {
  maxSandboxes: 5,
  maxConcurrent: 2,
  maxStorageGb: 10,
  maxCreditCents: 10000,  // $100.00
});

const quota = await client.quotas.get("usr_123");
await client.quotas.delete("usr_123"); // revert to tenant default
```

### Audit log (Phase 3)

`client.auditLog`

```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);
```

### Tenant-wide event stream (Phase 3)

```typescript
for await (const event of client.events.stream({ tenantWide: true })) {
  console.log(event.type, event.data);
}
```

### Sharing (Phase 4)

`sandbox.share`

```typescript
// Create a public share URL
const share = await sandbox.share.create({ expiresIn: 3600 });
// { shareId: "ms_...", shareUrl: "https://...", expiresAt: "...", scope: "read" }

const shares = await sandbox.share.list();
await sandbox.share.revoke(share.shareId);
```

---

## White-label integrator flow

```typescript

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

// 1. Configure tenant branding once at startup
await client.tenant.branding.set({
  productName: "Acme AI",
  logoUrl: "https://cdn.acme.com/logo.png",
  primaryColor: "#ff6600",
});

// 2. Set a custom preview domain
await client.tenant.previewDomain.set("preview.acme.com");
await client.tenant.previewDomain.verify();

// 3. Register webhook for lifecycle events
await client.webhooks.create({
  url: "https://api.acme.com/webhooks/miosa",
  events: ["sandbox.created", "sandbox.ready", "sandbox.destroyed"],
});

// 4. Cap per-user resources
await client.quotas.set("usr_dr_smith", {
  maxSandboxes: 3,
  maxConcurrent: 1,
});

// 5. Create a sandbox attributed to a user + project
const sandbox = await client.sandboxes.create({
  templateId: "miosa-sandbox",
  name: "smile-dental",
  externalUserId: "usr_dr_smith",
  externalProjectId: "proj_landing_page",
  externalWorkspaceId: "ws_smile_dental",
  metadata: { plan: "pro" },
  idempotencyKey: randomUUID(),
});

// 6. Write files and execute a build
await sandbox.files.writeMany([
  { path: "/workspace/index.html", content: "<h1>Hello</h1>" },
]);
const result = await sandbox.exec.run("echo build done");

// 7. Mint a preview token for the end user
const tokenInfo = await sandbox.previewToken({ expiresIn: 3600 });
const previewUrl = tokenInfo.url; // share with the end user

// 8. Create a public share link
const share = await sandbox.share.create({ expiresIn: 86400 });
const publicUrl = share.shareUrl;

// 9. Query usage
const report = await client.usage.get({
  externalUserId: "usr_dr_smith",
  period: "30d",
});

// 10. Clean up
await sandbox.destroy();
```

---

## Common patterns

### Idempotency key

```typescript

const sandbox = await client.sandboxes.create({
  templateId: "miosa-sandbox",
  idempotencyKey: randomUUID(),
});
```

### Parallel sandbox creation

```typescript
const [sb1, sb2] = await Promise.all([
  client.sandboxes.create({ name: "worker-a" }),
  client.sandboxes.create({ name: "worker-b" }),
]);
```

### 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;
}
```

---

## Resource coverage

| Resource group | Available |
|---|---|
| Sandboxes (create, get, list, destroy, exec, events, files, previews, tags, snapshots) | ✓ |
| Sandbox Phase 1-4 (update, previewToken, fork, env, processes, share) | ✓ |
| 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 (plan, preview domain, branding) | ✓ |
| Regions / settings | ✓ |
| Dashboard / analytics / audit log / usage / quotas | ✓ |
| 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 | ✓ |
| Workspace members + invites | ✓ |
| Org invites | ✓ |
| Snapshots (standalone) | ✓ |
| Credits | ✓ |

---

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

---

# Security

URL: https://miosa.ai/docs/security
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security
Source: src/routes/docs/security/+page.md
Description: Built-in credential vault, outbound network controls, and audit log on every MIOSA sandbox and computer. No setup. Free on all plans.

# Security

Every MIOSA Sandbox and Computer ships with a built-in security boundary. **No setup. No add-on SKU. Free on every plan.**

Three things you can use whenever you need them:

| Feature | What it does | Page |
|---|---|---|
| **Secrets** | Store your API keys in MIOSA  -  sandboxes see opaque placeholders, the real values stay encrypted at rest | [Secrets](/docs/security/secrets) |
| **Connect Accounts** | OAuth-based credential connection (GitHub, Google, Slack, …) instead of pasting raw tokens | [Connect Accounts](/docs/security/connect-accounts) |
| **Network Allowlist** | Watch what your sandbox calls; lock it down to an approved list when you're ready | [Network](/docs/security/network) |
| **Audit Log** | Every outbound call is logged automatically  -  searchable, exportable, live-tail | [Audit Log](/docs/security/audit-log) |

## Getting started in 60 seconds

Nothing to install. Nothing to configure globally. Each Computer / Sandbox already has the three tabs.

### 1. Add a credential

Open any Sandbox or Computer → **Secrets** tab → **+ Add Secret**

```
Name:         openai_key
Value:        sk-proj-...   ← your real key
Expose as:    OPENAI_API_KEY
```

Or via SDK (Python  -  same shape in TypeScript / Go / Java / Elixir):

```python
sandbox.secrets.set(
    name="openai_key",
    value="sk-proj-...",
    expose_as_env="OPENAI_API_KEY",
)
```

Inside the sandbox, `process.env.OPENAI_API_KEY` is now an opaque `miosa-tok-…` placeholder. Your existing code uses it as normal. The real key is swapped in at the network boundary on the way out.

→ Full walkthrough: [Secrets](/docs/security/secrets)

### 2. Use your code unchanged

```python

requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
    json={...},
)
```

That's it. OpenAI sees your real `sk-…`. Your sandbox never does. No code change.

### 3. (Optional) Check what you called + lock it down

After your sandbox has been running for a while:

- **Audit Log tab**  -  live-tail every outbound call. Filter by host, status, time.
- **Network tab**  -  see the auto-built list of hosts you've contacted. One click to enforce-mode with that list as the allowlist.

Both are opt-in. Audit-only is the default until you decide to lock down.

→ See [Network Allowlist](/docs/security/network) for the lockdown workflow.

### Want to wire up GitHub / Google / Slack instead of pasting tokens?

→ [Connect Accounts](/docs/security/connect-accounts)  -  OAuth flow that handles refresh automatically.

### Building a white-label product on top of MIOSA?

Your end-users don't need MIOSA accounts  -  credentials can be scoped to your own `external_user_id`.

→ [White-label Credentials](/docs/security/white-label)

---

## Your code doesn't change

The whole design rule for MIOSA Security: **your existing code keeps working.**

```python

# This code is identical with or without MIOSA Secrets:
response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
    json={...},
)
```

What changes is *the value* of `OPENAI_API_KEY`. Without Secrets, it's your real `sk-...` key. With Secrets, it's an opaque placeholder like `miosa-tok-7f2a8c...`. The MIOSA proxy substitutes the real key on the way out. OpenAI sees the real key. Your sandbox never does.

## Three guarantees

New sandboxes do not block anything. The proxy watches and logs but never gets in the way. You only enter "enforce" mode by explicitly clicking Lock Down  -  and it's reversible in one click.

Once saved, secret values are encrypted with ChaCha20-Poly1305. They are unsealed only at the moment the proxy needs to swap them into an outbound request. Nobody  -  including MIOSA engineers  -  can re-read a stored value via the API or UI.

`.env` files still work. `tenant_provider_keys` and `workspace_env_vars` still work. MIOSA Secrets adds a new layer; it doesn't replace anything that exists today.

## Where to go next

- **First time using this?** Start with [Secrets  -  Quickstart](/docs/security/secrets).
- **Want to wire up OAuth (GitHub etc.)?** Read [Connect Accounts](/docs/security/connect-accounts).
- **Want to lock down outbound traffic?** Read [Network Allowlist](/docs/security/network).
- **Building a white-label product on MIOSA?** Read [White-label Credentials](/docs/security/white-label).

## Glossary

**Placeholder token**
An opaque string (format: `miosa-tok-<hex>`) that MIOSA injects into a sandbox's environment in place of a real credential. The proxy swaps the placeholder with the real value on every outbound request. The placeholder is unique per binding  -  it cannot be brute-forced to discover the real key.

**OAuth Connect**
A MIOSA feature that lets you authorize a third-party account (GitHub, Google, Slack, …) via the standard OAuth 2.0 flow instead of pasting a static API key. MIOSA stores the resulting access and refresh tokens, refreshes them automatically, and exposes the current valid access token to the sandbox as a placeholder env var.

**Resolver scope walk**
The ordered lookup MIOSA performs when a sandbox makes an outbound request and the proxy needs to match a placeholder to a real credential. The proxy checks scopes in this priority order: (1) direct sandbox binding, (2) user-scoped secret, (3) external_user-scoped secret, (4) external_workspace-scoped secret, (5) MIOSA workspace secret, (6) tenant-wide secret. First match wins. If nothing matches, the placeholder passes through unchanged and the upstream API call fails (the intended safe behavior).

## Real-world example  -  OpenAI customer-support agent in 5 minutes

This is the complete setup for an AI agent that uses OpenAI safely. Run these five commands and you're done.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

# 1. Create sandbox
sandbox = client.sandboxes.create(template="python-ds")

# 2. Store the OpenAI key  -  sandbox never sees the real value
sandbox.secrets.set(
    name="openai_key",
    value=os.environ["MY_OPENAI_KEY"],
    expose_as_env="OPENAI_API_KEY",
)

# 3. Lock down to only api.openai.com
sandbox.network.allow("api.openai.com")
sandbox.network.lockdown()

# 4. Run the agent  -  uses $OPENAI_API_KEY exactly like normal
result = sandbox.exec("""
python3 -c "

resp = requests.post(
    'https://api.openai.com/v1/chat/completions',
    headers={'Authorization': f'Bearer {os.environ[\"OPENAI_API_KEY\"]}'},
    json={'model': 'gpt-4o-mini', 'messages': [{'role': 'user', 'content': 'Hello!'}]}
)
print(resp.json()['choices'][0]['message']['content'])
"
""")
print(result.stdout)

# 5. Check the audit trail
events = sandbox.audit.list(since="5m")
for e in events:
    print(e.host, e.action, e.status_code)
```

```typescript

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

// 1. Create sandbox
const sandbox = await client.sandboxes.create({ template: 'python-ds' });

// 2. Store the OpenAI key
await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});

// 3. Lock down
await sandbox.network.allow('api.openai.com');
await sandbox.network.lockdown();

// 4. Run the agent
const result = await sandbox.exec(`
python3 -c "

resp = requests.post(
    'https://api.openai.com/v1/chat/completions',
    headers={'Authorization': f'Bearer {os.environ[\"OPENAI_API_KEY\"]}'},
    json={'model': 'gpt-4o-mini', 'messages': [{'role': 'user', 'content': 'Hello!'}]}
)
print(resp.json()['choices'][0]['message']['content'])
"
`);
console.log(result.stdout);

// 5. Audit trail
const events = await sandbox.audit.list({ since: '5m' });
for (const e of events) {
  console.log(e.host, e.action, e.statusCode);
}
```

## Troubleshooting

**My sandbox's env var contains a placeholder but the API returns 401.**
The proxy couldn't match the placeholder in the outbound request header. Confirm the SDK puts the token in `Authorization: Bearer ...`. See [troubleshooting #1](/docs/security/troubleshooting#1-secret-value-is-not-being-swapped--outbound-request-uses-the-raw-placeholder).

**I enabled lockdown and nothing works.**
Call `sandbox.network.pending()` to see the blocked hosts, then allow them. Or revert with `sandbox.network.observe()` while you diagnose.

**I can't see any audit rows.**
The audit log records outbound calls only. If the sandbox hasn't made any outbound requests, the log is empty. Trigger a call and re-query.

**I see "Reconnect needed" on a GitHub secret.**
The OAuth token was revoked by the user or expired. Call `sandbox.secrets.reauthorize(provider="github")` to re-run the OAuth dance. See [Connect Accounts troubleshooting](/docs/security/troubleshooting#4-github-oauth-refresh-failing--sandbox-gets-401-on-apigithubcom).

For the full list of issues and fixes, see the [Security troubleshooting hub](/docs/security/troubleshooting).

---

# Audit Log

URL: https://miosa.ai/docs/security/audit-log
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/audit-log
Source: src/routes/docs/security/audit-log/+page.md
Description: Every outbound call your sandbox makes is logged. Live-tail, filter, export.

# Audit Log

Every outbound call from your sandbox is recorded automatically. No setup. The Audit Log tab on each sandbox/computer is the source of truth for "what did my workload actually do on the network?"

## What's in each row

| Column | Description |
|---|---|
| `timestamp` | When the request happened (microsecond precision) |
| `host` | Upstream hostname |
| `method` | GET, POST, PUT, … |
| `path` | URL path (query string redacted) |
| `action` | `allow`, `reject`, `stub`, `error`, `client_cancel` |
| `status_code` | Upstream response code (or 0 if no response) |
| `duration_ms` | Wall-clock time |
| `bytes_in` / `bytes_out` | Volume |
| `request_transforms` | Which transforms fired (secrets, allowlist, header allowlist, …) |
| `mcp` | MCP message trace, when the call was an MCP JSON-RPC request |

## Live tail

The Audit Log tab streams new events in real time over WebSocket. New rows appear at the top as your sandbox makes calls.

## Filtering

In the UI, use the filter bar to scope by:

- **Time range**  -  last hour, 24h, 7d, 30d, custom
- **Host**  -  exact or wildcard
- **HTTP method**
- **Action**  -  show only blocked, only allowed, only errors
- **Transform**  -  show only requests that swapped a particular secret, or only MCP tool calls
- **Status code**  -  show only 4xx, only 5xx, etc.

All filters are URL-shareable.

## From the SDK

```python
# List recent events
events = sandbox.audit.list(
    since="1h",
    host="api.openai.com",
    action="allow",
    limit=100,
)

for e in events:
    print(e.timestamp, e.host, e.method, e.status_code, e.duration_ms)

# Live tail (blocks; yields events as they arrive)
for event in sandbox.audit.tail():
    print(event.host, event.action)
    if event.action == "reject":
        break

# Tenant-wide audit (admin-scoped key required)
events = client.audit.list(
    since="24h",
    external_user_id="dr_smith@clinic1",
)
```

```typescript
const events = await sandbox.audit.list({
  since: '1h',
  host: 'api.openai.com',
  action: 'allow',
  limit: 100,
});

for (const e of events) {
  console.log(e.timestamp, e.host, e.method, e.statusCode, e.durationMs);
}

for await (const event of sandbox.audit.tail()) {
  console.log(event.host, event.action);
  if (event.action === 'reject') break;
}
```

```go
events, err := sandbox.Audit.List(ctx, miosa.AuditListOpts{
    Since:  "1h",
    Host:   "api.openai.com",
    Action: "allow",
    Limit:  100,
})
for _, e := range events {
    fmt.Println(e.Timestamp, e.Host, e.Method, e.StatusCode, e.DurationMs)
}

// Live tail
stream, err := sandbox.Audit.Tail(ctx)
for {
    event, err := stream.Next()
    if err != nil { break }
    fmt.Println(event.Host, event.Action)
    if event.Action == "reject" { break }
}

// Tenant-wide
events, err = client.Audit.List(ctx, miosa.AuditListOpts{
    Since:          "24h",
    ExternalUserID: "dr_smith@clinic1",
})
```

```java
List events = sandbox.audit().list(AuditListOpts.builder()
    .since("1h")
    .host("api.openai.com")
    .action("allow")
    .limit(100)
    .build());

for (AuditEvent e : events) {
    System.out.println(e.getTimestamp() + " " + e.getHost() + " " + e.getStatusCode());
}

// Live tail
try (AuditStream stream = sandbox.audit().tail()) {
    for (AuditEvent event : stream) {
        System.out.println(event.getHost() + " " + event.getAction());
        if ("reject".equals(event.getAction())) break;
    }
}
```

```elixir
{:ok, events} = Miosa.Audit.list(sandbox.id,
  since: "1h", host: "api.openai.com", action: "allow", limit: 100)
Enum.each(events, fn e ->
  IO.puts("#{e.timestamp} #{e.host} #{e.method} #{e.status_code} #{e.duration_ms}ms")
end)

# Live tail
Miosa.Audit.tail(sandbox.id, fn event ->
  IO.puts("#{event.host} #{event.action}")
  if event.action == "reject", do: :stop, else: :continue
end)

# Tenant-wide
{:ok, events} = Miosa.Audit.list_tenant(%{since: "24h", external_user_id: "dr_smith@clinic1"})
```

## Common queries

### "Why did this fail?"
Filter by `action=reject` for the last hour. Each row tells you which rule blocked it (`rejected_by` column).

### "Which secret did this request use?"
Each row's `request_transforms` JSON includes a `secrets` entry listing the secret names swapped. UI surfaces this in the detail drawer; SDK exposes it as `event.request_transforms.secrets.swapped`.

### "What did our AI agent do last quarter?"
Tenant-admin filter by date range and resource type. Export CSV.

### "Show me all calls by Dr. Smith"
For white-label deployments, filter by `external_user_id`. See [White-label Credentials](/docs/security/white-label).

## Export

Every filtered view can be exported as CSV or JSON via the "Export" button (UI) or the SDK:

```python
sandbox.audit.export(since="30d", format="csv", path="audit-30d.csv")
```

## Retention

| Plan | Retention |
|---|---|
| All plans (default) | 90 days |
| Custom retention (longer) | available on enterprise plans |

Beyond the retention window, rows are deleted from `egress_audit`. Export your data if you need a longer record.

If you delete a sandbox, its audit rows remain in the tenant's audit table for the retention window. Identity columns (tenant, workspace, user, external_*) are denormalized at write time so queries don't need joins.

## Programmatic alerting (Phase 5)

You'll be able to wire saved queries into alerting:

> "Notify me if any sandbox makes more than 100 requests to a never-before-seen host in 5 minutes."

This ships in Phase 5 of the Security rollout.

## Real-world example  -  compliance dashboard for a multi-tenant healthcare app

You're building a healthcare SaaS where each clinician uses a sandbox. Compliance requires you to surface all outbound calls per clinician in your own dashboard, with the ability to export a 30-day report.

```python

from miosa import Miosa
from datetime import datetime

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def get_clinician_report(clinician_id: str, days: int = 30) -> dict:
    """Return an audit summary for one clinician over the last N days."""
    events = client.audit.list(
        since=f"{days}d",
        external_user_id=clinician_id,
        limit=1000,
    )

    hosts = {}
    blocked = []
    for e in events:
        hosts[e.host] = hosts.get(e.host, 0) + 1
        if e.action == "reject":
            blocked.append({
                "timestamp": e.timestamp,
                "host": e.host,
                "method": e.method,
                "rule": e.rejected_by,
            })

    return {
        "clinician_id": clinician_id,
        "period_days": days,
        "total_requests": len(events),
        "unique_hosts": len(hosts),
        "top_hosts": sorted(hosts.items(), key=lambda x: -x[1])[:10],
        "blocked_count": len(blocked),
        "blocked_events": blocked[:20],
    }

report = get_clinician_report("dr_smith@clinic1.example", days=30)
print(json.dumps(report, indent=2))

# Export to CSV
client.audit.export(
    since="30d",
    format="csv",
    path=f"audit-dr_smith-30d.csv",
    external_user_id="dr_smith@clinic1.example",
)
print("Exported audit-dr_smith-30d.csv")
```

```typescript

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

async function getClinicianReport(clinicianId: string, days = 30) {
  const events = await client.audit.list({
    since: `${days}d`,
    externalUserId: clinicianId,
    limit: 1000,
  });

  const hosts: Record<string, number> = {};
  const blocked = [];

  for (const e of events) {
    hosts[e.host] = (hosts[e.host] ?? 0) + 1;
    if (e.action === 'reject') {
      blocked.push({ timestamp: e.timestamp, host: e.host, rule: e.rejectedBy });
    }
  }

  return {
    clinicianId,
    periodDays: days,
    totalRequests: events.length,
    uniqueHosts: Object.keys(hosts).length,
    topHosts: Object.entries(hosts).sort(([, a], [, b]) => b - a).slice(0, 10),
    blockedCount: blocked.length,
    blockedEvents: blocked.slice(0, 20),
  };
}

const report = await getClinicianReport('dr_smith@clinic1.example', 30);
console.log(JSON.stringify(report, null, 2));

await client.audit.export({
  since: '30d',
  format: 'csv',
  path: 'audit-dr_smith-30d.csv',
  externalUserId: 'dr_smith@clinic1.example',
});
```

## Troubleshooting

**Audit log is empty even though the sandbox is running.**
The audit log only records *outbound* calls from the sandbox. If the sandbox is just waiting for input or doing in-process computation with no network calls, no rows appear. Trigger an outbound call and re-query.

**`audit.tail()` disconnects after a few seconds.**
Tail connections are kept alive with WebSocket pings. If your network has a short idle-connection timeout, the connection can drop. Reconnect in your retry loop:

```python
while True:
    try:
        for event in sandbox.audit.tail():
            process(event)
    except ConnectionError:
        time.sleep(1)  # reconnect
```

**`request_transforms.secrets.swapped` is empty  -  but I have secrets bound.**
If the sandbox's env var contains the real key (e.g., from a `.env` file that overrode the placeholder), the proxy has nothing to swap. Run `sandbox.exec("echo $OPENAI_API_KEY")`  -  if it prints the real `sk-proj-...` instead of `miosa-tok-...`, the `.env` file is winning.

**Tenant-wide `client.audit.list()` returns too many rows.**
Narrow with `external_user_id`, `external_workspace_id`, `host`, or `action` filters. Maximum `limit` per call is 1000. For larger exports, use `audit.export()`.

**I need audit rows older than 90 days.**
Default retention is 90 days. For longer retention, contact support to enable custom retention on your tenant. Export regularly if you need a permanent archive.

For more issues, see the [Security troubleshooting hub](/docs/security/troubleshooting).

## Frequently asked

**Does the audit log capture request bodies?**
Not by default  -  only headers (redacted) and metadata. You can opt in to body capture per-resource if you need it for compliance, with a "may contain sensitive data" warning.

**Are response bodies captured?**
No. Audit is request-side only.

**Can I disable the audit log entirely?**
No  -  audit is the platform baseline. You can shorten retention but not disable it.

**Will live-tail consume my plan's API quota?**
No. Audit streaming is over a WebSocket and doesn't count against REST API rate limits.

---

# Connect Accounts (OAuth)

URL: https://miosa.ai/docs/security/connect-accounts
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/connect-accounts
Source: src/routes/docs/security/connect-accounts/+page.md
Description: Authorize accounts (GitHub, Google, Slack, …) once. MIOSA manages token refresh; your sandbox sees an env var.

# Connect Accounts (OAuth)

Instead of pasting a personal-access token or API key, **authorize an account** directly with the upstream provider. MIOSA stores the access + refresh tokens, refreshes them in the background, and exposes the current valid access token to your sandbox as a plain environment variable.

## When to use this over Secrets

| You have… | Use |
|---|---|
| An API key string (e.g., OpenAI `sk-…`, Stripe `sk_live_…`) | [Secrets](/docs/security/secrets) |
| An account where the provider supports OAuth (GitHub, Google, Slack, …) | **Connect Accounts** |
| A machine-to-machine OAuth2 client (client_id + client_secret) | **Connect Accounts** (Machine OAuth) |

## Connect a GitHub account (the typical flow)

### From the dashboard

```
1. Sandbox detail → Secrets tab → "+ Connect Account"
2. Pick "GitHub" from the provider grid
3. Browser opens to github.com/login/oauth/authorize
4. Approve the scopes you want to grant
5. You bounce back to MIOSA. Done.
```

A new entry appears in your Secrets list:

```
Name:     github_token
Type:     OAuth Connect
Provider: GitHub
Scopes:   repo, read:user
Expires:  in 8 hours (auto-refreshed)
```

Inside your sandbox:

```bash
$ echo $GITHUB_TOKEN
miosa-tok-9a3c5e7b1f8d2a4c...
```

Use it exactly like a real token  -  the swap happens on egress:

```python
requests.get(
    "https://api.github.com/user/repos",
    headers={"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"},
)
```

When the access token expires, MIOSA uses the refresh token in the background to mint a new one. Your code never notices.

### From the SDK

```python
flow = sandbox.secrets.connect(
    provider="github",
    expose_as_env="GITHUB_TOKEN",
)

# `flow.authorize_url` is a URL the end user opens in their browser.
print("Authorize at:", flow.authorize_url)

# Block until the user completes the OAuth dance:
flow.wait_for_completion(timeout=300)
```

```ts
const flow = await sandbox.secrets.connect({
  provider: 'github',
  exposeAsEnv: 'GITHUB_TOKEN',
});

console.log('Authorize at:', flow.authorizeUrl);
await flow.waitForCompletion({ timeoutSec: 300 });
```

```go
flow, err := sandbox.Secrets.Connect(ctx, miosa.OAuthConnect{
    Provider:    "github",
    ExposeAsEnv: "GITHUB_TOKEN",
    Scopes:      []string{"repo", "read:user"},
})
if err != nil { panic(err) }

fmt.Println("Authorize at:", flow.AuthorizeURL)
if err := flow.WaitForCompletion(ctx, 300); err != nil { panic(err) }
```

```java
OAuthFlow flow = sandbox.secrets().connect(OAuthConnect.builder()
    .provider("github")
    .exposeAsEnv("GITHUB_TOKEN")
    .scopes(List.of("repo", "read:user"))
    .build());

System.out.println("Authorize at: " + flow.getAuthorizeUrl());
flow.waitForCompletion(Duration.ofSeconds(300));
```

```elixir
{:ok, flow} = Miosa.Secrets.connect(sandbox.id, %{
  provider: "github",
  expose_as_env: "GITHUB_TOKEN",
  scopes: ["repo", "read:user"]
})

IO.puts("Authorize at: #{flow.authorize_url}")
{:ok, _} = Miosa.Secrets.wait_for_oauth(flow.id, timeout: 300)
```

## Supported providers

| Provider | Status |
|---|---|
| GitHub | ✅ available |
| Google (Gmail, Drive, Calendar) | rolling out |
| Slack | rolling out |
| Linear | rolling out |
| Notion | rolling out |
| Stripe | planned |
| HubSpot | planned |
| Custom OAuth2 provider | planned  -  file a request |

Adding a new well-known provider is a config-only change on our side  -  no SDK release needed.

## Machine OAuth (client credentials)

For provider APIs that use the OAuth2 client-credentials flow (no end-user, machine-to-machine):

```python
sandbox.secrets.add_machine_oauth(
    name="my_internal_api",
    client_id="abc...",
    client_secret="def...",
    token_url="https://my-api.example.com/oauth/token",
    scopes=["read", "write"],
    expose_as_env="INTERNAL_API_TOKEN",
)
```

MIOSA mints + caches access tokens against `token_url`, refreshes ahead of expiry, and injects them as `INTERNAL_API_TOKEN`.

## What the proxy injects

For an OAuth Connect secret, the proxy injects:

- **Access token** by default (the most common case  -  `Authorization: Bearer …`)
- **Refresh-on-401**: if the upstream returns a 401, the proxy attempts a refresh before bubbling the error to your code

The refresh token itself is **never** exposed to the sandbox. It stays encrypted in MIOSA's vault.

## Rotation, revocation, scope changes

- **Rotation**: happens automatically. You don't do anything.
- **Revocation**: open the Secrets tab → click "Disconnect" → MIOSA destroys the refresh token immediately. The next outbound request fails with 401.
- **Scope changes**: requires re-authorizing. Click "Re-authorize" on the secret; you'll go through the OAuth dance again with the new scopes.

## White-label OAuth (your branding, not MIOSA's)

By default, end-users see "Authorize MIOSA to access your GitHub" in the OAuth consent screen. For white-label deployments, register your own OAuth app and route the dance through your branding  -  see [White-label Credentials](/docs/security/white-label).

## Real-world example  -  agent reads GitHub issues and posts Slack updates

Connect both GitHub and Slack via OAuth. The agent reads open issues and posts a daily digest to a Slack channel. No credentials ever enter the sandbox.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
sandbox = client.sandboxes.create(template="python-ds")

# Connect GitHub
github_flow = sandbox.secrets.connect(
    provider="github",
    expose_as_env="GITHUB_TOKEN",
    scopes=["repo", "read:user"],
)
print("1. Authorize GitHub at:", github_flow.authorize_url)
github_flow.wait_for_completion(timeout=300)
print("   GitHub connected.")

# Connect Slack
slack_flow = sandbox.secrets.connect(
    provider="slack",
    expose_as_env="SLACK_BOT_TOKEN",
    scopes=["chat:write", "channels:read"],
)
print("2. Authorize Slack at:", slack_flow.authorize_url)
slack_flow.wait_for_completion(timeout=300)
print("   Slack connected.")

# Write and run the agent
agent_code = '''

GITHUB_TOKEN = os.environ["GITHUB_TOKEN"]
SLACK_TOKEN  = os.environ["SLACK_BOT_TOKEN"]
REPO         = "your-org/your-repo"
CHANNEL      = "#engineering-digest"

# Fetch open issues
issues = requests.get(
    f"https://api.github.com/repos/{REPO}/issues?state=open&per_page=10",
    headers={"Authorization": f"Bearer {GITHUB_TOKEN}"},
).json()

# Build digest message
lines = [f"*Open issues digest for {REPO}*"]
for i in issues:
    lines.append(f"• <{i['html_url']}|#{i['number']} {i['title']}>")
message = "\\n".join(lines)

# Post to Slack
resp = requests.post(
    "https://slack.com/api/chat.postMessage",
    headers={"Authorization": f"Bearer {SLACK_TOKEN}"},
    json={"channel": CHANNEL, "text": message},
)
print("Posted:", resp.json().get("ok"))
'''

sandbox.files.write("/workspace/digest.py", agent_code)
result = sandbox.exec("python /workspace/digest.py")
print(result.stdout)
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const sandbox = await client.sandboxes.create({ template: 'node-web' });

// Connect GitHub
const githubFlow = await sandbox.secrets.connect({
  provider: 'github',
  exposeAsEnv: 'GITHUB_TOKEN',
  scopes: ['repo', 'read:user'],
});
console.log('1. Authorize GitHub at:', githubFlow.authorizeUrl);
await githubFlow.waitForCompletion({ timeoutSec: 300 });
console.log('   GitHub connected.');

// Connect Slack
const slackFlow = await sandbox.secrets.connect({
  provider: 'slack',
  exposeAsEnv: 'SLACK_BOT_TOKEN',
  scopes: ['chat:write', 'channels:read'],
});
console.log('2. Authorize Slack at:', slackFlow.authorizeUrl);
await slackFlow.waitForCompletion({ timeoutSec: 300 });
console.log('   Slack connected.');

// Run the digest agent
const result = await sandbox.exec('node /workspace/digest.js');
console.log(result.stdout);
```

## Troubleshooting

**`flow.wait_for_completion` times out  -  user authorized but the flow never resolves.**
Usually means the OAuth callback URL is wrong. Verify the callback URL in your OAuth app settings on the provider side matches what MIOSA expects. For white-label setups, make sure your proxy endpoint is forwarding `code` and `state` parameters to `client.oauth.complete()`.

**GitHub OAuth returns "bad_verification_code".**
The authorization code is single-use with a short TTL (10 minutes for GitHub). If `wait_for_completion` took too long, or the callback was called twice, the code is stale. Re-initiate `sandbox.secrets.connect()` to get a fresh flow.

**Token expired  -  sandbox gets 401 from GitHub.**
MIOSA auto-refreshes tokens. If refresh fails (token revoked by user), the dashboard shows "Reconnect needed." Call `sandbox.secrets.reauthorize(provider="github")` and have the user re-authorize.

**"invalid_grant" during token refresh.**
GitHub (and most providers) invalidate the refresh token when the user revokes the OAuth app permission. Re-connect via `sandbox.secrets.reauthorize()`.

**Slack posts succeed but the token appears in the message body.**
This happens if the Slack SDK puts the token in the request body instead of the `Authorization` header. The MIOSA proxy scans bodies when buffered, but Slack's standard `Bearer` header is the reliable path. Ensure you're using `Authorization: Bearer $SLACK_BOT_TOKEN`.

For more issues, see the [Security troubleshooting hub](/docs/security/troubleshooting).

## Frequently asked

**My OAuth provider isn't on the list. Can I add it manually?**
Yes  -  file a request, or use the Custom OAuth2 path when it ships (Phase 3). For now, any provider that issues static access tokens works as a regular API key via [Secrets](/docs/security/secrets).

**Does the sandbox see the refresh token?**
No. Only the current access token is injected. Refresh tokens stay encrypted in MIOSA.

**Can I bind one OAuth account to many sandboxes?**
Yes. Save the secret at the `tenant`, `workspace`, or `user` scope; every sandbox in that scope inherits the binding.

**What happens if the provider revokes my token from their side?**
The proxy's next refresh attempt will fail. We surface this in the dashboard with a "Reconnect needed" badge on the secret, and your next outbound request returns 401.

---

# Network Allowlist

URL: https://miosa.ai/docs/security/network
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/network
Source: src/routes/docs/security/network/+page.md
Description: Watch what your sandbox calls. When you're ready, lock it down with a one-click allowlist. Reversible.

# Network Allowlist

By default, every new MIOSA sandbox runs in **audit-only mode**: every outbound call is recorded, none are blocked. After your sandbox has been running for a while, MIOSA shows you the list of hosts it actually contacted  -  and you can flip to **enforce mode** in one click, with that list as the allowlist.

Lockdown is never applied automatically. You explicitly click "Lock Down"  -  and you can revert to audit-only at any time with one click. No data is lost in either direction.

## The two modes

| Mode | What it does | Default? |
|---|---|---|
| **Audit-only** | Logs every outbound request. Nothing is blocked. | ✅ yes  -  every new sandbox starts here |
| **Enforce** | Applies the allowlist. Requests to unlisted hosts are blocked. | opt-in |

## The "watch then enforce" flow

### Day 0  -  Sandbox is created

No setup. Audit-only is on by default. Your sandbox makes outbound calls exactly like it did before MIOSA Egress existed. Every call is logged silently.

### Day 0-7  -  Use your sandbox normally

Build, deploy, run your agent  -  whatever. MIOSA collects audit data.

### Day 7+  -  Visit the Network tab

The Network tab shows you:

```
HOSTS CONTACTED IN THE LAST 7 DAYS                  REQUESTS

api.openai.com                                        1,247
*.anthropic.com                                          83
github.com                                               412
pypi.org                                                  29
files.pythonhosted.org                                   161
api.github.com                                          1,053
```

Click "Lock Down". A confirmation modal appears showing the checkboxes for each host. You uncheck anything you don't want. Click Confirm.

Mode flips to **enforce**. The proxy now blocks anything not on the list.

### After lockdown  -  New hosts go to Pending

If your sandbox tries to reach a host that isn't on the allowlist, the request is blocked AND the host appears in the **Pending Requests** section of the Network tab. One click → Allow or Block.

You're never stuck  -  denied requests are visible, attributable, and one click away from resolution.

## SDK  -  Network controls

```python
# Allow a host (audit-only or enforce  -  doesn't matter; allow is allow)
sandbox.network.allow("api.openai.com")
sandbox.network.allow("*.anthropic.com", methods=["POST"])

# Explicit deny  -  overrides any allow
sandbox.network.deny("169.254.169.254")

# Switch to enforce mode using the current allowlist
sandbox.network.lockdown()

# Switch back to audit-only
sandbox.network.observe()

# Auto-suggested allowlist from observed traffic
hosts = sandbox.network.suggestions(since="7d")
for h in hosts:
    print(h.host, h.request_count, h.last_seen)

# Inspect the current policy
policy = sandbox.network.get_policy()
print(policy.mode, policy.allow_rules, policy.deny_rules)

# Pending blocked requests
pending = sandbox.network.pending()
for p in pending:
    print(p.host, p.request_count, "blocked")
```

```typescript
await sandbox.network.allow('api.openai.com');
await sandbox.network.allow('*.anthropic.com', { methods: ['POST'] });
await sandbox.network.deny('169.254.169.254');
await sandbox.network.lockdown();
await sandbox.network.observe();

const hosts = await sandbox.network.suggestions({ since: '7d' });
const policy = await sandbox.network.getPolicy();
const pending = await sandbox.network.pending();
```

```go
sandbox.Network.Allow(ctx, "api.openai.com", miosa.AllowOpts{})
sandbox.Network.Allow(ctx, "*.anthropic.com", miosa.AllowOpts{Methods: []string{"POST"}})
sandbox.Network.Deny(ctx, "169.254.169.254")
sandbox.Network.Lockdown(ctx)
sandbox.Network.Observe(ctx)

hosts, _ := sandbox.Network.Suggestions(ctx, miosa.SuggestionsOpts{Since: "7d"})
policy, _ := sandbox.Network.GetPolicy(ctx)
pending, _ := sandbox.Network.Pending(ctx)
```

```java
sandbox.network().allow("api.openai.com");
sandbox.network().allow("*.anthropic.com", AllowOpts.builder().methods(List.of("POST")).build());
sandbox.network().deny("169.254.169.254");
sandbox.network().lockdown();
sandbox.network().observe();

List hosts = sandbox.network().suggestions(
    SuggestionsOpts.builder().since("7d").build());
NetworkPolicy policy = sandbox.network().getPolicy();
List pending = sandbox.network().pending();
```

```elixir
{:ok, _} = Miosa.Network.allow(sandbox.id, "api.openai.com")
{:ok, _} = Miosa.Network.allow(sandbox.id, "*.anthropic.com", methods: ["POST"])
{:ok, _} = Miosa.Network.deny(sandbox.id, "169.254.169.254")
{:ok, _} = Miosa.Network.lockdown(sandbox.id)
{:ok, _} = Miosa.Network.observe(sandbox.id)

{:ok, hosts}   = Miosa.Network.suggestions(sandbox.id, since: "7d")
{:ok, policy}  = Miosa.Network.get_policy(sandbox.id)
{:ok, pending} = Miosa.Network.pending(sandbox.id)
```

## Pattern matching

| Kind | Example | Matches |
|---|---|---|
| Exact host | `api.openai.com` | only this hostname |
| Wildcard | `*.openai.com` | any subdomain of openai.com |
| CIDR (IP only) | `10.0.0.0/8` | any IP in this range, only when the request target is an IP literal (not a hostname) |

Precedence at request time:

1. Exact match wins over wildcard
2. Wildcard wins over CIDR
3. Explicit `deny` rules always win over `allow`

## Per-resource vs tenant-wide rules

You can attach allowlist rules at two levels:

- **Per-resource**  -  applies to just one sandbox or computer
- **Tenant-wide**  -  applies to every resource in your tenant unless a resource has its own override

This means you can have a tenant default of "only allow our internal API + npm" and per-sandbox additions on top.

## When to use warn-mode rules

You can mark a rule as `warn_only`:

```python
sandbox.network.allow("api.experimental.example.com", warn_only=True)
```

In enforce mode, a `warn_only` allow rule still lets the request through but flags it in the audit log. Useful for trial-running a new third-party integration before committing to it.

## Rolling back

If lockdown breaks something:

```python
sandbox.network.observe()
```

You're back to audit-only. Allowlist rules are preserved (so you can re-lockdown later) but they're no longer enforcing.

## Real-world example  -  Python data pipeline locked to its upstream services

A Python sandbox that fetches data from a REST API, processes it, and writes results to an S3-compatible endpoint. Locked down to exactly those three hosts.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
sandbox = client.sandboxes.create(template="python-ds")

# Store credentials in the vault
sandbox.secrets.set(name="data_api_key", value=os.environ["DATA_API_KEY"], expose_as_env="DATA_API_KEY")
sandbox.secrets.set(name="s3_key", value=os.environ["S3_SECRET_KEY"], expose_as_env="AWS_SECRET_ACCESS_KEY")

# Let it run for a minute to observe traffic

pipeline = """

resp = requests.get(
    "https://data.example.com/api/v1/events?limit=100",
    headers={"X-Api-Key": os.environ["DATA_API_KEY"]},
)
events = resp.json()

# Process…
summary = {"count": len(events), "total_value": sum(e["value"] for e in events)}

s3 = boto3.client(
    "s3",
    endpoint_url="https://storage.example.com",
    aws_access_key_id="access",
    aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
)

s3.put_object(Bucket="results", Key="summary.json", Body=json.dumps(summary))
print("Done:", summary)
"""
sandbox.files.write("/workspace/pipeline.py", pipeline)
sandbox.exec("pip install boto3 -q")
sandbox.exec("python /workspace/pipeline.py")   # observe this run

# Now lock down based on what we observed
suggestions = sandbox.network.suggestions(since="1h")
print("Observed hosts:")
for h in suggestions:
    print(f"  {h.host} ({h.request_count} requests)")

# Allow only the three we expect
sandbox.network.allow("data.example.com")
sandbox.network.allow("storage.example.com")
sandbox.network.allow("pypi.org")          # for the pip install above
sandbox.network.allow("files.pythonhosted.org")
sandbox.network.lockdown()
print("Locked. Mode:", sandbox.network.get_policy().mode)

# Run again  -  still works, nothing else reachable
result = sandbox.exec("python /workspace/pipeline.py")
print(result.stdout)
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const sandbox = await client.sandboxes.create({ template: 'python-ds' });

await sandbox.secrets.set({ name: 'data_api_key', value: process.env.DATA_API_KEY!, exposeAsEnv: 'DATA_API_KEY' });

// Observe one run, then lock down
const suggestions = await sandbox.network.suggestions({ since: '1h' });
for (const h of suggestions) {
  await sandbox.network.allow(h.host);
}
await sandbox.network.lockdown();
console.log('Locked to:', suggestions.map(h => h.host).join(', '));
```

## Troubleshooting

**`pip install` fails after lockdown  -  "Could not find a version that satisfies the requirement".**
Three domains are needed: `pypi.org`, `files.pythonhosted.org`, and `pythonhosted.org`. Allow all three before locking down.

**`npm install` fails after lockdown.**
Allow `registry.npmjs.org`. Some packages also fetch from `*.github.com` during postinstall scripts  -  check the Pending queue for exact hosts.

**My sandbox is in enforce mode but I see unexpected hosts in the audit log.**
Audit-only log entries always appear even in enforce mode (blocked calls still get logged with `action=reject`). Filter by `action=reject` to see what's being blocked.

**I want the same policy on every new sandbox without configuring each one.**
Apply rules at the tenant level using `client.network.allow(...)` and `client.network.lockdown()`  -  these become the default for all resources in the tenant unless overridden per sandbox.

**After `observe()`, my rules are gone when I call `lockdown()` again.**
Rules are never deleted by `observe()`. If they appear missing, check `sandbox.network.get_policy().allow_rules`  -  they'll be listed there. The only way rules disappear is if you called `sandbox.network.clear_rules()` explicitly.

For more issues, see the [Security troubleshooting hub](/docs/security/troubleshooting).

## Frequently asked

**Will lockdown block npm install or pip install?**
Only if you don't allow `pypi.org`, `files.pythonhosted.org`, `registry.npmjs.org`, etc. The 7-day audit data will have already shown you these  -  they're on the suggested list.

**My agent suddenly stopped working after I locked down.**
Open the Network tab → Pending Requests. You'll see exactly what got blocked. One-click allow, or revert with `observe()`.

**Can I share allowlists across sandboxes?**
Yes  -  apply them at the tenant or workspace scope, or copy a "policy template" from another resource (Phase 5).

**Does lockdown affect inbound (preview) traffic?**
No. Lockdown is for outbound only. Preview URLs into your sandbox keep working exactly as before.

---

# Secrets  -  Quickstart

URL: https://miosa.ai/docs/security/secrets
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/secrets
Source: src/routes/docs/security/secrets/+page.md
Description: Store API keys in MIOSA. Your sandbox uses an opaque placeholder. The real key never lives inside the VM.

# Secrets  -  Quickstart

Store an API key once in MIOSA. Every sandbox using it sees an opaque placeholder env var. Rotate in one place, every sandbox picks up the new value automatically.

## Add an API key (30 seconds)

### From the dashboard

```
1. Open your Sandbox or Computer in the MIOSA dashboard
2. Click the "Secrets" tab
3. Click "+ Add Secret"
4. Fill in:
     Name:        openai_key
     Value:       sk-proj-...  (paste your real key)
     Expose as:   OPENAI_API_KEY
5. Save
```

Inside the sandbox, `process.env.OPENAI_API_KEY` is now an opaque token. Use it in your code exactly as you would the real key  -  the swap happens on egress.

### From the SDK

```python
from miosa import Miosa
client = Miosa(api_key="msk_u_...")
sandbox = client.sandboxes.create(template="python-ds")

sandbox.secrets.set(
    name="openai_key",
    value="sk-proj-...",
    expose_as_env="OPENAI_API_KEY",
)
```

```ts

const miosa = new Miosa({ apiKey: 'msk_u_...' });
const sandbox = await miosa.sandboxes.create({ template: 'node-web' });

await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});
```

```go
client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))
sandbox, _ := client.Sandboxes.Create(ctx, miosa.SandboxCreate{Template: "go-web"})

sandbox.Secrets.Set(ctx, miosa.SecretSet{
    Name:         "openai_key",
    Value:        realKey,
    ExposeAsEnv:  "OPENAI_API_KEY",
})
```

## How the placeholder works

Inside the sandbox after binding:

```bash
$ echo $OPENAI_API_KEY
miosa-tok-7f2a8c1d4b2e6f0a...
```

When your code makes an outbound call:

```python
requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
    json={...},
)
```

…the MIOSA proxy on your VM's host sees the request, finds `miosa-tok-7f2a8c1d4b2e6f0a` in the `Authorization` header, and **swaps it with your real `sk-proj-...`** before forwarding to OpenAI. OpenAI sees the real key. Your sandbox never did.

The placeholder is unique per binding  -  there is no global table of placeholders an attacker could brute-force.

Header values, query parameters, URL paths, and (when buffered) request bodies are all scanned for placeholder tokens. Basic-auth headers are decoded → swapped → re-encoded.

## Rotate a key

```python
sandbox.secrets.rotate("openai_key", new_value="sk-proj-newvalue...")
```

Every sandbox using this secret picks up the new value on its next outbound request. No restart. No redeploy. The placeholder token doesn't change.

## List + delete

```python
secrets = sandbox.secrets.list()
# Returns metadata only  -  name, type, preview (last 4 chars), last_used_at.
# Never returns the real value.

sandbox.secrets.delete("openai_key")
```

## Scope levels

A secret can be scoped at five levels  -  the proxy picks the most specific match for the resource making the request:

| Scope | Use case |
|---|---|
| `tenant` | Your organization's company-wide credentials |
| `workspace` | Credentials shared by everyone in one workspace |
| `user` | An individual MIOSA user's personal credentials |
| `external_user` | A white-label end-user's credentials (see [White-label](/docs/security/white-label)) |
| `external_workspace` | A white-label workspace's credentials |

Default scope when using `sandbox.secrets.set` is determined by the API key making the call. Tenant admins can create tenant-wide secrets; individual users create user-scoped ones for their own resources.

## What the proxy can do beyond a string swap

For OAuth-managed credentials (see [Connect Accounts](/docs/security/connect-accounts)), the proxy also:

- **Refreshes expired tokens** automatically using the stored refresh token
- **Surfaces token revocation** (when the upstream side invalidates the access) as a 401 to your code, exactly as if you'd held the token yourself

You don't write any of that logic.

## All 5 SDKs

```python
from miosa import Miosa
client = Miosa(api_key="msk_u_...")
sandbox = client.sandboxes.create(template="python-ds")

sandbox.secrets.set(
    name="openai_key",
    value="sk-proj-...",
    expose_as_env="OPENAI_API_KEY",
)
sandbox.secrets.rotate("openai_key", new_value="sk-proj-newvalue...")
secrets = sandbox.secrets.list()
sandbox.secrets.delete("openai_key")
```

```typescript

const miosa = new Miosa({ apiKey: 'msk_u_...' });
const sandbox = await miosa.sandboxes.create({ template: 'node-web' });

await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});
await sandbox.secrets.rotate({ name: 'openai_key', newValue: 'sk-proj-newvalue...' });
const secrets = await sandbox.secrets.list();
await sandbox.secrets.delete('openai_key');
```

```go
client := miosa.NewClient(os.Getenv("MIOSA_API_KEY"))
sandbox, _ := client.Sandboxes.Create(ctx, miosa.SandboxCreate{Template: "go-web"})

sandbox.Secrets.Set(ctx, miosa.SecretSet{
    Name:        "openai_key",
    Value:       realKey,
    ExposeAsEnv: "OPENAI_API_KEY",
})
sandbox.Secrets.Rotate(ctx, "openai_key", "sk-proj-newvalue...")
secrets, _ := sandbox.Secrets.List(ctx)
sandbox.Secrets.Delete(ctx, "openai_key")
```

```java
MiosaClient client = new MiosaClient(System.getenv("MIOSA_API_KEY"));
Sandbox sandbox = client.sandboxes().create(SandboxCreate.builder()
    .template("python-ds").build());

sandbox.secrets().set(SecretSet.builder()
    .name("openai_key")
    .value(System.getenv("MY_OPENAI_KEY"))
    .exposeAsEnv("OPENAI_API_KEY")
    .build());
sandbox.secrets().rotate("openai_key", "sk-proj-newvalue...");
List secrets = sandbox.secrets().list();
sandbox.secrets().delete("openai_key");
```

```elixir
{:ok, sandbox} = Miosa.Sandboxes.create(%{template: "python-ds"})

{:ok, _} = Miosa.Secrets.set(sandbox.id, %{
  name: "openai_key",
  value: System.get_env("MY_OPENAI_KEY"),
  expose_as_env: "OPENAI_API_KEY"
})
{:ok, _} = Miosa.Secrets.rotate(sandbox.id, "openai_key", "sk-proj-newvalue...")
{:ok, secrets} = Miosa.Secrets.list(sandbox.id)
{:ok, _} = Miosa.Secrets.delete(sandbox.id, "openai_key")
```

## Real-world example  -  multi-service agent with OpenAI and Stripe

An agent that drafts payment summaries by calling both OpenAI and the Stripe API. Two secrets, one sandbox, no credentials in the VM.

```python

from miosa import Miosa

client = Miosa(api_key=os.environ["MIOSA_API_KEY"])
sandbox = client.sandboxes.create(template="python-ds")

# Store both secrets
sandbox.secrets.set(
    name="openai_key",
    value=os.environ["MY_OPENAI_KEY"],
    expose_as_env="OPENAI_API_KEY",
)
sandbox.secrets.set(
    name="stripe_key",
    value=os.environ["MY_STRIPE_KEY"],
    expose_as_env="STRIPE_SECRET_KEY",
)

agent_code = '''

# Both env vars are placeholders; the proxy swaps them on egress
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
STRIPE_SECRET_KEY = os.environ["STRIPE_SECRET_KEY"]

# Fetch recent Stripe charges
charges = requests.get(
    "https://api.stripe.com/v1/charges?limit=5",
    auth=(STRIPE_SECRET_KEY, ""),
).json()["data"]

# Ask OpenAI to summarize them
summary_prompt = "Summarize these Stripe charges in one sentence: " + json.dumps(charges)
resp = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
    json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": summary_prompt}]},
)
print(resp.json()["choices"][0]["message"]["content"])
'''

sandbox.files.write("/workspace/agent.py", agent_code)
result = sandbox.exec("python /workspace/agent.py")
print(result.stdout)
```

```typescript

const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
const sandbox = await client.sandboxes.create({ template: 'node-web' });

await sandbox.secrets.set({
  name: 'openai_key',
  value: process.env.MY_OPENAI_KEY!,
  exposeAsEnv: 'OPENAI_API_KEY',
});
await sandbox.secrets.set({
  name: 'stripe_key',
  value: process.env.MY_STRIPE_KEY!,
  exposeAsEnv: 'STRIPE_SECRET_KEY',
});

const agentCode = `
const resp = await fetch('https://api.stripe.com/v1/charges?limit=5', {
  headers: { Authorization: 'Bearer ' + process.env.STRIPE_SECRET_KEY },
});
const { data: charges } = await resp.json();

const ai = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.OPENAI_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Summarize: ' + JSON.stringify(charges) }],
  }),
});
const { choices } = await ai.json();
console.log(choices[0].message.content);
`;

await sandbox.files.write('/workspace/agent.ts', agentCode);
const result = await sandbox.exec('npx tsx /workspace/agent.ts');
console.log(result.stdout);
```

## Troubleshooting

**The sandbox env var is empty  -  `echo $OPENAI_API_KEY` prints nothing.**
The secret was saved at `scope="tenant"` or `scope="workspace"` but the sandbox doesn't belong to that scope. Re-save with `scope="sandbox"` (the default when using `sandbox.secrets.set`).

**`secrets.list()` shows the secret but the upstream API returns 401.**
The proxy is not seeing the placeholder in the request. Confirm the library you're using puts the token in `Authorization: Bearer ...`. Check the audit row's `request_transforms.secrets.swapped`  -  if empty, the proxy never matched.

**I rotated the key but nothing changed.**
Rotation is instant. The upstream API call succeeding after rotation means the new key is already working. Verify the old key is actually invalid by revoking it on the provider side.

**I deleted a secret but the env var still has a value inside the sandbox.**
The sandbox process caches env vars at startup. Restart the process or open a new exec session  -  the proxy checks the vault on each request, but the env var in the process's memory reflects the last value it read.

For more issues, see the [Security troubleshooting hub](/docs/security/troubleshooting).

## Frequently asked

**Can I read a secret's real value via the SDK after I save it?**
No. `secrets.list` returns metadata only (name, type, preview, last-used time). The value is sealed.

**What if I want to keep using `.env` files?**
Use them. MIOSA Secrets is purely additive; `.env` files continue to work. Use Secrets for credentials you want centrally managed.

**Will this slow my sandbox down?**
About 1-3 ms per outbound request. Trivial vs typical API latency.

**Does it work with `curl`, `requests`, `fetch`, `axios`, `gRPC`, …?**
Yes. The proxy operates at the network layer; the swap is invisible to the language runtime.

---

# Security  -  Troubleshooting

URL: https://miosa.ai/docs/security/troubleshooting
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/troubleshooting
Source: src/routes/docs/security/troubleshooting/+page.md
Description: Top 15 issues across MIOSA Secrets, Connect Accounts, Network Allowlist, Audit Log, and White-label Credentials  -  with root causes and fixes.

# Security  -  Troubleshooting

Quick-reference for the 15 most common issues across all MIOSA Security features. Each entry: symptom → root cause → fix.

---

## Secrets

### 1. Secret value is not being swapped  -  outbound request uses the raw placeholder

**Symptom**: Your sandbox sees `miosa-tok-...` in `$OPENAI_API_KEY` and that placeholder reaches the upstream API, which returns a 401.

**Root cause**: The proxy swaps placeholders by scanning the outbound request for known token prefixes. If the request uses a non-standard header name or doesn't include the `Authorization` header at all, the swap is skipped.

**Fix**:
- Confirm the SDK or library you're using puts the token in the `Authorization: Bearer ...` header.
- For query-string auth (e.g., `?api_key=...`), make sure the token appears verbatim in the query string  -  the proxy scans query params too.
- Check the audit row's `request_transforms.secrets.swapped` field. If it's empty, the proxy didn't match the placeholder.
- Verify the env var name casing matches exactly. `OPENAI_API_KEY` ≠ `openai_api_key`. The proxy is case-sensitive when looking up `expose_as_env` bindings.

---

### 2. `secrets.list()` shows the secret but `$ENV_VAR` is empty inside the sandbox

**Symptom**: The secret is listed in the dashboard and SDK, but `echo $OPENAI_API_KEY` inside the sandbox returns nothing.

**Root cause**: The secret was created with `scope="tenant"` or `scope="workspace"` but the sandbox was not created under the same workspace. Or the `expose_as_env` value has a typo.

**Fix**:
```python
# Check the binding on the sandbox directly
secrets = sandbox.secrets.list()
for s in secrets:
    print(s.name, s.expose_as_env, s.scope)

# If missing, bind it explicitly to this sandbox
sandbox.secrets.set(
    name="openai_key",
    value="sk-proj-...",
    expose_as_env="OPENAI_API_KEY",
)
```

---

### 3. Rotating a key doesn't take effect  -  sandbox still uses the old key

**Symptom**: You called `sandbox.secrets.rotate(name, new_value=...)` but outbound calls to the API still succeed with what appears to be the old key.

**Root cause**: This is almost always correct behavior. Rotation is instant  -  the proxy looks up the new value on the next request carrying the placeholder. If the upstream call succeeds after rotation, the new key is already working. The old key may still be valid on the provider's side (keys aren't invalidated on MIOSA's end  -  only on the provider's end).

**Fix**: Verify rotation worked by checking the audit log:
```python
events = sandbox.audit.list(since="5m", host="api.openai.com", limit=5)
for e in events:
    print(e.timestamp, e.status_code, e.request_transforms)
```
If `status_code` is 200 after rotation, the new key is in use.

To force the old key to stop working: revoke it on the provider's side (e.g., delete it in the OpenAI dashboard), then rotate on MIOSA.

---

## Connect Accounts (OAuth)

### 4. GitHub OAuth refresh failing  -  sandbox gets 401 on `api.github.com`

**Symptom**: The sandbox was working, then suddenly starts getting 401s from GitHub. The audit log shows `action=allow` but `status_code=401`.

**Root cause**: The GitHub access token expired and the refresh attempt failed. This happens when:
- The user revoked the GitHub OAuth app's access from their GitHub settings
- The refresh token itself expired (GitHub personal OAuth tokens don't expire, but GitHub Apps tokens do after 8 hours without a refresh)
- The scopes were changed on the provider side

**Fix**:
1. In the MIOSA dashboard → Secrets tab, the GitHub entry will show "Reconnect needed."
2. Call `flow.reauthorize()` to re-run the OAuth dance:
```python
flow = sandbox.secrets.reauthorize(provider="github")
print("Authorize at:", flow.authorize_url)
flow.wait_for_completion(timeout=300)
```

---

### 5. Custom OAuth provider returns "invalid_state"

**Symptom**: The OAuth callback from a custom OAuth2 provider includes `error=invalid_state`.

**Root cause**: The `state` parameter in the OAuth dance has a 10-minute TTL. If the user took more than 10 minutes to authorize, or if the callback was called twice (e.g., the user hit the back button and tried again), the state is expired or consumed.

**Fix**: Re-initiate the flow. State is one-time use.
```python
# Don't reuse the old flow object  -  create a new one
flow = sandbox.secrets.connect(
    provider="my_custom_provider",
    expose_as_env="MY_API_TOKEN",
)
print("New authorize URL:", flow.authorize_url)
```
If you're building the UI, show the user a "Try again" button that calls your backend to initiate a fresh `connect()`.

---

### 6. Provider OAuth app shows "Authorize MIOSA" instead of my brand

**Symptom**: Your end-users see the MIOSA branding on the GitHub (or other provider) consent screen.

**Root cause**: You haven't registered a custom OAuth app override for your tenant.

**Fix**: See [White-label OAuth setup](/docs/security/white-label#white-label-oauth-your-branding-not-miosas). Register your own OAuth app with the provider, then add the override in Settings → OAuth Providers.

---

## Network Allowlist

### 7. Sandbox can't reach `pypi.org` after lockdown

**Symptom**: `pip install <package>` fails with a connection error after you locked down the network.

**Root cause**: `pip` contacts three domains, and all three must be on the allowlist:

| Domain | What it does |
|---|---|
| `pypi.org` | Package index queries |
| `files.pythonhosted.org` | Package download CDN |
| `pythonhosted.org` | Legacy package downloads (some packages still use this) |

**Fix**:
```python
sandbox.network.allow("pypi.org")
sandbox.network.allow("files.pythonhosted.org")
sandbox.network.allow("pythonhosted.org")
# If you also need conda:
sandbox.network.allow("conda.anaconda.org")
sandbox.network.allow("repo.anaconda.com")
```

---

### 8. `npm install` fails after lockdown

**Symptom**: `npm install` or `pnpm install` fails after switching to enforce mode.

**Root cause**: The npm registry and its CDN are not on the allowlist.

**Fix**:
```python
sandbox.network.allow("registry.npmjs.org")
sandbox.network.allow("*.npmjs.com")
```
If you use pnpm's own mirror:
```python
sandbox.network.allow("registry.npmjs.org")
```

---

### 9. Agent stopped calling a host that's on the allowlist

**Symptom**: You can see the host in your allowlist, but the agent keeps getting blocked.

**Root cause**: The agent is resolving a subdomain or alias not covered by your rule. For example, `api.openai.com` is on the list but the agent is also hitting `oai.endpoint.amazonaws.com` (OpenAI's backend CDN).

**Fix**:
1. Check the Pending Requests queue:
```python
pending = sandbox.network.pending()
for p in pending:
    print(p.host, p.request_count)
```
2. Add any missing hosts to the allowlist.
3. For CDNs and dynamic subdomains, use a wildcard: `*.openai.com`.

---

### 10. I locked down a sandbox but all new sandboxes from the same template are locked too

**Symptom**: Sandboxes created from a template inherit enforce mode unexpectedly.

**Root cause**: The template you snapshotted was already in enforce mode. The policy state is part of the template snapshot.

**Fix**: After creating a sandbox from the template, immediately call:
```python
new_sandbox.network.observe()
```
To prevent this for all future sandboxes, snapshot the template while it's in audit-only mode.

---

## Audit Log

### 11. Audit log is empty  -  no rows for a sandbox that's been running

**Symptom**: `sandbox.audit.list(since="24h")` returns an empty list, even though the sandbox is running and making calls.

**Root cause**: Either:
- The sandbox isn't making any *outbound* calls (the audit log only records egress, not inbound traffic)
- The sandbox was created before the MIOSA egress feature was enabled on your tenant

**Fix**: Confirm outbound traffic from inside the sandbox:
```python
r = sandbox.exec("curl -s -o /dev/null -w '%{http_code}' https://api.openai.com/")
print(r.stdout)  # 401 is fine  -  it proves egress happened
```
Then re-query the audit log. If still empty after confirmed egress, file a support ticket.

---

### 12. Audit rows show `request_transforms.secrets.swapped = []` even though a secret is bound

**Symptom**: The request to `api.openai.com` succeeds, but the audit row shows no secrets were swapped.

**Root cause**: The secret binding was added *after* this particular request was made, or the sandbox resolved the real key from a `.env` file rather than the placeholder (so no swap was needed).

**Fix**: Check whether the env var contains a placeholder or the real key:
```python
r = sandbox.exec("echo $OPENAI_API_KEY")
print(r.stdout)
# "miosa-tok-..." means placeholder is present → proxy will swap
# "sk-proj-..."  means real key is in the env → proxy has nothing to swap
```
If the real key is in the env var (e.g., from a `.env` file), the proxy never sees the placeholder and no swap occurs.

---

## White-label

### 13. Audit query by `external_user_id` returns rows from other users

**Symptom**: `client.audit.list(external_user_id="alice@example.com")` returns events that clearly belong to other users.

**Root cause**: This should not happen  -  `external_user_id` is a strict equality filter within your tenant. Most commonly this is a wildcard match being applied in your own code.

**Fix**: Verify you're passing the exact ID, not a pattern:
```python
# Correct
events = client.audit.list(external_user_id="alice@example.com")

# Wrong  -  this is not a prefix match, but double-check your exact string
events = client.audit.list(external_user_id="alice@")  # won't match anything
```
If the issue persists, check that multiple sandboxes aren't all being created with the same `external_user_id` by mistake.

---

### 14. `scope="external_user"` secret returns 403

**Symptom**: Calling `client.secrets.set(..., scope="external_user", external_user_id="...")` returns HTTP 403.

**Root cause**: Your tenant has "Allow end-user-scoped credentials" disabled.

**Fix**: In the MIOSA dashboard → Settings → Security → toggle "Allow end-user-scoped credentials" to On. If you intentionally disabled it and this call is from your own backend (not an end-user), use `scope="tenant"` or `scope="external_workspace"` instead.

---

### 15. Resolver scope walk skips an expected secret

**Symptom**: A sandbox with `external_user_id="alice"` doesn't pick up a secret set at `scope="external_workspace"` for `external_workspace_id="team-a"`, even though Alice is in team-a.

**Root cause**: The resolver scope walk uses the `external_workspace_id` stamped on the sandbox at creation time. If the sandbox was created without `external_workspace_id="team-a"`, the workspace-level secret doesn't resolve for it.

**Fix**: Verify the sandbox has the right workspace stamp:
```python
sbx = client.sandboxes.get(sandbox_id)
print(sbx.external_workspace_id)   # should be "team-a"
```
If it's missing or wrong, create a new sandbox with the correct attribution. Attribution fields are immutable after creation.

---

## Still stuck?

- Use the Audit Log → detail drawer: each row shows exactly which transforms ran and which rules fired.
- Check [Network Allowlist](/docs/security/network), [Secrets](/docs/security/secrets), [Connect Accounts](/docs/security/connect-accounts) for full reference docs.
- For bugs, open a support ticket from the MIOSA dashboard  -  include the sandbox ID and the relevant audit row ID.

---

# White-label Credentials

URL: https://miosa.ai/docs/security/white-label
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/security/white-label
Source: src/routes/docs/security/white-label/+page.md
Description: How to scope secrets and OAuth connections to your own end-users on top of MIOSA  -  with your branding, not ours.

# White-label Credentials

If you're building a product **on top of MIOSA** (an AI coding agent, a vertical SaaS, an agency tool) and your end-users create sandboxes through *your* UI, MIOSA Security supports them as first-class identities  -  even though they don't have MIOSA accounts.

This page covers:

1. Attributing sandboxes to your end-users with `external_user_id`
2. Storing credentials scoped to those end-users
3. Branding the OAuth consent flow as your own product
4. Auditing per end-user, per workspace

## Background  -  external attribution

Every Computer and Sandbox already supports three caller-supplied attribution fields:

| Field | Purpose |
|---|---|
| `external_user_id` | Your end-user's identity in your system |
| `external_workspace_id` | Your workspace/team grouping |
| `external_project_id` | Your project identity |

These are labels, not authentication boundaries. But MIOSA Security uses them as **credential-scoping keys**, which means you can store secrets that resolve only for *that* end-user's resources.

See [External Attribution](/docs/platform/attribution) for the broader picture.

## Stamping attribution at create time

When your backend creates a sandbox for one of your end-users, pass the attribution:

```python
sandbox = client.sandboxes.create(
    template="python-ds",
    external_user_id="dr_smith@clinic1.example",
    external_workspace_id="clinic1",
    external_project_id="patient-intake-flow",
)
```

```typescript
const sandbox = await client.sandboxes.create({
  template: 'node-web',
  externalUserId: 'dr_smith@clinic1.example',
  externalWorkspaceId: 'clinic1',
  externalProjectId: 'patient-intake-flow',
});
```

```go
sandbox, err := client.Sandboxes.Create(ctx, miosa.SandboxCreate{
    Template:            "python-ds",
    ExternalUserID:      "dr_smith@clinic1.example",
    ExternalWorkspaceID: "clinic1",
    ExternalProjectID:   "patient-intake-flow",
})
```

```java
Sandbox sandbox = client.sandboxes().create(SandboxCreate.builder()
    .template("python-ds")
    .externalUserId("dr_smith@clinic1.example")
    .externalWorkspaceId("clinic1")
    .externalProjectId("patient-intake-flow")
    .build());
```

```elixir
{:ok, sandbox} = Miosa.Sandboxes.create(%{
  template: "python-ds",
  external_user_id: "dr_smith@clinic1.example",
  external_workspace_id: "clinic1",
  external_project_id: "patient-intake-flow"
})
```

The values you choose are opaque to MIOSA  -  they're whatever IDs make sense in your system.

## Storing a credential scoped to an end-user

Suppose Dr. Smith pastes her own OpenAI key into your UI. Save it scoped to her:

```python
client.secrets.set(
    name="openai_key",
    value="sk-proj-her-personal-key...",
    scope="external_user",
    external_user_id="dr_smith@clinic1.example",
    expose_as_env="OPENAI_API_KEY",
)
```

Now any sandbox you create with `external_user_id="dr_smith@clinic1.example"` resolves `OPENAI_API_KEY` to her key. Other clinicians at the same clinic do **not** see it.

For a clinic-wide credential (e.g., shared EHR access):

```python
client.secrets.set(
    name="ehr_api_key",
    value="...",
    scope="external_workspace",
    external_workspace_id="clinic1",
    expose_as_env="EHR_API_KEY",
)
```

## How the proxy decides which credential to use

When a sandbox makes an outbound call and the proxy needs to swap a placeholder, it walks (in priority order):

```
1. Direct binding on this specific sandbox
2. Secret scoped to user (owner_user_id  -  for MIOSA-native users)
3. Secret scoped to external_user (external_user_id match)
4. Secret scoped to external_workspace (external_workspace_id match)
5. Secret scoped to MIOSA workspace
6. Tenant-wide secret
```

First match wins. If nothing matches, the placeholder stays in the request and the upstream call fails (the right behavior  -  better than silently leaking).

## White-label OAuth (your branding, not MIOSA's)

By default, when one of your end-users clicks "Connect GitHub" in your UI, they're sent to GitHub with the consent screen showing **"Authorize MIOSA"**. For a true white-label experience, override that:

### 1. Register your own OAuth app on the provider

For GitHub:

```
https://github.com/settings/applications/new

Application name:  CliniCIQ Cloud
Homepage URL:      https://cliniciq.example
Authorization callback URL:  https://app.cliniciq.example/oauth/callback
```

### 2. Drop the credentials into MIOSA

In your tenant admin dashboard → Settings → OAuth Providers → "Add provider override":

```
Provider:       github
Display name:   GitHub
Client ID:      <from GitHub>
Client Secret:  <from GitHub>
Callback URL:   https://app.cliniciq.example/oauth/callback
Branding:       { "button_label": "Connect GitHub to CliniCIQ" }
```

From now on, when one of your end-users connects GitHub, they see "Authorize CliniCIQ Cloud"  -  your name, your branding, your callback domain.

### 3. Make sure your callback proxies to MIOSA

Your `https://app.cliniciq.example/oauth/callback` route receives the OAuth `code` parameter and forwards it to MIOSA's callback endpoint:

```python
@app.get("/oauth/callback")
def oauth_callback(request):
    code = request.query_params["code"]
    state = request.query_params["state"]
    # Forward to MIOSA
    return miosa.oauth.complete(provider="github", code=code, state=state)
```

MIOSA exchanges the code for tokens on your behalf and stores them in the vault.

## Per-user auditing

Audit log carries the full identity chain on every row, so you can query by your own user IDs:

```python
# All activity by one end-user
events = client.audit.list(
    since="7d",
    external_user_id="dr_smith@clinic1.example",
)

# All activity in one workspace
events = client.audit.list(
    since="30d",
    external_workspace_id="clinic1",
)
```

Same filters available in the UI.

## Privacy boundary

What a tenant admin (you, as the white-label operator) can do:

- ✅ See that a particular `external_user_id` has secrets bound to them
- ✅ Read audit rows showing which credential resolved for each call
- ✅ Disable a secret to immediately revoke access
- ❌ Re-read the encrypted value of any stored secret

The "you can't read stored values" rule applies to every actor in MIOSA  -  including the platform engineers. If one of your end-users ever asks "can CliniCIQ see my OpenAI key after I save it"  -  the answer is "no, the value is encrypted; only the request body that leaves your sandbox ever contains it, briefly, in transit."

## Disabling end-user-scoped credentials entirely

Some white-label customers want all credentials managed centrally  -  end-users can't bring their own keys. Toggle this in your tenant settings:

```
Settings → Security → "Allow end-user-scoped credentials" → Off
```

When off, only `tenant` and `external_workspace` scoped secrets resolve. End-user-scoped secret creation returns a 403.

## Real-world example  -  ClinicIQ: AI medical assistant per clinician

ClinicIQ is a healthcare SaaS built on MIOSA. Each clinician gets their own sandbox. They supply their own OpenAI key through the ClinicIQ settings page. The audit log is surfaced in ClinicIQ's compliance dashboard. GitHub OAuth shows "Authorize ClinicIQ" not "Authorize MIOSA."

```python

from miosa import Miosa
from flask import Flask, request, jsonify, redirect

app_server = Flask(__name__)
client = Miosa(api_key=os.environ["MIOSA_API_KEY"])

def get_or_create_sandbox(clinician_id: str, clinic_id: str):
    """Return existing sandbox or create a new one for this clinician."""
    sandboxes = client.sandboxes.list(external_user_id=clinician_id)
    if sandboxes:
        return sandboxes[0]
    return client.sandboxes.create(
        template="python-ds",
        external_user_id=clinician_id,
        external_workspace_id=clinic_id,
        external_project_id="medical-assistant",
    )

@app_server.post("/api/clinicians/<clinician_id>/openai-key")
def save_openai_key(clinician_id: str):
    """Clinician saves their own OpenAI key through the ClinicIQ settings page."""
    data = request.json
    client.secrets.set(
        name="openai_key",
        value=data["api_key"],
        scope="external_user",
        external_user_id=clinician_id,
        expose_as_env="OPENAI_API_KEY",
    )
    return jsonify({"status": "saved"})

@app_server.post("/api/clinicians/<clinician_id>/connect-github")
def connect_github(clinician_id: str):
    """Start GitHub OAuth for a clinician."""
    clinic_id = request.json["clinic_id"]
    sbx = get_or_create_sandbox(clinician_id, clinic_id)
    flow = sbx.secrets.connect(
        provider="github",
        expose_as_env="GITHUB_TOKEN",
        scopes=["repo", "read:user"],
    )
    return jsonify({"authorize_url": flow.authorize_url})

@app_server.get("/oauth/callback")
def oauth_callback():
    """OAuth callback forwarded from ClinicIQ's branded domain."""
    client.oauth.complete(
        provider="github",
        code=request.args["code"],
        state=request.args["state"],
    )
    return redirect("/dashboard?connected=github")

@app_server.get("/api/clinicians/<clinician_id>/activity")
def clinician_activity(clinician_id: str):
    """Per-clinician audit feed for the ClinicIQ compliance dashboard."""
    events = client.audit.list(
        since="7d",
        external_user_id=clinician_id,
        limit=200,
    )
    return jsonify([{
        "time": e.timestamp,
        "host": e.host,
        "action": e.action,
        "status": e.status_code,
    } for e in events])
```

```typescript

const app = express();
app.use(express.json());
const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

async function getOrCreateSandbox(clinicianId: string, clinicId: string) {
  const sandboxes = await client.sandboxes.list({ externalUserId: clinicianId });
  return sandboxes[0] ?? client.sandboxes.create({
    template: 'python-ds',
    externalUserId: clinicianId,
    externalWorkspaceId: clinicId,
    externalProjectId: 'medical-assistant',
  });
}

app.post('/api/clinicians/:clinicianId/openai-key', async (req, res) => {
  await client.secrets.set({
    name: 'openai_key',
    value: req.body.apiKey,
    scope: 'external_user',
    externalUserId: req.params.clinicianId,
    exposeAsEnv: 'OPENAI_API_KEY',
  });
  res.json({ status: 'saved' });
});

app.post('/api/clinicians/:clinicianId/connect-github', async (req, res) => {
  const sbx = await getOrCreateSandbox(req.params.clinicianId, req.body.clinicId);
  const flow = await sbx.secrets.connect({
    provider: 'github',
    exposeAsEnv: 'GITHUB_TOKEN',
    scopes: ['repo', 'read:user'],
  });
  res.json({ authorizeUrl: flow.authorizeUrl });
});

app.get('/oauth/callback', async (req, res) => {
  await client.oauth.complete({
    provider: 'github',
    code: req.query.code as string,
    state: req.query.state as string,
  });
  res.redirect('/dashboard?connected=github');
});

app.get('/api/clinicians/:clinicianId/activity', async (req, res) => {
  const events = await client.audit.list({
    since: '7d',
    externalUserId: req.params.clinicianId,
    limit: 200,
  });
  res.json(events.map(e => ({ time: e.timestamp, host: e.host, action: e.action, status: e.statusCode })));
});
```

## Troubleshooting

**Sandbox can't find the secret I stored for an end-user  -  env var is empty.**
The sandbox must have been created with the same `external_user_id` you used for the secret. Attribution is stamped at creation time and cannot be changed. Verify with `client.sandboxes.get(sandbox_id).external_user_id`.

**`scope="external_user"` returns HTTP 403.**
Your tenant has "Allow end-user-scoped credentials" disabled. Enable it in Settings → Security, or use `scope="external_workspace"` for workspace-level credentials instead.

**The resolver skips my workspace-scoped secret.**
The sandbox must have been created with a matching `external_workspace_id`. If the sandbox was created without it, the workspace-level scope walk entry is blank and won't match.

**OAuth consent screen still says "Authorize MIOSA" after I added a provider override.**
Double-check that the `client_id` in your override matches the OAuth app you registered with the provider, not MIOSA's default client ID. Remove and re-add the override if needed.

**My end-user can see other users' sandboxes in the MIOSA dashboard.**
End-users should not have MIOSA accounts or API keys. If they do, create a browser token scoped to that user instead: `client.browser_tokens.create(external_user_id="...")`. Browser tokens are read-only and scoped to that user's resources.

For more issues, see the [Security troubleshooting hub](/docs/security/troubleshooting).

## Frequently asked

**My end-users don't have MIOSA accounts. Can they still use OAuth Connect?**
Yes. The OAuth flow attributes the resulting token to whatever `external_user_id` your backend passes when initiating the flow.

**Can the same `external_user_id` exist in multiple tenants?**
Yes  -  `external_user_id` is scoped within a tenant. The same string in two different tenants represents two independent identities.

**What if an end-user is in two of my workspaces?**
You can create credentials at the workspace scope for each  -  the proxy resolves the correct one based on which sandbox is making the request.

**Can my end-users see the audit log themselves?**
That's your call  -  MIOSA gives you the audit data; how you expose it in your white-labeled UI is up to you. Most white-label customers surface "your activity" to end-users in their own dashboards.

**How do I migrate existing in-app secret storage to MIOSA Secrets?**
Bulk import via SDK is the easiest path:

```python
for user_id, openai_key in your_existing_secret_store.items():
    client.secrets.set(
        name="openai_key",
        value=openai_key,
        scope="external_user",
        external_user_id=user_id,
        expose_as_env="OPENAI_API_KEY",
    )
```

Once verified, delete from your old store.

---

# UI Components

URL: https://miosa.ai/docs/ui-components
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/ui-components
Source: src/routes/docs/ui-components/+page.md
Description: Drop-in React, Vue, and Svelte components for embedding MIOSA sandboxes in your own frontend.

`@miosa/react`, `@miosa/vue`, and `@miosa/svelte` are drop-in component libraries that let you embed live MIOSA sandboxes directly in your own frontend  -  no iframe glue code, no WebSocket wiring, no API plumbing.

Each package ships four production-ready components:

| Component | What it renders |
|---|---|
| `` | A sandboxed iframe showing your sandbox's HTTP preview URL |
| `` | A full xterm.js terminal connected to a sandbox PTY over WebSocket |
| `` | An interactive file browser backed by the sandbox filesystem |
| `` | A usage summary widget (compute seconds, storage, egress) per end-user |

## Auth model

Your MIOSA API key (`msk_*`) must stay on your server. Components that accept an `apiKey` prop are intended for **server-rendered** or **trusted-client** contexts only. For public-facing embeds, generate a short-lived preview token on your backend and pass it as `previewToken`.

The recommended pattern for public embeds:

Diagram:
sequenceDiagram
    participant Browser
    participant YourBackend
    participant MiosaAPI as api.miosa.ai

    Browser->>YourBackend: GET /sandbox-token?sandboxId=sb_...
    YourBackend->>MiosaAPI: POST /api/v1/sandboxes/{id}/preview-token
    Note over YourBackend,MiosaAPI: Uses msk_* API key  -  server only
    MiosaAPI-->>YourBackend: { token, expires_at }
    YourBackend-->>Browser: { token }
    Browser->>Browser:

`` and `` both accept a `previewToken` in place of an `apiKey`. Tokens are short-lived (1 hour by default) and scoped to a single sandbox.

## Which framework package to choose

| If you use... | Install |
|---|---|
| React / Next.js / Remix | `@miosa/react` |
| Vue 3 / Nuxt 3 | `@miosa/vue` |
| Svelte 5 / SvelteKit | `@miosa/svelte` |

The component APIs are structurally identical across all three packages. Prop names, event names, and behavior are the same  -  only the import path and framework idioms differ.

## Install

```bash
npm install @miosa/react
# peer deps required for MiosaTerminal
npm install @xterm/xterm @xterm/addon-fit
```

```bash
npm install @miosa/vue
# peer deps required for MiosaTerminal
npm install @xterm/xterm xterm-addon-fit
```

```bash
npm install @miosa/svelte
# peer deps required for MiosaTerminal
npm install @xterm/xterm xterm-addon-fit
```

Also add the stylesheet to your app entry point (React only  -  Vue and Svelte bundle their own scoped styles):

```ts

```

## See also

- [React components](/docs/ui-components/react)
- [Vue components](/docs/ui-components/vue)
- [Svelte components](/docs/ui-components/svelte)
- [Platform: Browser Tokens](/docs/platform/browser-tokens)
- [Develop: Previews](/docs/develop/previews)

---

# React UI Components

URL: https://miosa.ai/docs/ui-components/react
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/ui-components/react
Source: src/routes/docs/ui-components/react/+page.md
Description: Drop-in React components for embedding MIOSA sandboxes  -  MiosaPreview, MiosaTerminal, MiosaFileTree, MiosaUsage.

`@miosa/react` v0.2.0 provides four React components for embedding MIOSA sandboxes in any React application.

## Install

```bash
npm install @miosa/react
# xterm peer deps  -  required only if you use MiosaTerminal
npm install @xterm/xterm @xterm/addon-fit
```

Add the bundled stylesheet to your app entry point:

```ts

```

## MiosaThemeProvider

Wrap your component tree with `MiosaThemeProvider` to set a default theme for all nested Miosa components.

```tsx

export default function App() {
  return (

      {/* all Miosa components inherit theme="dark" */}

  );
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `theme` | `"dark" \| "light"` | `"dark"` | Visual theme applied to all child components |
| `injectStyles` | `boolean` | `false` | When `true`, lazily injects the stylesheet via a `<link>` tag. Prefer the explicit `import '@miosa/react/styles.css'` instead. |
| `children` | `React.ReactNode` |  -  | Required. Your component tree. |

---

## MiosaPreview

Renders a sandboxed `<iframe>` showing the HTTP preview URL for a running sandbox.

```tsx

// Using a short-lived preview token (recommended for public-facing embeds)

// Using an API key (server-rendered / trusted context only)

```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** The sandbox ID to preview. |
| `previewToken` | `string` |  -  | Short-lived preview token minted by your backend. Mutually exclusive with `apiKey`. |
| `apiKey` | `string` |  -  | Your MIOSA API key. Mutually exclusive with `previewToken`. Do not expose in the browser. |
| `theme` | `"dark" \| "light"` | `"dark"` | Visual theme. |
| `className` | `string` |  -  | CSS class forwarded to the root element. |
| `onError` | `(err: Error) => void` |  -  | Called when the preview URL cannot be resolved. |

Exactly one of `previewToken` or `apiKey` must be provided.

### States

The component progresses through `idle → loading → ready` (or `error`). A skeleton placeholder is shown while loading. On error, an accessible `role="alert"` message is rendered.

---

## MiosaTerminal

Renders a full PTY terminal connected to a sandbox over WebSocket, powered by xterm.js. The terminal auto-fits to its container and reconnects on resize.

`MiosaTerminal` requires `apiKey`  -  it does not support `previewToken`. Keep this component in server-rendered or internal tooling contexts.

```tsx

 console.log('resized to', cols, rows)}
  onError={(err) => console.error(err)}
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** The sandbox to connect to. |
| `apiKey` | `string` |  -  | **Required.** Your MIOSA API key. |
| `theme` | `"dark" \| "light"` | `"dark"` | Sets the xterm.js color theme. |
| `className` | `string` |  -  | CSS class forwarded to the root `<div>`. |
| `onResize` | `(cols: number, rows: number) => void` |  -  | Called whenever the terminal dimensions change. |
| `onError` | `(err: Error) => void` |  -  | Called on WebSocket errors or if xterm fails to load. |

### Peer dependencies

`@xterm/xterm` and `@xterm/addon-fit` are loaded dynamically at runtime (lazy import), so they will not bloat your initial bundle. The component falls back to the legacy `xterm` package name if `@xterm/xterm` is unavailable.

---

## MiosaFileTree

Renders an interactive file browser backed by the sandbox filesystem. Directories expand and collapse; clicking a file fires `onSelect`. The tree subscribes to filesystem change events and refreshes automatically.

```tsx

 openFile(file.path)}
  onChange={(tree: FileNode[]) => console.log('tree updated', tree)}
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** |
| `apiKey` | `string` |  -  | **Required.** |
| `theme` | `"dark" \| "light"` | `"dark"` | Visual theme. |
| `className` | `string` |  -  | CSS class on the root `<nav>`. |
| `showHidden` | `boolean` | `false` | When `true`, dotfiles and hidden directories are included. |
| `defaultExpanded` | `string[]` | `[]` | Array of directory paths to start expanded, e.g. `['/workspace/src']`. |
| `onSelect` | `(file: FileNode) => void` |  -  | Called when a file (not a directory) is clicked. |
| `onChange` | `(tree: FileNode[]) => void` |  -  | Called after each tree refresh with the full updated tree. |
| `onError` | `(err: Error) => void` |  -  | Called on load or watch errors. |

### FileNode type

```ts
interface FileNode {
  path: string;       // absolute path, e.g. "/workspace/src/index.ts"
  name: string;       // filename segment, e.g. "index.ts"
  type: 'file' | 'directory';
  children?: FileNode[]; // present for directories
}
```

---

## MiosaUsage

Renders a usage summary for a specific end-user  -  compute seconds, aggregated over a time period. Intended for billing dashboards in white-label products.

```tsx

```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `externalUserId` | `string` |  -  | **Required.** Your platform's user ID (the `external_user_id` used when creating sandboxes). |
| `apiKey` | `string` |  -  | **Required.** |
| `period` | `"7d" \| "30d" \| "90d"` | `"30d"` | Time window for usage aggregation. |
| `theme` | `"dark" \| "light"` | `"dark"` | Visual theme. |
| `className` | `string` |  -  | CSS class on the root element. |
| `onError` | `(err: Error) => void` |  -  | Called on fetch errors. |

The component renders a total usage count and a bar chart of daily buckets.

---

## Theming and styling

All components attach BEM class names to their root element for CSS targeting:

| Component | Root class |
|---|---|
| `MiosaPreview` | `.miosa-preview` |
| `MiosaTerminal` | `.miosa-terminal` |
| `MiosaFileTree` | `.miosa-file-tree` |
| `MiosaUsage` | `.miosa-usage` |

Theme variants are appended as modifier classes: `.miosa-preview--dark`, `.miosa-preview--light`, etc.

The `data-miosa-theme` attribute is also set on the root element, allowing CSS attribute selectors:

```css
[data-miosa-theme="dark"] .miosa-preview__frame {
  border: 1px solid #333;
}
```

---

## End-to-end example: Next.js

This example creates a sandbox on page load, then shows the preview, terminal, and file tree side by side.

**`app/api/sandbox-token/route.ts`**  -  backend token endpoint (never expose your API key to the client)

```ts

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

export async function POST(req: Request) {
  const { sandboxId } = await req.json() as { sandboxId: string };
  const sandbox = await client.sandboxes.get(sandboxId);
  // @ts-expect-error - previewToken is available on the sandbox object
  const { token } = await sandbox.previewToken(3600);
  return NextResponse.json({ token });
}
```

**`app/workbench/page.tsx`**  -  client component

```tsx
'use client';

  MiosaPreview,
  MiosaTerminal,
  MiosaFileTree,
  MiosaThemeProvider,
} from '@miosa/react';

const SANDBOX_ID = 'sb_abc123'; // created elsewhere in your app

export default function WorkbenchPage() {
  const [token, setToken] = useState<string | null>(null);
  const [selectedFile, setSelectedFile] = useState<string | null>(null);

  useEffect(() => {
    fetch('/api/sandbox-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sandboxId: SANDBOX_ID }),
    })
      .then((r) => r.json() as Promise<{ token: string }>)
      .then(({ token }) => setToken(token));
  }, []);

  if (!token) return <div>Loading workspace…</div>;

  return (

      <div style={{ display: 'grid', gridTemplateColumns: '240px 1fr 1fr', height: '100vh' }}>
        {/* File tree sidebar */}
         setSelectedFile(file.path)}
        />

        {/* Preview panel */}
        <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
          {selectedFile && (
            <div style={{ padding: '8px', fontSize: 12, color: '#888' }}>
              {selectedFile}
            </div>
          )}

        </div>

        {/* Terminal panel */}
         console.error('[terminal]', err)}
        />
      </div>

  );
}
```

In production, generate the preview token on your Next.js server side (e.g. a Server Component or API route) rather than in a `useEffect`. This keeps your API key entirely off the client.

## See also

- [UI Components overview](/docs/ui-components)
- [Platform: Browser Tokens](/docs/platform/browser-tokens)
- [Vue components](/docs/ui-components/vue)
- [Svelte components](/docs/ui-components/svelte)

---

# Svelte UI Components

URL: https://miosa.ai/docs/ui-components/svelte
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/ui-components/svelte
Source: src/routes/docs/ui-components/svelte/+page.md
Description: Drop-in Svelte 5 components for embedding MIOSA sandboxes  -  MiosaPreview, MiosaTerminal, MiosaFileTree, MiosaUsage.

`@miosa/svelte` v0.2.0 provides four Svelte 5 components for embedding MIOSA sandboxes. All components use Svelte 5 runes (`$props`, `$state`, `$derived`, `$effect`) and work with SvelteKit out of the box.

## Install

```bash
npm install @miosa/svelte
# xterm peer deps  -  required only if you use MiosaTerminal
npm install @xterm/xterm xterm-addon-fit
```

Styles are scoped inside each `.svelte` file  -  no global stylesheet import required.

## MiosaPreview

Renders a sandboxed `<iframe>` showing the HTTP preview URL for a running sandbox.

```svelte

 console.error(e.detail)}
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** The sandbox ID to preview. |
| `previewToken` | `string` |  -  | Short-lived preview token from your backend. Mutually exclusive with `apiKey`. |
| `apiKey` | `string` |  -  | Your MIOSA API key. Use only in `+page.server.svelte` or trusted SSR contexts. |
| `theme` | `"light" \| "dark"` | `"light"` | Visual theme. |
| `class` | `string` | `""` | CSS class forwarded to the root `<div>`. |

### Events

| Event | Detail | Description |
|---|---|---|
| `error` | `Error` | Dispatched when the preview URL cannot be resolved. |

Exactly one of `previewToken` or `apiKey` must be provided.

The component re-resolves the URL reactively whenever `sandboxId` changes (via `$effect`).

---

## MiosaTerminal

Renders a full PTY terminal connected to a sandbox over WebSocket, powered by xterm.js.

`MiosaTerminal` requires `apiKey`. Place it inside a `+page.server.svelte` data load or pass the key via a server-only environment variable  -  do not embed your API key in client-side markup.

```svelte

 console.log(e.detail.cols, e.detail.rows)}
  on:error={(e) => console.error(e.detail)}
  style="height: 400px"
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** |
| `apiKey` | `string` |  -  | **Required.** |
| `theme` | `"light" \| "dark"` | `"dark"` | Sets the xterm.js color scheme. |

### Events

| Event | Detail | Description |
|---|---|---|
| `resize` | `{ cols: number; rows: number }` | Dispatched when the terminal dimensions change. |
| `error` | `Error` | Dispatched on WebSocket errors or xterm load failure. |

The component auto-fits to its container via `ResizeObserver` and syncs resize events to the PTY. Cleanup (WebSocket close + terminal dispose) runs in `onDestroy`.

---

## MiosaFileTree

Renders a flat-list file browser backed by the sandbox filesystem. Directories expand inline on click; files dispatch a `select` event with the file path.

```svelte

 (selectedPath = e.detail)}
  on:change={(e) => console.log(e.detail.path, e.detail.type)}
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** |
| `apiKey` | `string` |  -  | **Required.** |
| `showHidden` | `boolean` | `false` | Include dotfiles and hidden directories. |
| `defaultExpanded` | `boolean` | `false` | When `true`, all directories start expanded. |

### Events

| Event | Detail | Description |
|---|---|---|
| `select` | `string` | Absolute path of the clicked file, e.g. `/workspace/src/index.ts`. |
| `change` | `{ path: string; type: "created" \| "deleted" \| "modified" }` | Dispatched on filesystem changes. |

The tree uses `$derived` to recompute the flat render list whenever a directory is toggled  -  no recursive component needed.

---

## MiosaUsage

Renders a three-column usage summary (compute seconds, storage GB·hours, egress GB) for a specific end-user.

```svelte

```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `externalUserId` | `string` |  -  | **Required.** Your platform's user ID, matching the `external_user_id` used when creating sandboxes. |
| `apiKey` | `string` |  -  | **Required.** |
| `period` | `"current" \| "last_30" \| "last_7"` | `"current"` | Billing period. `"current"` is the active billing cycle; `"last_30"` / `"last_7"` are rolling windows. |
| `theme` | `"light" \| "dark"` | `"light"` | Visual theme. |

Reactively reloads whenever `externalUserId` or `period` changes via `$effect`. No events are dispatched.

---

## createMiosaClient store

The package also exports a `createMiosaClient` helper for creating a shared client store:

```ts

const client = createMiosaClient({ apiKey: 'msk_...' });
```

This is intended for advanced use cases where you need direct SDK access alongside the components.

---

## End-to-end example: SvelteKit

**`src/routes/workbench/+page.server.ts`**  -  load preview token server-side

```ts

const SANDBOX_ID = 'sb_abc123';

export const load: PageServerLoad = async () => {
  const client = new Miosa({ apiKey: env.MIOSA_API_KEY });
  const sandbox = await client.sandboxes.get(SANDBOX_ID);
  // @ts-expect-error
  const { token } = await sandbox.previewToken(3600);
  return { sandboxId: SANDBOX_ID, previewToken: token };
};
```

**`src/routes/workbench/+page.svelte`**

```svelte

<div class="workbench">
  <aside class="workbench__sidebar">
     (selectedFile = e.detail)}
    />
  </aside>

  <main class="workbench__preview">
    {#if selectedFile}
      <div class="workbench__filepath">{selectedFile}</div>
    {/if}

  </main>

  <section class="workbench__terminal">
     console.error('[terminal]', e.detail)}
    />
  </section>
</div>

<style>
  .workbench {
    display: grid;
    grid-template-columns: 240px 1fr 1fr;
    height: 100vh;
    overflow: hidden;
  }
</style>
```

`$env/dynamic/private` is available only in server-side SvelteKit modules (`+page.server.ts`, hooks, etc.). Never import it in a `+page.svelte` or any other client-side file  -  SvelteKit will throw a build error if you try.

## See also

- [UI Components overview](/docs/ui-components)
- [Platform: Browser Tokens](/docs/platform/browser-tokens)
- [React components](/docs/ui-components/react)
- [Vue components](/docs/ui-components/vue)

---

# Vue UI Components

URL: https://miosa.ai/docs/ui-components/vue
Fallback URL: https://miosa.roberto-c49.workers.dev/docs/ui-components/vue
Source: src/routes/docs/ui-components/vue/+page.md
Description: Drop-in Vue 3 components for embedding MIOSA sandboxes  -  MiosaPreview, MiosaTerminal, MiosaFileTree, MiosaUsage.

`@miosa/vue` v0.2.0 provides four Vue 3 single-file components for embedding MIOSA sandboxes. All components are written with `

<template>
  <!-- Recommended: short-lived preview token from your backend -->
   console.error(err)"
  />
</template>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** The sandbox ID to preview. |
| `previewToken` | `string` |  -  | Short-lived preview token from your backend. Mutually exclusive with `apiKey`. |
| `apiKey` | `string` |  -  | Your MIOSA API key. Use only in trusted server-rendered contexts. |
| `theme` | `"light" \| "dark"` | `"light"` | Visual theme. |
| `class` | `string` |  -  | Forwarded to the root `<div>`. |

### Events

| Event | Payload | Description |
|---|---|---|
| `error` | `Error` | Emitted when the preview URL cannot be resolved. |

Exactly one of `previewToken` or `apiKey` must be provided.

---

## MiosaTerminal

Renders a full PTY terminal connected to a sandbox over WebSocket, powered by xterm.js.

`MiosaTerminal` requires `apiKey`. Keep it in server-rendered or internal tooling pages  -  do not expose your API key in public client-side code.

```vue

<template>
   console.log(cols, rows)"
    @error="(err) => console.error(err)"
    style="height: 400px"
  />
</template>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** |
| `apiKey` | `string` |  -  | **Required.** |
| `theme` | `"light" \| "dark"` | `"dark"` | Sets the xterm.js color scheme. |

### Events

| Event | Payload | Description |
|---|---|---|
| `resize` | `[cols: number, rows: number]` | Emitted when the terminal dimensions change. |
| `error` | `Error` | Emitted on WebSocket errors or xterm load failure. |

The component auto-fits to its container via `ResizeObserver` and syncs resize events to the PTY.

---

## MiosaFileTree

Renders a flat-list file browser backed by the sandbox filesystem. Directories expand inline on click; files emit a `select` event.

```vue

<template>
   console.log(path, type)"
  />
</template>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sandboxId` | `string` |  -  | **Required.** |
| `apiKey` | `string` |  -  | **Required.** |
| `showHidden` | `boolean` | `false` | Include dotfiles and hidden directories. |
| `defaultExpanded` | `boolean` | `false` | When `true`, all directories start expanded. |

### Events

| Event | Payload | Description |
|---|---|---|
| `select` | `path: string` | Emitted when a file is clicked. `path` is the absolute path within the sandbox (e.g. `/workspace/src/index.ts`). |
| `change` | `[path: string, type: "created" \| "deleted" \| "modified"]` | Emitted on filesystem changes (when the watch subscription fires). |

---

## MiosaUsage

Renders a three-column usage summary (compute, storage, egress) for a specific end-user.

```vue

<template>

</template>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `externalUserId` | `string` |  -  | **Required.** Your platform's user ID, matching the `external_user_id` used when creating sandboxes. |
| `apiKey` | `string` |  -  | **Required.** |
| `period` | `"current" \| "last_30" \| "last_7"` | `"current"` | Billing period to aggregate over. `"current"` is the current billing cycle; `"last_30"` / `"last_7"` are rolling day windows. |
| `theme` | `"light" \| "dark"` | `"light"` | Visual theme. |

Displays `compute_seconds`, `storage_gb_hours`, and `egress_gb`. No events are emitted.

---

## End-to-end example: Nuxt 3

**`server/api/sandbox-token.post.ts`**  -  server route (keeps API key off the client)

```ts

export default defineEventHandler(async (event) => {
  const { sandboxId } = await readBody<{ sandboxId: string }>(event);
  const client = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
  const sandbox = await client.sandboxes.get(sandboxId);
  // @ts-expect-error
  const { token } = await sandbox.previewToken(3600);
  return { token };
});
```

**`pages/workbench.vue`**

```vue

<template>
  <div class="workbench">
    <aside class="workbench__sidebar">
       (selectedFile = path)"
      />
    </aside>

    <main class="workbench__preview">
      <div v-if="selectedFile" class="workbench__filepath">{{ selectedFile }}</div>

    </main>

    <section class="workbench__terminal">
       console.error('[terminal]', err)"
      />
    </section>
  </div>
</template>

<style scoped>
.workbench {
  display: grid;
  grid-template-columns: 240px 1fr 1fr;
  height: 100vh;
  overflow: hidden;
}
</style>
```

In Nuxt 3, use `runtimeConfig` to expose the API key only on the server side (`runtimeConfig.miosaApiKey`, not `runtimeConfig.public.miosaApiKey`). This prevents it from being serialized into the client bundle.

## See also

- [UI Components overview](/docs/ui-components)
- [Platform: Browser Tokens](/docs/platform/browser-tokens)
- [React components](/docs/ui-components/react)
- [Svelte components](/docs/ui-components/svelte)