@pablofdezr/microvm 0.1.0

package/dist/types.gen.d.ts

@@ -0,0 +1,1557 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/sandboxes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List sandboxes */
+        get: operations["listSandboxes"];
+        put?: never;
+        /**
+         * Create a sandbox
+         * @description Boots a microVM and waits for it to answer. Returns once the sandbox is
+         *     ready to run commands.
+         *
+         *     Fails with `capacity_error` when the node has no room. That is
+         *     deliberate: a sandbox is a reservation, so the caller is told
+         *     immediately rather than left waiting. If you would rather wait, submit a
+         *     task.
+         */
+        post: operations["createSandbox"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Retrieve a sandbox
+         * @description Returns the sandbox with live metering.
+         */
+        get: operations["retrieveSandbox"];
+        put?: never;
+        post?: never;
+        /**
+         * Delete a sandbox
+         * @description Kills the VM and releases everything it held.
+         *
+         *     Returns the sandbox with its final metering. Those numbers are sampled
+         *     before the kill and cannot be obtained afterwards: the cgroup that holds
+         *     them dies with the VM, so this reply is the only record of what the
+         *     sandbox cost.
+         */
+        delete: operations["deleteSandbox"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}/executions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        /** List a sandbox's executions */
+        get: operations["listExecutions"];
+        put?: never;
+        /**
+         * Run a command
+         * @description Starts a command and returns immediately with the execution. It does not
+         *     wait for the command to finish.
+         *
+         *     To follow the output, stream the execution; to collect it afterwards,
+         *     retrieve it. Output is buffered on the host either way, so nothing is
+         *     lost between starting the command and connecting to its stream.
+         */
+        post: operations["createExecution"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}/executions/{execution}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Retrieve an execution
+         * @description Returns the execution and everything it printed.
+         *
+         *     This works after the sandbox is gone. Output is buffered on the host
+         *     precisely because the moment you most need it -- a timeout, a TTL, the
+         *     OOM killer -- is the moment a guest-side buffer would die with the VM.
+         */
+        get: operations["retrieveExecution"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}/executions/{execution}/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Stream an execution's output
+         * @description Server-sent events, one per output chunk, as the process produces them.
+         *     The stream ends with an `exit` or `error` event.
+         *
+         *     The stream replays from the start of the execution, so connecting late
+         *     loses nothing and a dropped connection can simply reconnect. This is why
+         *     starting a command and streaming it are separate calls: a single call
+         *     that did both would make the output unrecoverable the moment the
+         *     connection broke.
+         *
+         *     SSE rather than WebSockets because the traffic is one-directional: there
+         *     is no upgrade, no ping/pong, and it survives any proxy that speaks HTTP.
+         */
+        get: operations["streamExecution"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}/executions/{execution}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Cancel an execution
+         * @description Signals the process. The signal reaches the whole process group, so a
+         *     program that spawned children does not leave them running.
+         *
+         *     Defaults to SIGKILL. Hostile code is not owed a chance to clean up, and
+         *     a graceful signal it can ignore is a way to outlive its own cancel.
+         */
+        post: operations["cancelExecution"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandbox}/files": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Download a file
+         * @description The path is a query parameter rather than part of the route because a
+         *     file path contains slashes, and encoding them into a path segment would
+         *     make every caller escape their own paths to name a file.
+         */
+        get: operations["retrieveFile"];
+        put?: never;
+        /**
+         * Upload a file
+         * @description Writes a file into the sandbox, creating parent directories.
+         */
+        post: operations["createFile"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tasks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Submit a task
+         * @description Queues work for the fleet. Unlike creating a sandbox, this never fails
+         *     for capacity: the task waits for a slot on any node.
+         *
+         *     The queue is the source of truth. No node is told what to run; each
+         *     pulls when it has a free slot, which is why adding the three-hundredth
+         *     node needs no coordination and losing one needs no detection.
+         */
+        post: operations["createTask"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tasks/{task}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                task: components["parameters"]["TaskId"];
+            };
+            cookie?: never;
+        };
+        /** Retrieve a task */
+        get: operations["retrieveTask"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/queue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve the queue
+         * @description The queue's depth, plus this node's slots.
+         *
+         *     `pending`, `leased`, `done` and `failed` describe the whole fleet's
+         *     queue. `slots` and `busy` describe *this node only*: no node knows the
+         *     fleet's capacity, and none needs to, which is exactly what lets a node
+         *     be added without telling anything else it exists.
+         */
+        get: operations["retrieveQueue"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/images": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List images
+         * @description The language runtimes this node can boot.
+         */
+        get: operations["listImages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tenants": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List tenant policies
+         * @description Every tenant with a storage policy set. **Admin only.** A tenant with no
+         *     policy is unlimited and does not appear here.
+         */
+        get: operations["listTenants"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tenants/{tenant}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The tenant namespace, e.g. from a sandbox's `storage.namespace`. */
+                tenant: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * Retrieve a tenant's policy and usage
+         * @description A tenant's cap, policy, and how much of the cap is used right now.
+         *     **Admin only.** The usage is read from the object store, so it is the
+         *     real total, not an estimate.
+         */
+        get: operations["retrieveTenant"];
+        /**
+         * Set a tenant's storage policy
+         * @description Set the storage cap and full-policy for a tenant. **Admin only.** This is
+         *     the one thing an admin key can do that a normal key cannot, and it is
+         *     powerful: `evict` deletes a tenant's oldest data to make room, so setting
+         *     it is a decision to allow that deletion.
+         */
+        put: operations["updateTenant"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Health check
+         * @description Liveness. The one route that needs no credentials.
+         */
+        get: operations["retrieveHealth"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /** @description The body of every non-2xx reply. */
+        ErrorEnvelope: {
+            error: components["schemas"]["Error"];
+        };
+        Error: {
+            type: components["schemas"]["ErrorType"];
+            /**
+             * @description A stable, machine-readable identifier. Switch on this. The message is
+             *     for humans and may be reworded at any time.
+             * @example sandbox_not_found
+             */
+            code: string;
+            /**
+             * @description A human-readable explanation. Never parse it.
+             * @example No such sandbox: sb_01JZ8QK3M4N5P6R7S8T9V0W1X2
+             */
+            message: string;
+            /**
+             * @description Which request field was at fault, when one was.
+             * @example image
+             */
+            param?: string;
+            /** @description Quote this when reporting a problem. */
+            request_id?: string;
+        };
+        /**
+         * @description The class of error, which determines what a client should *do*:
+         *
+         *     - `invalid_request_error` — the request is wrong. Retrying it unchanged
+         *       will fail identically.
+         *     - `authentication_error` — the token is missing or wrong.
+         *     - `capacity_error` — no room right now. Retrying later may work; a task
+         *       would not have failed at all.
+         *     - `idempotency_error` — an Idempotency-Key was reused with a different
+         *       body.
+         *     - `api_error` — our fault. Safe to retry with the same Idempotency-Key.
+         * @enum {string}
+         */
+        ErrorType: "invalid_request_error" | "authentication_error" | "capacity_error" | "idempotency_error" | "api_error";
+        ListEnvelope: {
+            /** @enum {string} */
+            object: "list";
+            /** @description The endpoint this list came from. */
+            url: string;
+            /**
+             * @description Whether more objects exist past this page. Page on with
+             *     `starting_after` set to the last ID in `data`.
+             */
+            has_more: boolean;
+            data: Record<string, never>[];
+        };
+        /** @enum {string} */
+        SandboxState: "running" | "stopped";
+        /**
+         * @description Why a sandbox stopped. `stopped` means you asked; the rest happened to
+         *     it, and only `failed` means something went wrong.
+         * @enum {string}
+         */
+        SandboxStopReason: "stopped" | "expired" | "idle" | "failed";
+        Sandbox: {
+            /** @example sb_01JZ8QK3M4N5P6R7S8T9V0W1X2 */
+            id: string;
+            /** @enum {string} */
+            object: "sandbox";
+            /** @example python */
+            image: string;
+            state: components["schemas"]["SandboxState"];
+            /** @description Set once the sandbox is stopped. */
+            stop_reason?: components["schemas"]["SandboxStopReason"];
+            /** Format: date-time */
+            created: string;
+            /**
+             * Format: date-time
+             * @description When the TTL kills it, whatever it is doing.
+             */
+            expires: string;
+            /** Format: date-time */
+            stopped?: string | null;
+            vcpus?: number;
+            mem_mib?: number;
+            /** @description Whether filtered egress is on. */
+            network?: boolean;
+            /**
+             * @description Where this sandbox's files persist, when the node has object storage
+             *     configured. Absent when it does not.
+             */
+            storage?: components["schemas"]["SandboxStorage"];
+            stats: components["schemas"]["Stats"];
+        };
+        /**
+         * @description A sandbox's view of object storage. Files written here outlive the
+         *     sandbox and are reachable by every sandbox in the same `namespace`, which
+         *     is how state is carried from one run to the next.
+         */
+        SandboxStorage: {
+            /**
+             * @description The tenant your files live under, derived from your API key. It is
+             *     yours and stable: write a file today, read it from another sandbox
+             *     tomorrow. You cannot choose it — that is what stops one tenant from
+             *     naming another's.
+             * @example t_9f86d081884c7d659a2feaa0c55ad015
+             */
+            namespace: string;
+            /** @description Whether this sandbox may write, or only read. */
+            read_only: boolean;
+            /**
+             * @description Where storage is mounted inside the guest, e.g. `/mnt/storage`. This
+             *     is a directory in your own sandbox, not a namespace, so choosing it
+             *     reaches nobody else's files. Defaults to `/mnt/storage`.
+             * @example /mnt/storage
+             */
+            mount_path?: string;
+            /**
+             * Format: int64
+             * @description Your tenant's total storage cap in bytes, or 0 for unlimited. This is
+             *     the limit your writes are measured against; it is set by an admin.
+             */
+            max_bytes?: number;
+            /** @description What a write does when the cap is reached. Absent when there is no cap. */
+            policy?: components["schemas"]["TenantFullPolicy"];
+        };
+        SandboxList: components["schemas"]["ListEnvelope"] & {
+            data?: components["schemas"]["Sandbox"][];
+        };
+        /**
+         * @description What a sandbox has consumed. Cumulative since boot, so a biller must
+         *     diff two samples: booting alone costs a couple of CPU-seconds, and
+         *     cumulative idle is meaningless for a sandbox's first seconds.
+         */
+        Stats: {
+            /**
+             * @description CPU actually burned. **This is the billable number.** A sandbox
+             *     blocked on I/O bills nearly nothing: three seconds asleep costs
+             *     about 15ms of this.
+             */
+            active_cpu_ms: number;
+            /** @description How long the sandbox has existed. */
+            wall_ms: number;
+            /**
+             * @description `wall_ms` minus `active_cpu_ms`: existing but doing nothing. Zero
+             *     when a multi-vCPU sandbox burns more CPU than wall-clock.
+             */
+            idle_ms: number;
+            memory_current_bytes: number;
+            /** @description The high-water mark, which is what a memory limit must be sized against. */
+            memory_peak_bytes: number;
+        };
+        SandboxCreateParams: {
+            /**
+             * @description The language image.
+             * @example python
+             */
+            image: string;
+            /** @default 1 */
+            vcpus?: number;
+            /** @default 256 */
+            mem_mib?: number;
+            /**
+             * Format: double
+             * @description A hard CPU ceiling; may be fractional. 0.5 means half a core, enforced.
+             * @example 0.5
+             */
+            cpu_cores?: number;
+            disk_mib?: number;
+            /**
+             * @description Caps bandwidth both ways, in bytes per second. Worth setting even
+             *     when CPU is capped: a sandbox pinned to a quarter core can still
+             *     saturate the host's uplink, and the first you hear of it is the
+             *     abuse complaint.
+             */
+            network_bps?: number;
+            disk_bps?: number;
+            disk_iops?: number;
+            /**
+             * @description Filtered egress. The public internet is reachable; every private
+             *     range, link-local and the cloud metadata endpoint are not.
+             * @default false
+             */
+            network?: boolean;
+            /**
+             * @description Injected into every execution in this sandbox. An execution's own
+             *     env wins where they overlap.
+             *
+             *     Write-only. These usually carry credentials, so they are never
+             *     logged and no endpoint returns them. They are applied by the host on
+             *     each execution rather than written into the guest's filesystem,
+             *     where anything inside could read them long after the command that
+             *     needed them.
+             */
+            env?: {
+                [key: string]: string;
+            };
+            /**
+             * @description Maximum lifetime. The sandbox is killed when it elapses.
+             * @default 900
+             */
+            ttl_seconds?: number;
+            /**
+             * @description Reclaim after this long with nothing running. Negative disables it.
+             * @default 120
+             */
+            idle_seconds?: number;
+            /**
+             * @description Options for this sandbox's storage mount. The namespace is never set
+             *     here — it comes from your API key. Only the read/write posture is
+             *     yours to choose, and only to tighten.
+             */
+            storage?: components["schemas"]["SandboxStorageParams"];
+        };
+        /** @description What a create request may say about storage, which is very little. */
+        SandboxStorageParams: {
+            /**
+             * @description Mount storage read-only for this sandbox even if the key could write.
+             *     It can only tighten: a read-only key stays read-only whatever you set
+             *     here. Useful for a run that should read shared state but never touch it.
+             */
+            read_only?: boolean;
+            /**
+             * @description Where to mount storage inside the guest. An absolute, clean path using
+             *     only letters, digits and `_-./`; it names a directory in your own
+             *     sandbox and cannot reach another tenant's files. Defaults to
+             *     `/mnt/storage`.
+             * @example /data
+             */
+            mount_path?: string;
+        };
+        /**
+         * @description What a write does when a tenant is at its cap.
+         *
+         *     - `preserve` — reject the write and keep what is stored. For data that
+         *       matters more than the next write: an audit trail, a paid-for dataset.
+         *     - `evict` — delete the oldest objects until the write fits. For a cache
+         *       or scratch space, where the newest data is the point. It deletes data,
+         *       irreversibly, which is why it is never the default.
+         * @enum {string}
+         */
+        TenantFullPolicy: "preserve" | "evict";
+        Tenant: {
+            /** @enum {string} */
+            object: "tenant";
+            /**
+             * @description The tenant namespace this policy applies to.
+             * @example t_9f86d081884c7d659a2feaa0c55ad015
+             */
+            id: string;
+            /**
+             * Format: int64
+             * @description The tenant's total storage cap, in bytes. 0 means unlimited.
+             */
+            max_bytes: number;
+            policy: components["schemas"]["TenantFullPolicy"];
+            /**
+             * Format: int64
+             * @description Bytes currently stored, read from the object store on retrieve. Absent
+             *     on the reply to an update, which does not stop to scan the bucket.
+             */
+            usage_bytes?: number;
+        };
+        TenantList: components["schemas"]["ListEnvelope"] & {
+            data?: components["schemas"]["Tenant"][];
+        };
+        TenantUpdateParams: {
+            /**
+             * Format: int64
+             * @description The tenant's total storage cap, in bytes. 0 means unlimited.
+             * @example 1073741824
+             */
+            max_bytes: number;
+            policy: components["schemas"]["TenantFullPolicy"];
+        };
+        /**
+         * @description Outcomes that all look like failure but are not, and a caller must tell
+         *     apart:
+         *
+         *     - `running` — still going.
+         *     - `exited` — your code ran to completion. `exit_code` is its own verdict.
+         *     - `timed_out` — it exceeded its timeout and we killed it.
+         *     - `canceled` — you cancelled it.
+         *     - `vanished` — **we took the VM away.** Your code did not fail.
+         *     - `failed` — the command could never start, e.g. no such binary.
+         * @enum {string}
+         */
+        ExecutionStatus: "running" | "exited" | "timed_out" | "canceled" | "vanished" | "failed";
+        Execution: {
+            /** @example exe_01JZ8QK3M4N5P6R7S8T9V0W1X2 */
+            id: string;
+            /** @enum {string} */
+            object: "execution";
+            /** @example sb_01JZ8QK3M4N5P6R7S8T9V0W1X2 */
+            sandbox: string;
+            /** @example python3 */
+            cmd: string;
+            args?: string[];
+            status: components["schemas"]["ExecutionStatus"];
+            exit_code?: number | null;
+            /**
+             * @description The signal that killed it, if one did.
+             * @example SIGKILL
+             */
+            signal?: string | null;
+            /** @description Why the command could never start. Set only when status is `failed`. */
+            error?: string;
+            stdout: string;
+            stderr: string;
+            /**
+             * @description Output exceeded the retention cap and the oldest bytes were dropped.
+             *     The *tail* is kept, because that is where a traceback is. Never
+             *     silently truncated: a partial log that looks complete is worse than
+             *     no log.
+             */
+            stdout_truncated?: boolean;
+            stderr_truncated?: boolean;
+            /** Format: date-time */
+            created: string;
+            /** Format: date-time */
+            finished?: string | null;
+            duration_ms?: number;
+        };
+        ExecutionList: components["schemas"]["ListEnvelope"] & {
+            data?: components["schemas"]["Execution"][];
+        };
+        ExecutionCreateParams: {
+            /** @example python3 */
+            cmd: string;
+            /**
+             * @example [
+             *       "main.py"
+             *     ]
+             */
+            args?: string[];
+            /** @description Merged over the sandbox's env; these win. Write-only. */
+            env?: {
+                [key: string]: string;
+            };
+            cwd?: string;
+            /**
+             * Format: byte
+             * @description Written to the process, then closed.
+             */
+            stdin?: string;
+            /**
+             * @description Kills the process group when exceeded.
+             * @default 300
+             */
+            timeout_seconds?: number;
+        };
+        ExecutionCancelParams: {
+            /**
+             * @description The signal to send. It reaches the whole process group.
+             * @default SIGKILL
+             * @example SIGKILL
+             */
+            signal?: string;
+        };
+        File: {
+            /** @enum {string} */
+            object: "file";
+            /** @example /app/main.py */
+            path: string;
+            size_bytes: number;
+        };
+        FileCreateParams: {
+            /**
+             * @description Absolute path inside the sandbox. Parent directories are created.
+             * @example /app/main.py
+             */
+            path: string;
+            /**
+             * Format: byte
+             * @description The file's bytes, base64 encoded so binary survives the trip.
+             */
+            content: string;
+        };
+        /**
+         * @description - `pending` — waiting for a slot anywhere in the fleet.
+         *     - `running` — a node holds it.
+         *     - `done` — it ran. `exit_code` is your code's own verdict, and a
+         *       non-zero one is still `done`.
+         *     - `failed` — **our** failure: no node could run it, after its attempts
+         *       ran out.
+         * @enum {string}
+         */
+        TaskStatus: "pending" | "running" | "done" | "failed";
+        Task: {
+            /** @example tsk_01JZ8QK3M4N5P6R7S8T9V0W1X2 */
+            id: string;
+            /** @enum {string} */
+            object: "task";
+            status: components["schemas"]["TaskStatus"];
+            exit_code?: number | null;
+            stdout?: string;
+            stderr?: string;
+            /**
+             * @description An infrastructure failure. Distinct from a non-zero exit, which is
+             *     the caller's own code and not a failure of ours.
+             */
+            error?: string;
+            /**
+             * @description How many tries it took. Retries are for nodes dying, not for code
+             *     failing: a task whose process exits non-zero is never retried, or a
+             *     caller's bug would be run repeatedly and billed for each attempt.
+             */
+            attempts?: number;
+            /** Format: date-time */
+            created?: string;
+            /** Format: date-time */
+            started?: string | null;
+            /** Format: date-time */
+            finished?: string | null;
+            active_cpu_ms?: number;
+            memory_peak_bytes?: number;
+        };
+        TaskCreateParams: {
+            /** @example python */
+            image: string;
+            /** @example python3 */
+            cmd: string;
+            args?: string[];
+            /** @description Write-only. */
+            env?: {
+                [key: string]: string;
+            };
+            /**
+             * @description Written into the sandbox before the command runs, keyed by path.
+             * @example {
+             *       "/app/main.py": "cHJpbnQoImhpIik="
+             *     }
+             */
+            files?: {
+                [key: string]: string;
+            };
+            /** @default 300 */
+            timeout_seconds?: number;
+            /** @default false */
+            network?: boolean;
+            /** @default 1 */
+            vcpus?: number;
+            /** @default 256 */
+            mem_mib?: number;
+            /** Format: double */
+            cpu_cores?: number;
+            /**
+             * @description Scheduling priority, 0 to 10. Higher runs first; equal priorities are
+             *     FIFO, which is the guarantee callers actually reason about. It orders
+             *     the queue within what a node can fit: among the tasks a node has room
+             *     for, the highest priority is taken first, so a high-priority task that
+             *     does not fit yields to a lower one that does rather than blocking it.
+             * @default 0
+             */
+            priority?: number;
+            /**
+             * @description How many times a node may try this before it is failed for good. Two
+             *     means one retry: enough to survive a node dying, few enough that a
+             *     task which reliably kills its worker cannot cycle the fleet forever.
+             * @default 2
+             */
+            max_attempts?: number;
+        };
+        Queue: {
+            /** @enum {string} */
+            object: "queue";
+            pending: number;
+            /** @description Held by a worker somewhere in the fleet. */
+            leased: number;
+            done: number;
+            failed: number;
+            /**
+             * @description How long the head of the queue has waited. This is the number that
+             *     says whether the fleet is big enough.
+             */
+            oldest_pending_ms: number;
+            /** @description This node's slots. Not the fleet's. */
+            slots: number;
+            /** @description This node's slots currently running something. */
+            busy: number;
+        };
+        Image: {
+            /** @enum {string} */
+            object: "image";
+            /** @example python */
+            id: string;
+            /** @example python */
+            language: string;
+            /** @example arm64 */
+            arch?: string;
+            size_bytes?: number;
+        };
+        ImageList: components["schemas"]["ListEnvelope"] & {
+            data?: components["schemas"]["Image"][];
+        };
+        Health: {
+            /** @enum {string} */
+            object: "health";
+            ok: boolean;
+            version: string;
+        };
+        /** @description One event in an execution's stream, sent as an SSE data payload. */
+        Frame: {
+            /** @enum {string} */
+            object: "frame";
+            /** @enum {string} */
+            type: "started" | "stdout" | "stderr" | "exit" | "error";
+            /**
+             * Format: byte
+             * @description The chunk, base64 so binary output survives the trip.
+             */
+            data?: string;
+            pid?: number;
+            exit_code?: number | null;
+            signal?: string;
+            timed_out?: boolean;
+            message?: string;
+        };
+    };
+    responses: {
+        /** @description The request is malformed or contradicts itself. */
+        InvalidRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description The token is missing or wrong. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /**
+         * @description The token is valid but lacks the power for this. Distinct from 401 on
+         *     purpose: 401 means "log in", 403 means "you are logged in and still may
+         *     not". Setting a tenant policy needs an admin key.
+         */
+        Forbidden: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description No such object. */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description The object already exists, or is in a state that forbids this. */
+        Conflict: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description This node has no free slot. Retry, or submit a task instead. */
+        CapacityExhausted: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /**
+         * @description The queue could not be reached, so nothing is known about the task. This
+         *     is deliberately not a 404: "we cannot ask" and "it does not exist" call
+         *     for opposite reactions from a client, and reporting the first as the
+         *     second would have a caller give up on work that is running fine.
+         */
+        QueueUnreachable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description Something failed on our side. */
+        ApiError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+    };
+    parameters: {
+        SandboxId: string;
+        ExecutionId: string;
+        TaskId: string;
+        /** @description How many objects to return, 1–100. */
+        Limit: number;
+        /**
+         * @description A cursor. Returns the page of objects immediately after this ID, which
+         *     is the ID of the last object on the previous page.
+         */
+        StartingAfter: string;
+        /**
+         * @description A cursor, for paging backwards. Returns the page immediately before this
+         *     ID, which is the ID of the first object on the current page.
+         */
+        EndingBefore: string;
+        /**
+         * @description Makes a retry safe. A request that never got its reply -- a timeout, a
+         *     dropped connection -- cannot be known to have failed, so the only sane
+         *     move is to retry it; without a key, that retry runs the work twice.
+         *
+         *     The first request with a given key is executed and its reply recorded.
+         *     Any later request with the same key replays that reply, without doing
+         *     the work again. Keys are held for 24 hours and are scoped to the token.
+         *
+         *     Reusing a key with a *different* request body is an `idempotency_error`:
+         *     it means the client believes it is retrying something it is not.
+         */
+        IdempotencyKey: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    listSandboxes: {
+        parameters: {
+            query?: {
+                /** @description How many objects to return, 1–100. */
+                limit?: components["parameters"]["Limit"];
+                /**
+                 * @description A cursor. Returns the page of objects immediately after this ID, which
+                 *     is the ID of the last object on the previous page.
+                 */
+                starting_after?: components["parameters"]["StartingAfter"];
+                /**
+                 * @description A cursor, for paging backwards. Returns the page immediately before this
+                 *     ID, which is the ID of the first object on the current page.
+                 */
+                ending_before?: components["parameters"]["EndingBefore"];
+                /** @description Only sandboxes in this state. */
+                state?: components["schemas"]["SandboxState"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A page of sandboxes, newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SandboxList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
+    createSandbox: {
+        parameters: {
+            query?: never;
+            header?: {
+                /**
+                 * @description Makes a retry safe. A request that never got its reply -- a timeout, a
+                 *     dropped connection -- cannot be known to have failed, so the only sane
+                 *     move is to retry it; without a key, that retry runs the work twice.
+                 *
+                 *     The first request with a given key is executed and its reply recorded.
+                 *     Any later request with the same key replays that reply, without doing
+                 *     the work again. Keys are held for 24 hours and are scoped to the token.
+                 *
+                 *     Reusing a key with a *different* request body is an `idempotency_error`:
+                 *     it means the client believes it is retrying something it is not.
+                 */
+                "Idempotency-Key"?: components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SandboxCreateParams"];
+            };
+        };
+        responses: {
+            /** @description The sandbox is running and ready. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Sandbox"];
+                };
+            };
+            400: components["responses"]["InvalidRequest"];
+            401: components["responses"]["Unauthorized"];
+            409: components["responses"]["Conflict"];
+            429: components["responses"]["CapacityExhausted"];
+            500: components["responses"]["ApiError"];
+        };
+    };
+    retrieveSandbox: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sandbox. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Sandbox"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    deleteSandbox: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sandbox, stopped, with its final cost. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Sandbox"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    listExecutions: {
+        parameters: {
+            query?: {
+                /** @description How many objects to return, 1–100. */
+                limit?: components["parameters"]["Limit"];
+                /**
+                 * @description A cursor. Returns the page of objects immediately after this ID, which
+                 *     is the ID of the last object on the previous page.
+                 */
+                starting_after?: components["parameters"]["StartingAfter"];
+                /**
+                 * @description A cursor, for paging backwards. Returns the page immediately before this
+                 *     ID, which is the ID of the first object on the current page.
+                 */
+                ending_before?: components["parameters"]["EndingBefore"];
+            };
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A page of executions, newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ExecutionList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    createExecution: {
+        parameters: {
+            query?: never;
+            header?: {
+                /**
+                 * @description Makes a retry safe. A request that never got its reply -- a timeout, a
+                 *     dropped connection -- cannot be known to have failed, so the only sane
+                 *     move is to retry it; without a key, that retry runs the work twice.
+                 *
+                 *     The first request with a given key is executed and its reply recorded.
+                 *     Any later request with the same key replays that reply, without doing
+                 *     the work again. Keys are held for 24 hours and are scoped to the token.
+                 *
+                 *     Reusing a key with a *different* request body is an `idempotency_error`:
+                 *     it means the client believes it is retrying something it is not.
+                 */
+                "Idempotency-Key"?: components["parameters"]["IdempotencyKey"];
+            };
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecutionCreateParams"];
+            };
+        };
+        responses: {
+            /** @description The command is running. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Execution"];
+                };
+            };
+            400: components["responses"]["InvalidRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    retrieveExecution: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The execution. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Execution"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    streamExecution: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A stream of frames. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": components["schemas"]["Frame"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    cancelExecution: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+                execution: components["parameters"]["ExecutionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ExecutionCancelParams"];
+            };
+        };
+        responses: {
+            /** @description The execution. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Execution"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    retrieveFile: {
+        parameters: {
+            query: {
+                /** @description Absolute path inside the sandbox. */
+                path: string;
+            };
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The file's contents. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/octet-stream": string;
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    createFile: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                sandbox: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FileCreateParams"];
+            };
+        };
+        responses: {
+            /** @description The file was written. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["File"];
+                };
+            };
+            400: components["responses"]["InvalidRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    createTask: {
+        parameters: {
+            query?: never;
+            header?: {
+                /**
+                 * @description Makes a retry safe. A request that never got its reply -- a timeout, a
+                 *     dropped connection -- cannot be known to have failed, so the only sane
+                 *     move is to retry it; without a key, that retry runs the work twice.
+                 *
+                 *     The first request with a given key is executed and its reply recorded.
+                 *     Any later request with the same key replays that reply, without doing
+                 *     the work again. Keys are held for 24 hours and are scoped to the token.
+                 *
+                 *     Reusing a key with a *different* request body is an `idempotency_error`:
+                 *     it means the client believes it is retrying something it is not.
+                 */
+                "Idempotency-Key"?: components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TaskCreateParams"];
+            };
+        };
+        responses: {
+            /** @description The task is queued. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Task"];
+                };
+            };
+            400: components["responses"]["InvalidRequest"];
+            401: components["responses"]["Unauthorized"];
+            409: components["responses"]["Conflict"];
+            503: components["responses"]["QueueUnreachable"];
+        };
+    };
+    retrieveTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                task: components["parameters"]["TaskId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The task, with its result once it has one. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Task"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            503: components["responses"]["QueueUnreachable"];
+        };
+    };
+    retrieveQueue: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The queue. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Queue"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            503: components["responses"]["QueueUnreachable"];
+        };
+    };
+    listImages: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The images. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ImageList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
+    listTenants: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The configured tenants. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TenantList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    retrieveTenant: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The tenant namespace, e.g. from a sandbox's `storage.namespace`. */
+                tenant: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The tenant. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Tenant"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    updateTenant: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The tenant namespace, e.g. from a sandbox's `storage.namespace`. */
+                tenant: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TenantUpdateParams"];
+            };
+        };
+        responses: {
+            /** @description The updated tenant. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Tenant"];
+                };
+            };
+            400: components["responses"]["InvalidRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    retrieveHealth: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The daemon is up. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Health"];
+                };
+            };
+        };
+    };
+}