@aerol-ai/aerolvm-sdk 0.1.1

package/dist/MicroVM.d.ts

@@ -0,0 +1,36 @@
+import { Sandbox } from "./Sandbox.js";
+import type { CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+type FetchLike = typeof fetch;
+export interface MicroVMConfig {
+    patToken?: string;
+    apiUrl?: string;
+    fetch?: FetchLike;
+}
+export declare class MicroVM {
+    readonly apiUrl: string;
+    readonly patToken: string;
+    private readonly client;
+    constructor(config?: MicroVMConfig);
+    create(options: CreateOptions): Promise<Sandbox>;
+    list(): Promise<Sandbox[]>;
+    get(id: string): Promise<Sandbox>;
+    start(id: string): Promise<Sandbox>;
+    stop(id: string): Promise<Sandbox>;
+    destroy(id: string): Promise<void>;
+    resize(id: string, options: ResizeOptions): Promise<Sandbox>;
+    updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;
+    health(): Promise<HealthStatus>;
+    mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
+    execStream(sandboxID: string, options: ExecStreamOptions): ExecStreamHandle;
+    createSession(sandboxID: string, options: CreateSessionOptions): Promise<Session>;
+    listSessions(sandboxID: string): Promise<Session[]>;
+    getSession(sandboxID: string, sessionID: string): Promise<Session>;
+    deleteSession(sandboxID: string, sessionID: string): Promise<void>;
+    signalSession(sandboxID: string, sessionID: string, signal: string): Promise<void>;
+    resizeSession(sandboxID: string, sessionID: string, cols: number, rows: number): Promise<void>;
+    sessionLog(sandboxID: string, sessionID: string): Promise<Uint8Array>;
+    sessionRecording(sandboxID: string, sessionID: string): Promise<Uint8Array>;
+    attachSession(sandboxID: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
+    private wrap;
+}
+export {};

package/dist/MicroVM.js

@@ -0,0 +1,103 @@
+import { APIClient } from "./internal/client.js";
+import { Sandbox } from "./Sandbox.js";
+const defaultAPIURL = "http://127.0.0.1:8080";
+const authRequiredErrorMessage = "PAT token is required. Set patToken or SB_PAT_TOKEN.";
+export class MicroVM {
+    apiUrl;
+    patToken;
+    client;
+    constructor(config = {}) {
+        const patToken = config.patToken ?? readEnv("SB_PAT_TOKEN") ?? "";
+        const apiUrl = normalizeURL(config.apiUrl ?? readEnv("SB_API_URL") ?? defaultAPIURL);
+        if (patToken === "") {
+            throw new Error(authRequiredErrorMessage);
+        }
+        this.apiUrl = apiUrl;
+        this.patToken = patToken;
+        this.client = new APIClient({
+            baseURL: apiUrl,
+            patToken,
+            fetch: config.fetch,
+        });
+    }
+    async create(options) {
+        const sandbox = await this.client.create(options);
+        return this.wrap(sandbox.toJSON());
+    }
+    async list() {
+        const sandboxes = await this.client.list();
+        return sandboxes.map((sandbox) => this.wrap(sandbox.toJSON()));
+    }
+    async get(id) {
+        const sandbox = await this.client.get(id);
+        return this.wrap(sandbox.toJSON());
+    }
+    async start(id) {
+        const sandbox = await this.client.start(id);
+        return this.wrap(sandbox.toJSON());
+    }
+    async stop(id) {
+        const sandbox = await this.client.stop(id);
+        return this.wrap(sandbox.toJSON());
+    }
+    async destroy(id) {
+        await this.client.destroy(id);
+    }
+    async resize(id, options) {
+        const sandbox = await this.client.resize(id, options);
+        return this.wrap(sandbox.toJSON());
+    }
+    async updateLifecycle(id, lifecycle) {
+        const sandbox = await this.client.updateLifecycle(id, lifecycle);
+        return this.wrap(sandbox.toJSON());
+    }
+    async health() {
+        return this.client.health();
+    }
+    async mounts(sandboxID) {
+        return this.client.mounts(sandboxID);
+    }
+    execStream(sandboxID, options) {
+        return this.client.execStream(sandboxID, options);
+    }
+    async createSession(sandboxID, options) {
+        return this.client.createSession(sandboxID, options);
+    }
+    async listSessions(sandboxID) {
+        return this.client.listSessions(sandboxID);
+    }
+    async getSession(sandboxID, sessionID) {
+        return this.client.getSession(sandboxID, sessionID);
+    }
+    async deleteSession(sandboxID, sessionID) {
+        await this.client.deleteSession(sandboxID, sessionID);
+    }
+    async signalSession(sandboxID, sessionID, signal) {
+        await this.client.signalSession(sandboxID, sessionID, signal);
+    }
+    async resizeSession(sandboxID, sessionID, cols, rows) {
+        await this.client.resizeSession(sandboxID, sessionID, cols, rows);
+    }
+    async sessionLog(sandboxID, sessionID) {
+        return this.client.sessionLog(sandboxID, sessionID);
+    }
+    async sessionRecording(sandboxID, sessionID) {
+        return this.client.sessionRecording(sandboxID, sessionID);
+    }
+    attachSession(sandboxID, sessionID, options = {}) {
+        return this.client.attachSession(sandboxID, sessionID, options);
+    }
+    wrap(sandbox) {
+        return new Sandbox(this.client, sandbox);
+    }
+}
+function normalizeURL(value) {
+    return value.replace(/\/+$/, "");
+}
+function readEnv(name) {
+    if (typeof process === "undefined" || !process.env) {
+        return undefined;
+    }
+    const value = process.env[name];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}

package/dist/Sandbox.d.ts

@@ -0,0 +1,5 @@
+import { APIClient, SandboxResource } from "./internal/client.js";
+import type { Sandbox as SandboxData } from "./types.js";
+export declare class Sandbox extends SandboxResource {
+    constructor(client: APIClient, sandbox: SandboxData);
+}

package/dist/Sandbox.js

@@ -0,0 +1,6 @@
+import { SandboxResource } from "./internal/client.js";
+export class Sandbox extends SandboxResource {
+    constructor(client, sandbox) {
+        super(client, sandbox);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MicroVM } from "./MicroVM.js";
+export { Sandbox } from "./Sandbox.js";
+export type { MicroVMConfig } from "./MicroVM.js";
+export type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MicroVM } from "./MicroVM.js";
+export { Sandbox } from "./Sandbox.js";

package/dist/internal/client.d.ts

@@ -0,0 +1,93 @@
+import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Sandbox, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+type FetchLike = typeof fetch;
+export interface APIClientConfig {
+    baseURL: string;
+    patToken?: string;
+    fetch?: FetchLike;
+}
+export declare class APIClient {
+    readonly baseURL: string;
+    private readonly patToken;
+    private readonly fetchFn;
+    constructor(config: APIClientConfig);
+    create(options: CreateOptions): Promise<SandboxResource>;
+    list(): Promise<SandboxResource[]>;
+    get(id: string): Promise<SandboxResource>;
+    start(id: string): Promise<SandboxResource>;
+    stop(id: string): Promise<SandboxResource>;
+    destroy(id: string): Promise<void>;
+    resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
+    updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;
+    exec(id: string, request: ExecRequest): Promise<ExecResult>;
+    execStream(id: string, options: ExecStreamOptions): ExecStreamHandle;
+    createSession(id: string, options: CreateSessionOptions): Promise<Session>;
+    listSessions(id: string): Promise<Session[]>;
+    getSession(id: string, sessionID: string): Promise<Session>;
+    deleteSession(id: string, sessionID: string): Promise<void>;
+    signalSession(id: string, sessionID: string, signal: string): Promise<void>;
+    resizeSession(id: string, sessionID: string, cols: number, rows: number): Promise<void>;
+    sessionLog(id: string, sessionID: string): Promise<Uint8Array>;
+    sessionRecording(id: string, sessionID: string): Promise<Uint8Array>;
+    attachSession(id: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
+    uploadFile(id: string, targetPath: string, data: BinaryLike): Promise<void>;
+    downloadFile(id: string, targetPath: string): Promise<Uint8Array>;
+    exposePort(id: string, port: number): Promise<string>;
+    unexposePort(id: string, port: number): Promise<void>;
+    health(): Promise<HealthStatus>;
+    mounts(id: string): Promise<MountSpecRedacted[]>;
+    private wrap;
+    private doJSON;
+    private doBytes;
+    private request;
+}
+export declare class SandboxResource implements Sandbox {
+    id: string;
+    image: string;
+    status: Sandbox["status"];
+    publicURL: string;
+    containerID?: string;
+    containerIP?: string;
+    cpu: number;
+    memoryMB: number;
+    diskGB: number;
+    osUser: string;
+    env?: Record<string, string>;
+    networkBlockAll: boolean;
+    toolboxEnabled: boolean;
+    sshPublicKey?: string;
+    sshPrivateKey?: string;
+    exposedPorts?: ExposedPort[];
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string;
+    lastError?: string;
+    containerCommand?: string[];
+    lifecycle: Lifecycle;
+    runtime: Sandbox["runtime"];
+    protected readonly client: APIClient;
+    constructor(client: APIClient, sandbox: Sandbox);
+    refresh(): Promise<this>;
+    exec(command: string | ExecRequest): Promise<ExecResult>;
+    execStream(options: ExecStreamOptions): ExecStreamHandle;
+    createSession(options: CreateSessionOptions): Promise<Session>;
+    listSessions(): Promise<Session[]>;
+    getSession(sessionID: string): Promise<Session>;
+    deleteSession(sessionID: string): Promise<void>;
+    signalSession(sessionID: string, signal: string): Promise<void>;
+    resizeSession(sessionID: string, cols: number, rows: number): Promise<void>;
+    sessionLog(sessionID: string): Promise<Uint8Array>;
+    sessionRecording(sessionID: string): Promise<Uint8Array>;
+    attachSession(sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
+    uploadFile(targetPath: string, data: BinaryLike): Promise<void>;
+    downloadFile(targetPath: string): Promise<Uint8Array>;
+    exposePort(port: number): Promise<string>;
+    unexposePort(port: number): Promise<void>;
+    start(): Promise<this>;
+    stop(): Promise<this>;
+    destroy(): Promise<void>;
+    resize(options: ResizeOptions): Promise<this>;
+    updateLifecycle(lifecycle: Lifecycle): Promise<this>;
+    toJSON(): Sandbox;
+    private apply;
+}
+export {};

package/dist/internal/client.js

@@ -0,0 +1,629 @@
+import { basename } from "node:path";
+export class APIClient {
+    baseURL;
+    patToken;
+    fetchFn;
+    constructor(config) {
+        this.baseURL = config.baseURL.replace(/\/+$/, "");
+        this.patToken = config.patToken ?? "";
+        this.fetchFn = config.fetch ?? fetch;
+    }
+    async create(options) {
+        const response = await this.doJSON("POST", "/v1/sandboxes", toApiCreateOptions(options));
+        return new SandboxResource(this, fromApiCreateSandboxResponse(response));
+    }
+    async list() {
+        const response = await this.doJSON("GET", "/v1/sandboxes");
+        return response.map((item) => this.wrap(item));
+    }
+    async get(id) {
+        const response = await this.doJSON("GET", `/v1/sandboxes/${id}`);
+        return this.wrap(response);
+    }
+    async start(id) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/start`);
+        return this.wrap(response);
+    }
+    async stop(id) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/stop`);
+        return this.wrap(response);
+    }
+    async destroy(id) {
+        await this.doJSON("DELETE", `/v1/sandboxes/${id}`);
+    }
+    async resize(id, options) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/resize`, toApiResizeOptions(options));
+        return this.wrap(response);
+    }
+    async updateLifecycle(id, lifecycle) {
+        const response = await this.doJSON("PUT", `/v1/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
+        return this.wrap(response);
+    }
+    async exec(id, request) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
+        return fromApiExecResult(response);
+    }
+    execStream(id, options) {
+        return openExecStream(this.baseURL, this.patToken, id, options);
+    }
+    async createSession(id, options) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
+        return fromApiSession(response);
+    }
+    async listSessions(id) {
+        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions`);
+        return response.sessions.map(fromApiSession);
+    }
+    async getSession(id, sessionID) {
+        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+        return fromApiSession(response);
+    }
+    async deleteSession(id, sessionID) {
+        await this.doJSON("DELETE", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+    }
+    async signalSession(id, sessionID, signal) {
+        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/signal`, { signal });
+    }
+    async resizeSession(id, sessionID, cols, rows) {
+        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/resize`, { cols, rows });
+    }
+    async sessionLog(id, sessionID) {
+        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/log`);
+    }
+    async sessionRecording(id, sessionID) {
+        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/recording`);
+    }
+    attachSession(id, sessionID, options = {}) {
+        return openSessionAttach(this.baseURL, this.patToken, id, sessionID, options);
+    }
+    async uploadFile(id, targetPath, data) {
+        const form = new FormData();
+        form.set("path", targetPath);
+        form.set("file", toBlob(data), basename(targetPath));
+        const response = await this.request("POST", `/v1/sandboxes/${id}/toolbox/files/upload`, { body: form });
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+    }
+    async downloadFile(id, targetPath) {
+        const response = await this.request("GET", `/v1/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async exposePort(id, port) {
+        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/ports/${port}`);
+        return response.public_url;
+    }
+    async unexposePort(id, port) {
+        await this.doJSON("DELETE", `/v1/sandboxes/${id}/ports/${port}`);
+    }
+    async health() {
+        const response = await this.doJSON("GET", "/health");
+        return fromApiHealthStatus(response);
+    }
+    async mounts(id) {
+        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/mounts`);
+        return response.mounts.map(fromApiMountSpecRedacted);
+    }
+    wrap(sandbox) {
+        return new SandboxResource(this, fromApiSandbox(sandbox));
+    }
+    async doJSON(method, path, body) {
+        const init = {};
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+            init.headers = {
+                "Content-Type": "application/json",
+            };
+        }
+        const response = await this.request(method, path, init);
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+    async doBytes(path) {
+        const response = await this.request("GET", path);
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    request(method, path, init = {}) {
+        const headers = new Headers(init.headers);
+        if (this.patToken !== "") {
+            headers.set("Authorization", `Bearer ${this.patToken}`);
+        }
+        return this.fetchFn(`${this.baseURL}${path}`, {
+            ...init,
+            method,
+            headers,
+        });
+    }
+}
+export class SandboxResource {
+    client;
+    constructor(client, sandbox) {
+        this.client = client;
+        this.apply(sandbox);
+    }
+    async refresh() {
+        const updated = await this.client.get(this.id);
+        this.apply(updated.toJSON());
+        return this;
+    }
+    async exec(command) {
+        return this.client.exec(this.id, typeof command === "string" ? { command } : command);
+    }
+    execStream(options) {
+        return this.client.execStream(this.id, options);
+    }
+    async createSession(options) {
+        return this.client.createSession(this.id, options);
+    }
+    async listSessions() {
+        return this.client.listSessions(this.id);
+    }
+    async getSession(sessionID) {
+        return this.client.getSession(this.id, sessionID);
+    }
+    async deleteSession(sessionID) {
+        await this.client.deleteSession(this.id, sessionID);
+    }
+    async signalSession(sessionID, signal) {
+        await this.client.signalSession(this.id, sessionID, signal);
+    }
+    async resizeSession(sessionID, cols, rows) {
+        await this.client.resizeSession(this.id, sessionID, cols, rows);
+    }
+    async sessionLog(sessionID) {
+        return this.client.sessionLog(this.id, sessionID);
+    }
+    async sessionRecording(sessionID) {
+        return this.client.sessionRecording(this.id, sessionID);
+    }
+    attachSession(sessionID, options = {}) {
+        return this.client.attachSession(this.id, sessionID, options);
+    }
+    async uploadFile(targetPath, data) {
+        await this.client.uploadFile(this.id, targetPath, data);
+    }
+    async downloadFile(targetPath) {
+        return this.client.downloadFile(this.id, targetPath);
+    }
+    async exposePort(port) {
+        return this.client.exposePort(this.id, port);
+    }
+    async unexposePort(port) {
+        await this.client.unexposePort(this.id, port);
+    }
+    async start() {
+        const updated = await this.client.start(this.id);
+        this.apply(updated.toJSON());
+        return this;
+    }
+    async stop() {
+        const updated = await this.client.stop(this.id);
+        this.apply(updated.toJSON());
+        return this;
+    }
+    async destroy() {
+        await this.client.destroy(this.id);
+    }
+    async resize(options) {
+        const updated = await this.client.resize(this.id, options);
+        this.apply(updated.toJSON());
+        return this;
+    }
+    async updateLifecycle(lifecycle) {
+        const updated = await this.client.updateLifecycle(this.id, lifecycle);
+        this.apply(updated.toJSON());
+        return this;
+    }
+    toJSON() {
+        return cloneSandbox(this);
+    }
+    apply(sandbox) {
+        Object.assign(this, cloneSandbox(sandbox));
+    }
+}
+function toApiCreateOptions(options) {
+    return {
+        image: options.image,
+        cpu: options.cpu,
+        memory_mb: options.memoryMB,
+        disk_gb: options.diskGB,
+        env: options.env,
+        os_user: options.osUser,
+        network_block_all: options.networkBlockAll,
+        registry: options.registry,
+        container_command: options.containerCommand,
+        mounts: options.mounts?.map(toApiMountSpec),
+        lifecycle: options.lifecycle ? toApiLifecycle(options.lifecycle) : undefined,
+        runtime: options.runtime,
+    };
+}
+function toApiResizeOptions(options) {
+    return {
+        cpu: options.cpu,
+        memory_mb: options.memoryMB,
+        disk_gb: options.diskGB,
+    };
+}
+function toApiExecRequest(request) {
+    return {
+        command: request.command,
+        workdir: request.workDir,
+        env: request.env,
+        timeout_seconds: request.timeoutSeconds,
+    };
+}
+function toApiCreateSessionOptions(options) {
+    return {
+        name: options.name,
+        argv: options.argv,
+        command: options.command,
+        workdir: options.workDir,
+        env: options.env,
+        pty: options.pty,
+        cols: options.cols,
+        rows: options.rows,
+    };
+}
+function toApiLifecycle(lifecycle) {
+    return {
+        stop_if_idle_for: lifecycle.stopIfIdleFor,
+        destroy_if_idle_for: lifecycle.destroyIfIdleFor,
+        stop_at_age: lifecycle.stopAtAge,
+        destroy_at_age: lifecycle.destroyAtAge,
+    };
+}
+function fromApiSandbox(sandbox) {
+    return {
+        id: sandbox.id,
+        image: sandbox.image,
+        status: sandbox.status,
+        publicURL: sandbox.public_url,
+        containerID: sandbox.container_id,
+        containerIP: sandbox.container_ip,
+        cpu: sandbox.cpu,
+        memoryMB: sandbox.memory_mb,
+        diskGB: sandbox.disk_gb,
+        osUser: sandbox.os_user,
+        env: sandbox.env,
+        networkBlockAll: sandbox.network_block_all,
+        toolboxEnabled: sandbox.toolbox_enabled,
+        sshPublicKey: sandbox.ssh_public_key,
+        exposedPorts: sandbox.exposed_ports?.map(fromApiExposedPort),
+        createdAt: sandbox.created_at,
+        updatedAt: sandbox.updated_at,
+        lastActiveAt: sandbox.last_active_at,
+        lastError: sandbox.last_error,
+        containerCommand: sandbox.container_command,
+        lifecycle: fromApiLifecycle(sandbox.lifecycle),
+        runtime: normalizeRuntime(sandbox.runtime),
+    };
+}
+// normalizeRuntime narrows the wire-level string to the union we expose, while
+// tolerating older sandboxd versions that don't send the field at all (treat
+// as "" — i.e. host default at start time).
+function normalizeRuntime(value) {
+    if (value === "docker" || value === "gvisor" || value === "kata") {
+        return value;
+    }
+    return "";
+}
+function fromApiCreateSandboxResponse(response) {
+    return {
+        ...fromApiSandbox(response),
+        sshPrivateKey: response.ssh_private_key,
+    };
+}
+function fromApiSession(session) {
+    return {
+        id: session.id,
+        name: session.name,
+        argv: session.argv,
+        workDir: session.workdir,
+        pty: session.pty,
+        status: session.status,
+        exitCode: session.exit_code,
+        exitSignal: session.exit_signal,
+        createdAt: session.created_at,
+        startedAt: session.started_at,
+        exitedAt: session.exited_at,
+        recording: session.recording,
+        bytes: session.bytes,
+        attached: session.attached,
+    };
+}
+function fromApiExposedPort(port) {
+    return {
+        sandboxID: port.sandbox_id,
+        port: port.port,
+        publicURL: port.public_url,
+        createdAt: port.created_at,
+    };
+}
+function fromApiExecResult(result) {
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exit_code,
+        durationMS: result.duration_ms,
+    };
+}
+function fromApiHealthStatus(status) {
+    return {
+        status: status.status,
+        sandboxes: status.sandboxes,
+        docker: status.docker,
+        caddy: status.caddy,
+        sshGateway: status.ssh_gateway ?? "",
+        version: status.version,
+    };
+}
+function toApiMountSpec(mount) {
+    return {
+        type: mount.type,
+        target: mount.target,
+        source: mount.source,
+        options: mount.options,
+        credentials: mount.credentials,
+        read_only: mount.readOnly,
+    };
+}
+function fromApiMountSpecRedacted(mount) {
+    return {
+        type: mount.type,
+        target: mount.target,
+        source: mount.source,
+        options: mount.options,
+        readOnly: mount.read_only ?? false,
+        hasCredentials: mount.has_credentials,
+    };
+}
+function fromApiLifecycle(lifecycle) {
+    const result = {};
+    if (lifecycle?.stop_if_idle_for !== undefined) {
+        result.stopIfIdleFor = lifecycle.stop_if_idle_for;
+    }
+    if (lifecycle?.destroy_if_idle_for !== undefined) {
+        result.destroyIfIdleFor = lifecycle.destroy_if_idle_for;
+    }
+    if (lifecycle?.stop_at_age !== undefined) {
+        result.stopAtAge = lifecycle.stop_at_age;
+    }
+    if (lifecycle?.destroy_at_age !== undefined) {
+        result.destroyAtAge = lifecycle.destroy_at_age;
+    }
+    return result;
+}
+function cloneSandbox(sandbox) {
+    return {
+        ...sandbox,
+        env: sandbox.env ? { ...sandbox.env } : undefined,
+        exposedPorts: sandbox.exposedPorts?.map((port) => ({ ...port })),
+        containerCommand: sandbox.containerCommand ? [...sandbox.containerCommand] : undefined,
+        lifecycle: { ...sandbox.lifecycle },
+    };
+}
+function toBlob(data) {
+    if (data instanceof Blob) {
+        return data;
+    }
+    if (typeof data === "string") {
+        return new Blob([data]);
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Blob([new Uint8Array(data)]);
+    }
+    return new Blob([Uint8Array.from(data)]);
+}
+async function decodeError(response) {
+    try {
+        const payload = (await response.json());
+        if (typeof payload.error === "string" && payload.error !== "") {
+            return new Error(payload.error);
+        }
+    }
+    catch {
+        // Fall through to status-based error.
+    }
+    return new Error(`request failed with status ${response.status}`);
+}
+const STREAM_PREFIX_STDOUT = 0x01;
+const STREAM_PREFIX_STDERR = 0x02;
+function openExecStream(baseURL, patToken, sandboxID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
+    const WS = globalThis.WebSocket;
+    if (!WS) {
+        throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");
+    }
+    // Browsers cannot attach Authorization headers to WebSocket handshakes,
+    // so sandboxd accepts the PAT via `Sec-WebSocket-Protocol` as
+    // `sandbox.bearer, <token>`.
+    const ws = new WS(wsURL, ["sandbox.bearer", patToken]);
+    ws.binaryType = "arraybuffer";
+    let exitResolve;
+    let exitReject;
+    const done = new Promise((resolve, reject) => {
+        exitResolve = resolve;
+        exitReject = reject;
+    });
+    let resolved = false;
+    const finishWith = (info) => {
+        if (resolved)
+            return;
+        resolved = true;
+        exitResolve?.(info);
+    };
+    const failWith = (msg) => {
+        if (resolved)
+            return;
+        resolved = true;
+        exitReject?.(new Error(msg));
+    };
+    ws.addEventListener("open", () => {
+        ws.send(JSON.stringify({
+            command: options.command,
+            workdir: options.workdir,
+            env: options.env,
+            tty: options.tty ?? false,
+            cols: options.cols ?? 0,
+            rows: options.rows ?? 0,
+        }));
+    });
+    ws.addEventListener("message", (event) => {
+        if (typeof event.data === "string") {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.type === "exit") {
+                    finishWith({ code: msg.code ?? 0, signal: msg.signal });
+                    ws.close();
+                }
+                else if (msg.type === "error") {
+                    options.onError?.(msg.message ?? "stream error");
+                    failWith(msg.message ?? "stream error");
+                    ws.close();
+                }
+            }
+            catch {
+                // ignore
+            }
+            return;
+        }
+        const buf = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : new Uint8Array(event.data.buffer);
+        if (buf.length === 0)
+            return;
+        const stream = buf[0];
+        const payload = buf.subarray(1);
+        if (stream === STREAM_PREFIX_STDOUT) {
+            options.onStdout?.(payload);
+        }
+        else if (stream === STREAM_PREFIX_STDERR) {
+            options.onStderr?.(payload);
+        }
+    });
+    ws.addEventListener("close", () => {
+        finishWith({ code: 0 });
+    });
+    ws.addEventListener("error", () => {
+        failWith("websocket error");
+    });
+    const sendBinary = (data) => {
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        ws.send(bytes);
+    };
+    return {
+        write: sendBinary,
+        resize(cols, rows) {
+            ws.send(JSON.stringify({ type: "resize", cols, rows }));
+        },
+        signal(name) {
+            ws.send(JSON.stringify({ type: "signal", signal: name }));
+        },
+        close() {
+            ws.send(JSON.stringify({ type: "close" }));
+            ws.close();
+        },
+        done,
+    };
+}
+function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/sessions/${encodeURIComponent(sessionID)}/attach`;
+    const WS = globalThis.WebSocket;
+    if (!WS) {
+        throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");
+    }
+    const ws = new WS(wsURL, ["sandbox.bearer", patToken]);
+    ws.binaryType = "arraybuffer";
+    let exitResolve;
+    let exitReject;
+    const done = new Promise((resolve, reject) => {
+        exitResolve = resolve;
+        exitReject = reject;
+    });
+    let settled = false;
+    const finishWith = (info) => {
+        if (settled)
+            return;
+        settled = true;
+        options.onExit?.(info);
+        exitResolve?.(info);
+    };
+    const failWith = (msg) => {
+        if (settled)
+            return;
+        settled = true;
+        exitReject?.(new Error(msg));
+    };
+    ws.addEventListener("open", () => {
+        if ((options.cols ?? 0) > 0 && (options.rows ?? 0) > 0) {
+            ws.send(JSON.stringify({ type: "resize", cols: options.cols, rows: options.rows }));
+        }
+    });
+    ws.addEventListener("message", (event) => {
+        if (typeof event.data === "string") {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.type === "exit") {
+                    finishWith({ code: msg.code ?? 0, signal: msg.signal });
+                    ws.close();
+                }
+                else if (msg.type === "error") {
+                    options.onError?.(msg.message ?? "session error");
+                    failWith(msg.message ?? "session error");
+                    ws.close();
+                }
+            }
+            catch {
+                // ignore malformed control frames
+            }
+            return;
+        }
+        const buf = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : new Uint8Array(event.data.buffer);
+        if (buf.length === 0) {
+            return;
+        }
+        const stream = buf[0];
+        const payload = buf.subarray(1);
+        if (stream === STREAM_PREFIX_STDOUT) {
+            options.onStdout?.(payload);
+        }
+        else if (stream === STREAM_PREFIX_STDERR) {
+            options.onStderr?.(payload);
+        }
+    });
+    ws.addEventListener("close", () => {
+        if (!settled) {
+            failWith("session stream closed before exit");
+        }
+    });
+    ws.addEventListener("error", () => {
+        failWith("websocket error");
+    });
+    const sendBinary = (data) => {
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        ws.send(bytes);
+    };
+    return {
+        write: sendBinary,
+        resize(cols, rows) {
+            ws.send(JSON.stringify({ type: "resize", cols, rows }));
+        },
+        signal(name) {
+            ws.send(JSON.stringify({ type: "signal", signal: name }));
+        },
+        close() {
+            ws.send(JSON.stringify({ type: "close" }));
+            ws.close();
+        },
+        done,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+export type SandboxStatus = "creating" | "started" | "stopped" | "destroyed" | "error";
+export interface RegistryAuth {
+    server: string;
+    username: string;
+    password: string;
+}
+export type MountType = "s3" | "nfs" | "sshfs" | "rclone";
+export interface MountSpec {
+    type: MountType;
+    target: string;
+    source: string;
+    options?: Record<string, string>;
+    credentials?: Record<string, string>;
+    readOnly?: boolean;
+}
+export interface MountSpecRedacted {
+    type: MountType;
+    target: string;
+    source: string;
+    options?: Record<string, string>;
+    readOnly: boolean;
+    hasCredentials: boolean;
+}
+export interface Lifecycle {
+    /** Duration in integer nanoseconds. */
+    stopIfIdleFor?: number;
+    /** Duration in integer nanoseconds. */
+    destroyIfIdleFor?: number;
+    /** Duration in integer nanoseconds. */
+    stopAtAge?: number;
+    /** Duration in integer nanoseconds. */
+    destroyAtAge?: number;
+}
+export type UpdateLifecycleOptions = Lifecycle;
+export interface CreateOptions {
+    image: string;
+    /** Number of CPU cores to allocate. Fractional values are supported (e.g. 0.5 = half a core). */
+    cpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
+    env?: Record<string, string>;
+    osUser?: string;
+    networkBlockAll?: boolean;
+    registry?: RegistryAuth;
+    containerCommand?: string[];
+    mounts?: MountSpec[];
+    lifecycle?: Lifecycle;
+    /**
+     * Container runtime to use for this sandbox. Omit to inherit the host
+     * default (`SB_CONTAINER_RUNTIME`). Use `"gvisor"` for runsc-backed
+     * isolation when running untrusted workloads — note that gVisor rejects
+     * privileged containers and ignores per-sandbox disk quotas. `"kata"` is
+     * reserved for future Kata Containers support and is rejected by the API
+     * today.
+     */
+    runtime?: "docker" | "gvisor" | "kata";
+}
+export interface ResizeOptions {
+    /** Number of CPU cores. Fractional values supported (e.g. 0.5). */
+    cpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
+}
+export interface CreateSessionOptions {
+    name?: string;
+    argv?: string[];
+    command?: string;
+    workDir?: string;
+    env?: Record<string, string>;
+    pty?: boolean;
+    cols?: number;
+    rows?: number;
+}
+export type SessionStatus = "running" | "exited" | "killed" | "failed";
+export interface Session {
+    id: string;
+    name: string;
+    argv: string[];
+    workDir?: string;
+    pty: boolean;
+    status: SessionStatus;
+    exitCode: number;
+    exitSignal?: string;
+    createdAt: string;
+    startedAt: string;
+    exitedAt?: string;
+    recording: boolean;
+    bytes: number;
+    attached: number;
+}
+export interface ExposedPort {
+    sandboxID: string;
+    port: number;
+    publicURL: string;
+    createdAt: string;
+}
+export interface Sandbox {
+    id: string;
+    image: string;
+    status: SandboxStatus;
+    publicURL: string;
+    containerID?: string;
+    containerIP?: string;
+    cpu: number;
+    memoryMB: number;
+    diskGB: number;
+    osUser: string;
+    env?: Record<string, string>;
+    networkBlockAll: boolean;
+    toolboxEnabled: boolean;
+    sshPublicKey?: string;
+    sshPrivateKey?: string;
+    exposedPorts?: ExposedPort[];
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string;
+    lastError?: string;
+    containerCommand?: string[];
+    lifecycle: Lifecycle;
+    /**
+     * Container runtime this sandbox is running under. Empty string indicates
+     * a pre-migration row that resolves to the host default at start time.
+     */
+    runtime: "" | "docker" | "gvisor" | "kata";
+}
+export interface ExecRequest {
+    command: string;
+    workDir?: string;
+    env?: Record<string, string>;
+    timeoutSeconds?: number;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMS: number;
+}
+export interface ExecStreamOptions {
+    command: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    tty?: boolean;
+    cols?: number;
+    rows?: number;
+    onStdout?: (chunk: Uint8Array) => void;
+    onStderr?: (chunk: Uint8Array) => void;
+    onError?: (message: string) => void;
+}
+export interface ExecExitInfo {
+    code: number;
+    signal?: string;
+}
+export interface ExecStreamHandle {
+    /** Send raw stdin bytes (or a UTF-8 string) to the process. */
+    write(data: Uint8Array | string): void;
+    /** PTY mode only — tell the process its terminal size has changed. */
+    resize(cols: number, rows: number): void;
+    /** Send a signal (e.g. "INT", "TERM") to the process group. */
+    signal(name: string): void;
+    /** Close stdin and gracefully end the stream. The process keeps running until it exits on its own. */
+    close(): void;
+    /** Resolves when the process exits, with its final exit code/signal. */
+    done: Promise<ExecExitInfo>;
+}
+export interface SessionAttachOptions {
+    onStdout?: (chunk: Uint8Array) => void;
+    onStderr?: (chunk: Uint8Array) => void;
+    onExit?: (info: ExecExitInfo) => void;
+    onError?: (message: string) => void;
+    cols?: number;
+    rows?: number;
+}
+export interface SessionAttachHandle {
+    /** Send raw stdin bytes (or a UTF-8 string) to the attached session. */
+    write(data: Uint8Array | string): void;
+    /** PTY sessions only — tell the session its terminal size has changed. */
+    resize(cols: number, rows: number): void;
+    /** Send a signal (e.g. "INT", "TERM", "KILL") to the session process group. */
+    signal(name: string): void;
+    /** Detach from the live stream without killing the session. */
+    close(): void;
+    /** Resolves when the session exits, or rejects if the attach stream drops first. */
+    done: Promise<ExecExitInfo>;
+}
+export interface HealthStatus {
+    status: string;
+    sandboxes: number;
+    docker: string;
+    caddy: string;
+    sshGateway: string;
+    version: string;
+}
+export type BinaryLike = Uint8Array | ArrayBuffer | Blob | string;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@aerol-ai/aerolvm-sdk",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "example:create": "npm run build && node dist/examples/createSandbox.js",
+    "example:create:src": "npx tsx src/examples/createSandbox.ts",
+    "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.17",
+    "typescript": "^5.8.3",
+    "tsx": "^4.21.0"
+  }
+}