@sistemo/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,69 @@
+# @sistemo/sdk (JavaScript / TypeScript)
+
+Run AI agents and untrusted code in **real isolated Firecracker microVMs** — self-host for free or use the cloud.
+
+```bash
+npm install @sistemo/sdk
+```
+
+Requires Node 18+ (uses the global `fetch`). Zero runtime dependencies.
+
+## Quickstart (< 10 lines)
+
+```ts
+import { Sandbox } from "@sistemo/sdk";
+
+const sb = await Sandbox.create();                  // reads SISTEMO_API_KEY
+const res = await sb.run("node -e 'console.log(2 + 2)'");
+console.log(res.stdout, res.exitCode);              // "4\n" 0
+await sb.close();
+```
+
+Get an API key from the dashboard (**Dashboard → API Keys**), then:
+
+```bash
+export SISTEMO_API_KEY=sk_live_xxxxxxxx
+```
+
+## Configuration
+
+| | |
+|---|---|
+| `SISTEMO_API_KEY` | your key (`sk_live_…`). Required. |
+| `SISTEMO_BASE_URL` | override the API URL (default `https://api.sistemo.io`). |
+
+Or pass them explicitly: `Sandbox.create({ apiKey: "sk_live_…", baseUrl: "https://…" })`.
+
+## API
+
+```ts
+const sb = await Sandbox.create({ vcpus: 1, memoryMb: 1024, stack: "base" });
+const res = await sb.run("echo hi && uname -a", 30); // -> { exitCode, stdout, stderr }
+await sb.close();                                    // destroy
+```
+
+A **read** API key can list resources but cannot create sandboxes or run code — use a **full** key with the SDK.
+
+## Errors
+
+```ts
+import { APIError, AuthError, QuotaExceededError } from "@sistemo/sdk";
+
+try {
+  const sb = await Sandbox.create();
+  await sb.run("...");
+} catch (e) {
+  // Check QuotaExceededError FIRST — it and AuthError both arrive as 403, but
+  // they need opposite handling: an auth failure never succeeds on retry, a
+  // quota refusal does once you free the resource it names.
+  if (e instanceof QuotaExceededError) { console.log(e.detail); }
+  else if (e instanceof AuthError) { /* 401/403 — key invalid or read-only */ }
+  else if (e instanceof APIError) { console.log(e.status, e.detail, e.code); }
+}
+```
+
+`QuotaExceededError` means an account limit was reached; `detail` names which
+dimension bound and how much is in use, and `GET /v1/quotas` reports every limit
+alongside current usage.
+
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Sistemo — run AI agents and untrusted code in real isolated microVMs.
+ *
+ * ```ts
+ * import { Sandbox } from "@sistemo/sdk";
+ *
+ * const sb = await Sandbox.create();              // reads SISTEMO_API_KEY
+ * const res = await sb.run("python3 -c 'print(2 + 2)'");
+ * console.log(res.stdout, res.exitCode);
+ * await sb.close();
+ * ```
+ */
+export declare class SistemoError extends Error {
+}
+export declare class APIError extends SistemoError {
+    readonly status: number;
+    readonly detail: string;
+    readonly code?: string;
+    constructor(status: number, detail: string, code?: string);
+}
+/** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
+export declare class AuthError extends APIError {
+}
+/**
+ * 403 `quota_exceeded` — an account limit was reached.
+ *
+ * Deliberately NOT an `AuthError`, even though both arrive as 403. They need
+ * opposite handling, and conflating them sends callers to the wrong place:
+ *
+ * - `AuthError` — the credential cannot do this. Retrying never helps.
+ * - `QuotaExceededError` — the credential is fine and the request is valid.
+ *   **Retrying succeeds once the resource is freed** (stop or destroy a machine,
+ *   delete a volume) or the limit is raised.
+ *
+ * `detail` names the dimension that bound and how much is in use; `GET /v1/quotas`
+ * reports every limit alongside current usage. A message mentioning "fleet limit"
+ * is a fleet-wide ceiling rather than your plan, which topping up will not lift.
+ */
+export declare class QuotaExceededError extends APIError {
+}
+/** 404 — resource not found (or not yours). */
+export declare class NotFoundError extends APIError {
+}
+/** 429 — rate limited. */
+export declare class RateLimitError extends APIError {
+}
+export interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 120000 — create blocks until boot). */
+    timeoutMs?: number;
+    /** Extra attempts after the first (default 2 → up to 3 tries). */
+    maxRetries?: number;
+    /** Base backoff in ms (default 400). */
+    retryBackoffMs?: number;
+    /** Cap on backoff in ms (default 8000). */
+    retryMaxBackoffMs?: number;
+}
+export interface RequestOptions {
+    headers?: Record<string, string>;
+    /** Enables safe HTTP retries for mutating methods. */
+    idempotencyKey?: string;
+    /** Override client maxRetries for this call. */
+    maxRetries?: number;
+}
+/** Low-level API client. Most users want {@link Sandbox} instead. */
+export declare class Client {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    private readonly retryMaxBackoffMs;
+    constructor(opts?: ClientOptions);
+    request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    private once;
+    private shouldRetryHttp;
+    private backoff;
+    /** List the account's volumes (root and data). */
+    listVolumes(): Promise<{
+        volumes: Volume[];
+    }>;
+    /** Create a standalone data volume. */
+    createVolume(name: string, sizeGb: number): Promise<Volume>;
+    /** Attach a volume (root or data) to a STOPPED machine. */
+    attachVolume(machineId: string, volumeId: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Detach a volume from a STOPPED machine. A detached root volume's disk is
+     * preserved and can be re-attached or booted onto a new sandbox.
+     */
+    detachVolume(machineId: string, volumeId: string): Promise<{
+        status: string;
+    }>;
+    /** Delete a detached volume. */
+    deleteVolume(volumeId: string): Promise<{
+        status: string;
+    }>;
+}
+export interface Volume {
+    id: string;
+    name: string;
+    size_gb: number;
+    role: string;
+    state: string;
+    machine_id?: string;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface SandboxOptions extends ClientOptions {
+    client?: Client;
+    name?: string;
+    vcpus?: number;
+    memoryMb?: number;
+    rootfsSizeGb?: number;
+    stack?: string;
+    metadata?: Record<string, unknown>;
+    /** Boot from an existing (detached/preserved) root volume instead of a fresh
+     * template clone. Size/stack come from the volume. */
+    rootVolumeId?: string;
+    /** Optional fixed Idempotency-Key for create (default: random UUID). */
+    idempotencyKey?: string;
+}
+/** An isolated microVM you can run code in. Create with {@link Sandbox.create}. */
+export declare class Sandbox {
+    readonly id: string;
+    state: string;
+    private readonly client;
+    private constructor();
+    /** Provision a new microVM (resolves once it has booted). */
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    /** Run a shell command/script inside the sandbox. */
+    run(script: string, timeoutSec?: number): Promise<ExecResult>;
+    /** Destroy the sandbox (and its disk unless `preserveStorage`). */
+    close(preserveStorage?: boolean): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,256 @@
+/**
+ * Sistemo — run AI agents and untrusted code in real isolated microVMs.
+ *
+ * ```ts
+ * import { Sandbox } from "@sistemo/sdk";
+ *
+ * const sb = await Sandbox.create();              // reads SISTEMO_API_KEY
+ * const res = await sb.run("python3 -c 'print(2 + 2)'");
+ * console.log(res.stdout, res.exitCode);
+ * await sb.close();
+ * ```
+ */
+const DEFAULT_BASE_URL = "https://api.sistemo.io";
+// Sent on every request from non-browser runtimes (Node/Bun/Deno). A real
+// User-Agent is required: the production WAF (Cloudflare) blocks generic
+// library UAs with a 403. Browsers ignore attempts to set User-Agent and send
+// their own (which the WAF allows), so this is a no-op there.
+const USER_AGENT = "@sistemo/sdk/0.1.0";
+const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+export class SistemoError extends Error {
+}
+export class APIError extends SistemoError {
+    status;
+    detail;
+    code;
+    constructor(status, detail, code) {
+        super(`[${status}] ${detail}${code ? ` (${code})` : ""}`);
+        this.name = "APIError";
+        this.status = status;
+        this.detail = detail;
+        this.code = code;
+    }
+}
+/** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
+export class AuthError extends APIError {
+}
+/**
+ * 403 `quota_exceeded` — an account limit was reached.
+ *
+ * Deliberately NOT an `AuthError`, even though both arrive as 403. They need
+ * opposite handling, and conflating them sends callers to the wrong place:
+ *
+ * - `AuthError` — the credential cannot do this. Retrying never helps.
+ * - `QuotaExceededError` — the credential is fine and the request is valid.
+ *   **Retrying succeeds once the resource is freed** (stop or destroy a machine,
+ *   delete a volume) or the limit is raised.
+ *
+ * `detail` names the dimension that bound and how much is in use; `GET /v1/quotas`
+ * reports every limit alongside current usage. A message mentioning "fleet limit"
+ * is a fleet-wide ceiling rather than your plan, which topping up will not lift.
+ */
+export class QuotaExceededError extends APIError {
+}
+/** 404 — resource not found (or not yours). */
+export class NotFoundError extends APIError {
+}
+/** 429 — rate limited. */
+export class RateLimitError extends APIError {
+}
+function apiError(status, detail, code) {
+    // 403 is two different things, told apart by `code` — never by the status.
+    if (status === 403 && code === "quota_exceeded")
+        return new QuotaExceededError(status, detail, code);
+    if (status === 401 || status === 403)
+        return new AuthError(status, detail, code);
+    if (status === 404)
+        return new NotFoundError(status, detail, code);
+    if (status === 429)
+        return new RateLimitError(status, detail, code);
+    return new APIError(status, detail, code);
+}
+function newIdempotencyKey() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return `idem-${Date.now()}-${Math.random().toString(36).slice(2, 12)}`;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Low-level API client. Most users want {@link Sandbox} instead. */
+export class Client {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    retryBackoffMs;
+    retryMaxBackoffMs;
+    constructor(opts = {}) {
+        const g = globalThis;
+        const env = g.process?.env ?? {};
+        const apiKey = opts.apiKey ?? env.SISTEMO_API_KEY;
+        if (!apiKey) {
+            throw new SistemoError("no API key — pass { apiKey } or set the SISTEMO_API_KEY environment variable");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (opts.baseUrl ?? env.SISTEMO_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 120_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.retryBackoffMs = opts.retryBackoffMs ?? 400;
+        this.retryMaxBackoffMs = opts.retryMaxBackoffMs ?? 8_000;
+    }
+    async request(method, path, body, opts = {}) {
+        const retries = opts.maxRetries ?? this.maxRetries;
+        const methodU = method.toUpperCase();
+        let lastErr;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                return await this.once(methodU, path, body, opts);
+            }
+            catch (e) {
+                lastErr = e;
+                const can = attempt < retries &&
+                    (e instanceof APIError
+                        ? this.shouldRetryHttp(methodU, e.status, opts.idempotencyKey)
+                        : e instanceof SistemoError); // connection / abort
+                if (!can)
+                    throw e;
+                await this.backoff(attempt, e instanceof APIError ? e : undefined);
+            }
+        }
+        throw lastErr;
+    }
+    async once(method, path, body, opts) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            const headers = {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                ...(opts.headers ?? {}),
+            };
+            if (opts.idempotencyKey) {
+                headers["Idempotency-Key"] = opts.idempotencyKey;
+            }
+            res = await fetch(this.baseUrl + path, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            throw new SistemoError(`connection error: ${e.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            let detail = "request failed";
+            let code;
+            try {
+                const parsed = JSON.parse(text);
+                detail = parsed.detail ?? detail;
+                code = parsed.code;
+            }
+            catch {
+                /* non-JSON error body */
+            }
+            throw apiError(res.status, detail, code);
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+    shouldRetryHttp(method, status, idempotencyKey) {
+        if (!RETRY_STATUSES.has(status))
+            return false;
+        if (method === "GET" || method === "HEAD" || method === "OPTIONS" || method === "DELETE") {
+            return true;
+        }
+        return Boolean(idempotencyKey);
+    }
+    async backoff(attempt, err) {
+        const base = Math.min(this.retryMaxBackoffMs, this.retryBackoffMs * 2 ** attempt);
+        let delay = base * (0.5 + Math.random());
+        if (err?.status === 429)
+            delay = Math.max(delay, base);
+        await sleep(delay);
+    }
+    // --- volumes (incl. detachable root volumes) ---------------------------
+    /** List the account's volumes (root and data). */
+    async listVolumes() {
+        const out = await this.request("GET", "/v1/volumes");
+        return { volumes: out.volumes ?? [] };
+    }
+    /** Create a standalone data volume. */
+    createVolume(name, sizeGb) {
+        return this.request("POST", "/v1/volumes", { name, size_gb: sizeGb }, { idempotencyKey: newIdempotencyKey() });
+    }
+    /** Attach a volume (root or data) to a STOPPED machine. */
+    attachVolume(machineId, volumeId) {
+        return this.request("POST", `/v1/machines/${machineId}/volume/attach`, { volume_id: volumeId }, { idempotencyKey: newIdempotencyKey() });
+    }
+    /**
+     * Detach a volume from a STOPPED machine. A detached root volume's disk is
+     * preserved and can be re-attached or booted onto a new sandbox.
+     */
+    detachVolume(machineId, volumeId) {
+        return this.request("POST", `/v1/machines/${machineId}/volume/detach`, { volume_id: volumeId }, { idempotencyKey: newIdempotencyKey() });
+    }
+    /** Delete a detached volume. */
+    deleteVolume(volumeId) {
+        return this.request("DELETE", `/v1/volumes/${volumeId}`);
+    }
+}
+/** An isolated microVM you can run code in. Create with {@link Sandbox.create}. */
+export class Sandbox {
+    id;
+    state;
+    client;
+    constructor(client, id, state) {
+        this.client = client;
+        this.id = id;
+        this.state = state;
+    }
+    /** Provision a new microVM (resolves once it has booted). */
+    static async create(opts = {}) {
+        const client = opts.client ?? new Client(opts);
+        const body = {
+            name: opts.name ?? "",
+            vcpus: opts.vcpus ?? 1,
+            memory_mb: opts.memoryMb ?? 1024,
+            rootfs_size_gb: opts.rootfsSizeGb ?? 10,
+            stack: opts.stack ?? "base",
+            metadata: opts.metadata ?? {},
+        };
+        if (opts.rootVolumeId)
+            body.root_volume_id = opts.rootVolumeId;
+        const key = opts.idempotencyKey ?? newIdempotencyKey();
+        const machine = await client.request("POST", "/v1/machines", body, { idempotencyKey: key });
+        if (!machine?.id) {
+            throw new APIError(502, "create machine response missing id — refusing to continue", "invalid_create_response");
+        }
+        return new Sandbox(client, machine.id, machine.state ?? "");
+    }
+    /** Run a shell command/script inside the sandbox. */
+    async run(script, timeoutSec = 30) {
+        // No Idempotency-Key: HTTP errors are not retried (would re-run the script).
+        // Connection failures still use the client's connection-retry path only when
+        // they throw SistemoError before a response — see Client.request.
+        const out = await this.client.request("POST", `/v1/machines/${this.id}/exec`, { script, timeout_sec: timeoutSec });
+        return {
+            exitCode: out.exit_code ?? -1,
+            stdout: out.stdout ?? "",
+            stderr: out.stderr ?? "",
+        };
+    }
+    /** Destroy the sandbox (and its disk unless `preserveStorage`). */
+    async close(preserveStorage = false) {
+        const q = preserveStorage ? "?preserve_storage=true" : "";
+        await this.client.request("DELETE", `/v1/machines/${this.id}${q}`);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sistemo/sdk",
+  "version": "0.1.0",
+  "description": "Run AI agents and untrusted code in real isolated microVMs.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/sdk.test.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "sandbox",
+    "firecracker",
+    "microvm",
+    "ai-agents",
+    "code-execution"
+  ],
+  "homepage": "https://sistemo.io",
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sistemo0/sistemo-sdk.git",
+    "directory": "js"
+  },
+  "bugs": {
+    "url": "https://github.com/sistemo0/sistemo-sdk/issues"
+  }
+}