@run-cloud/sdk 0.5.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Newly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -48,10 +48,9 @@ await writeFile(
 await cloud.sandboxes.destroy(sandbox.id);
 ```
 
-Ask for more than the default with either a preset or explicit resources:
+Ask for the exact resources you need:
 
 ```ts
-await cloud.sandboxes.create({ size: "s-4" });
 await cloud.sandboxes.create({ cpu: 2, memory: 4096, disk: 40 });
 ```
 
@@ -70,18 +69,47 @@ Snapshot a sandbox and restore it later:
 
 ```ts
 const snap = await cloud.sandboxes.snapshot(sandbox.id, { label: "deps-installed" });
-const restored = await cloud.snapshots.restore(snap.id, { size: "s-1" });
+const restored = await cloud.snapshots.restore(snap.id);
 ```
 
-A restore with no `size` boots the control plane's `s-2` preset (2 vCPU / 2 GiB),
-not the smaller default `sandboxes.create()` applies — pass `size` explicitly.
-
 Sandbox fields are returned in both the API's `snake_case` and camelCase
 (`milli_cpu` and `milliCpu` are both present).
 
 The client reads `RUN_CLOUD_API_KEY` first, then `RUN_CLOUD_API_TOKEN`. Override
 the API origin with `RUN_CLOUD_API_URL` or by passing `new Client({ apiUrl })`.
 
+## Compatibility adapters
+
+Provider-shaped migration adapters ship in this same package:
+
+| Provider | Import |
+| --- | --- |
+| Modal | `@run-cloud/sdk/compat/modal` |
+| E2B | `@run-cloud/sdk/compat/e2b` |
+| Daytona | `@run-cloud/sdk/compat/daytona` |
+| Vercel Sandbox | `@run-cloud/sdk/compat/vercel` |
+| Blaxel | `@run-cloud/sdk/compat/blaxel` |
+| Fly Sprites | `@run-cloud/sdk/compat/sprites` |
+| Cloudflare Sandbox | `@run-cloud/sdk/compat/cloudflare` |
+| CodeSandbox | `@run-cloud/sdk/compat/codesandbox` |
+| Fly Machines | `@run-cloud/sdk/compat/fly` |
+
+```ts
+// import { Sandbox } from "@vercel/sandbox";
+import { Sandbox } from "@run-cloud/sdk/compat/vercel";
+
+const box = await Sandbox.create();
+const result = await box.runCommand("node", ["-e", "console.log('hello')"]);
+console.log(await result.stdout());
+await box.stop();
+```
+
+The adapters preserve core creation, lookup/listing, synchronous command
+execution, pause/resume where the provider exposes it, and destruction.
+Provider-specific features that do not have a public run.cloud equivalent throw
+`UnsupportedCompatibilityFeatureError` with a migration hint. In particular,
+public port capabilities and filesystem mutation are not silently emulated.
+
 `cloud.ios.screenshot(sessionId)` returns PNG bytes as a `Uint8Array`. Save the
 bytes directly with `node:fs/promises.writeFile`, attach them to test artifacts,
 or pass them to an image-processing library.

package/dist/compat/blaxel.d.ts

@@ -0,0 +1,49 @@
+import { type CompatibilityClientOptions, type NativeSandbox } from "./common.js";
+declare class Process {
+    private readonly native;
+    constructor(native: NativeSandbox);
+    exec(config: {
+        name?: string;
+        command: string;
+        workingDir?: string;
+        env?: Record<string, string>;
+        waitForCompletion?: boolean;
+    }): Promise<{
+        pid: number;
+        name: string;
+        status: string;
+        exitCode: number;
+        logs: string;
+    }>;
+}
+declare class FileSystem {
+    private readonly native;
+    constructor(native: NativeSandbox);
+    read(path: string): Promise<string>;
+    write(): never;
+    ls(): never;
+    mkdir(): never;
+    rm(): never;
+}
+export declare class SandboxInstance {
+    readonly native: NativeSandbox;
+    readonly process: Process;
+    readonly fs: FileSystem;
+    private constructor();
+    static create(options?: CompatibilityClientOptions & {
+        name?: string;
+        image?: string;
+        memory?: number;
+        cpu?: number;
+        region?: string;
+        ttl?: number | string;
+    }): Promise<SandboxInstance>;
+    static get(id: string, options?: CompatibilityClientOptions): Promise<SandboxInstance>;
+    static list(options?: CompatibilityClientOptions): Promise<SandboxInstance[]>;
+    get id(): string;
+    get previews(): {
+        createIfNotExists: () => never;
+    };
+    delete(): Promise<void>;
+}
+export {};

package/dist/compat/blaxel.js

@@ -0,0 +1,85 @@
+import { compatibilityClient, createNative, getNative, listNative, unsupported, } from "./common.js";
+class Process {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async exec(config) {
+        if (config.waitForCompletion === false)
+            unsupported("Blaxel", "background processes");
+        const result = await this.native.exec(config.command, {
+            cwd: config.workingDir,
+            env: config.env,
+        });
+        return {
+            pid: 0,
+            name: config.name ?? "",
+            status: result.exitCode === 0 ? "completed" : "failed",
+            exitCode: result.exitCode,
+            logs: result.stdout + result.stderr,
+        };
+    }
+}
+class FileSystem {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async read(path) {
+        return new TextDecoder().decode(await this.native.readFile(path));
+    }
+    write() {
+        return unsupported("Blaxel", "file writes", "use an image or a command that writes the content");
+    }
+    ls() {
+        return unsupported("Blaxel", "directory listing");
+    }
+    mkdir() {
+        return unsupported("Blaxel", "directory creation");
+    }
+    rm() {
+        return unsupported("Blaxel", "file removal");
+    }
+}
+export class SandboxInstance {
+    native;
+    process;
+    fs;
+    constructor(native) {
+        this.native = native;
+        this.process = new Process(native);
+        this.fs = new FileSystem(native);
+    }
+    static async create(options = {}) {
+        const client = compatibilityClient(options);
+        const ttl = typeof options.ttl === "number" ? options.ttl : undefined;
+        return new SandboxInstance(await createNative(client, {
+            name: options.name,
+            image: options.image,
+            memory: options.memory,
+            cpu: options.cpu,
+            region: options.region,
+            idlePauseSeconds: ttl,
+        }));
+    }
+    static async get(id, options = {}) {
+        const client = compatibilityClient(options);
+        return new SandboxInstance(await getNative(client, id));
+    }
+    static async list(options = {}) {
+        const client = compatibilityClient(options);
+        return (await listNative(client)).map((sandbox) => new SandboxInstance(sandbox));
+    }
+    get id() {
+        return this.native.id;
+    }
+    get previews() {
+        return {
+            createIfNotExists: () => unsupported("Blaxel", "previews", "run.cloud public port capabilities are not available in the SDK yet"),
+        };
+    }
+    async delete() {
+        await this.native.destroy();
+    }
+}
+//# sourceMappingURL=blaxel.js.map

package/dist/compat/blaxel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blaxel.js","sourceRoot":"","sources":["../../src/compat/blaxel.ts"],"names":[],"mappings":"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"}

package/dist/compat/cloudflare.d.ts

@@ -0,0 +1,32 @@
+import type { Client } from "../index.js";
+import { type CompatibilityClientOptions, type NativeSandbox } from "./common.js";
+export declare class Sandbox {
+    private readonly client;
+    readonly id: string;
+    private ensured?;
+    constructor(client: Client, id: string);
+    private ensure;
+    get native(): Promise<NativeSandbox>;
+    exec(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<{
+        success: boolean;
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        command: string;
+        duration: number;
+    }>;
+    readFile(path: string): Promise<{
+        content: string;
+    }>;
+    writeFile(): never;
+    mkdir(): never;
+    listFiles(): never;
+    deleteFile(): never;
+    renameFile(): never;
+    exposePort(): never;
+    destroy(): Promise<void>;
+}
+export declare function getSandbox(binding: Client | unknown, id: string, options?: CompatibilityClientOptions): Sandbox;

package/dist/compat/cloudflare.js

@@ -0,0 +1,66 @@
+import { bytesToText, compatibilityClient, createNative, listNative, unsupported, } from "./common.js";
+export class Sandbox {
+    client;
+    id;
+    ensured;
+    constructor(client, id) {
+        this.client = client;
+        this.id = id;
+    }
+    async ensure() {
+        if (!this.ensured) {
+            this.ensured = (async () => {
+                const existing = (await listNative(this.client)).find((sandbox) => sandbox.name === this.id);
+                return existing ?? (await createNative(this.client, { name: this.id }));
+            })();
+        }
+        return await this.ensured;
+    }
+    get native() {
+        return this.ensure();
+    }
+    async exec(command, options = {}) {
+        const startedAt = Date.now();
+        const result = await (await this.ensure()).exec(command, options);
+        return {
+            success: result.exitCode === 0,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            command,
+            duration: Date.now() - startedAt,
+        };
+    }
+    async readFile(path) {
+        return { content: bytesToText(await (await this.ensure()).readFile(path)) };
+    }
+    writeFile() {
+        return unsupported("Cloudflare Sandbox", "file writes", "use an image or command");
+    }
+    mkdir() {
+        return unsupported("Cloudflare Sandbox", "directory creation");
+    }
+    listFiles() {
+        return unsupported("Cloudflare Sandbox", "directory listing");
+    }
+    deleteFile() {
+        return unsupported("Cloudflare Sandbox", "file deletion");
+    }
+    renameFile() {
+        return unsupported("Cloudflare Sandbox", "file rename");
+    }
+    exposePort() {
+        return unsupported("Cloudflare Sandbox", "exposePort", "run.cloud public port capabilities are not available in the SDK yet");
+    }
+    async destroy() {
+        await (await this.ensure()).destroy();
+    }
+}
+export function getSandbox(binding, id, options = {}) {
+    const client = options.client ??
+        (binding && typeof binding === "object" && "sandboxes" in binding
+            ? binding
+            : compatibilityClient(options));
+    return new Sandbox(client, id);
+}
+//# sourceMappingURL=cloudflare.js.map

package/dist/compat/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../../src/compat/cloudflare.ts"],"names":[],"mappings":"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"}

package/dist/compat/codesandbox.d.ts

@@ -0,0 +1,72 @@
+import type { Client } from "../index.js";
+import { type CompatibilityClientOptions, type NativeSandbox } from "./common.js";
+export declare class CommandError extends Error {
+    readonly exitCode: number;
+    readonly output: string;
+    constructor(exitCode: number, output: string);
+}
+declare class Commands {
+    private readonly native;
+    constructor(native: NativeSandbox);
+    run(command: string | string[]): Promise<string>;
+    runBackground(): never;
+}
+declare class FileSystem {
+    private readonly native;
+    constructor(native: NativeSandbox);
+    readTextFile(path: string): Promise<string>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeTextFile(): never;
+    writeFile(): never;
+    readdir(): never;
+    mkdir(): never;
+    remove(): never;
+    rename(): never;
+}
+export declare class SandboxClient {
+    readonly native: NativeSandbox;
+    readonly commands: Commands;
+    readonly fs: FileSystem;
+    constructor(native: NativeSandbox);
+    get id(): string;
+    get ports(): {
+        get: () => never;
+        getAll: () => Promise<never[]>;
+        waitForPort: () => never;
+    };
+    disconnect(): void;
+}
+export declare class Sandbox {
+    readonly native: NativeSandbox;
+    private readonly client;
+    constructor(native: NativeSandbox, client: Client);
+    get id(): string;
+    connect(): Promise<SandboxClient>;
+}
+declare class Sandboxes {
+    private readonly client;
+    constructor(client: Client);
+    create(options?: {
+        id?: string;
+        image?: string;
+        vmTier?: {
+            cpu?: number;
+            memGiB?: number;
+        };
+        title?: string;
+        region?: string;
+    }): Promise<Sandbox>;
+    resume(id: string): Promise<Sandbox>;
+    get(id: string): Promise<Sandbox>;
+    list(): Promise<Sandbox[]>;
+    hibernate(id: string): Promise<void>;
+    shutdown(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export declare class CodeSandbox {
+    readonly sandboxes: Sandboxes;
+    constructor(apiToken?: string, options?: CompatibilityClientOptions & {
+        baseUrl?: string;
+    });
+}
+export {};

package/dist/compat/codesandbox.js

@@ -0,0 +1,138 @@
+import { bytesToText, compatibilityClient, createNative, getNative, listNative, unsupported, } from "./common.js";
+export class CommandError extends Error {
+    exitCode;
+    output;
+    constructor(exitCode, output) {
+        super(`command failed with exit code ${exitCode}`);
+        this.exitCode = exitCode;
+        this.output = output;
+        this.name = "CommandError";
+    }
+}
+class Commands {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async run(command) {
+        const result = await this.native.exec(command);
+        const output = result.stdout + result.stderr;
+        if (result.exitCode !== 0)
+            throw new CommandError(result.exitCode, output);
+        return output;
+    }
+    runBackground() {
+        return unsupported("CodeSandbox", "background commands");
+    }
+}
+class FileSystem {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async readTextFile(path) {
+        return bytesToText(await this.native.readFile(path));
+    }
+    async readFile(path) {
+        return await this.native.readFile(path);
+    }
+    writeTextFile() {
+        return unsupported("CodeSandbox", "file writes", "use an image or command");
+    }
+    writeFile() {
+        return unsupported("CodeSandbox", "file writes", "use an image or command");
+    }
+    readdir() {
+        return unsupported("CodeSandbox", "directory listing");
+    }
+    mkdir() {
+        return unsupported("CodeSandbox", "directory creation");
+    }
+    remove() {
+        return unsupported("CodeSandbox", "file removal");
+    }
+    rename() {
+        return unsupported("CodeSandbox", "file rename");
+    }
+}
+export class SandboxClient {
+    native;
+    commands;
+    fs;
+    constructor(native) {
+        this.native = native;
+        this.commands = new Commands(native);
+        this.fs = new FileSystem(native);
+    }
+    get id() {
+        return this.native.id;
+    }
+    get ports() {
+        return {
+            get: () => unsupported("CodeSandbox", "ports.get", "run.cloud public port capabilities are not available in the SDK yet"),
+            getAll: async () => [],
+            waitForPort: () => unsupported("CodeSandbox", "ports.waitForPort"),
+        };
+    }
+    disconnect() { }
+}
+export class Sandbox {
+    native;
+    client;
+    constructor(native, client) {
+        this.native = native;
+        this.client = client;
+    }
+    get id() {
+        return this.native.id;
+    }
+    async connect() {
+        return new SandboxClient(this.native);
+    }
+}
+class Sandboxes {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async create(options = {}) {
+        return new Sandbox(await createNative(this.client, {
+            image: options.image ?? options.id,
+            cpu: options.vmTier?.cpu,
+            memory: options.vmTier?.memGiB ? options.vmTier.memGiB * 1024 : undefined,
+            name: options.title,
+            region: options.region,
+        }), this.client);
+    }
+    async resume(id) {
+        const native = await getNative(this.client, id);
+        await native.resume();
+        return new Sandbox(native, this.client);
+    }
+    async get(id) {
+        return new Sandbox(await getNative(this.client, id), this.client);
+    }
+    async list() {
+        return (await listNative(this.client)).map((sandbox) => new Sandbox(sandbox, this.client));
+    }
+    async hibernate(id) {
+        await (await getNative(this.client, id)).pause();
+    }
+    async shutdown(id) {
+        await (await getNative(this.client, id)).destroy();
+    }
+    async delete(id) {
+        await (await getNative(this.client, id)).destroy();
+    }
+}
+export class CodeSandbox {
+    sandboxes;
+    constructor(apiToken, options = {}) {
+        this.sandboxes = new Sandboxes(compatibilityClient({
+            ...options,
+            apiKey: options.apiKey ?? apiToken,
+            apiUrl: options.apiUrl ?? options.baseUrl,
+        }));
+    }
+}
+//# sourceMappingURL=codesandbox.js.map

package/dist/compat/codesandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codesandbox.js","sourceRoot":"","sources":["../../src/compat/codesandbox.ts"],"names":[],"mappings":"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"}

package/dist/compat/common.d.ts

@@ -0,0 +1,40 @@
+import { Client, type ExecOptions, type ExecResult, type Sandbox as SandboxRecord } from "../index.js";
+export declare const DEFAULT_IMAGE = "runcloud/agent-base";
+export declare class UnsupportedCompatibilityFeatureError extends Error {
+    constructor(provider: string, feature: string, alternative?: string);
+}
+export interface CompatibilityClientOptions {
+    client?: Client;
+    apiKey?: string;
+    apiUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare function compatibilityClient(options?: CompatibilityClientOptions): Client;
+export declare class NativeSandbox {
+    readonly client: Client;
+    private record;
+    constructor(client: Client, record: SandboxRecord);
+    get id(): string;
+    get name(): string;
+    get state(): string;
+    refresh(): Promise<this>;
+    exec(command: string | string[], options?: ExecOptions): Promise<ExecResult>;
+    readFile(path: string): Promise<Uint8Array>;
+    pause(): Promise<this>;
+    resume(): Promise<this>;
+    destroy(): Promise<void>;
+}
+export declare function createNative(client: Client, options?: {
+    image?: string;
+    cpu?: number;
+    memory?: number;
+    disk?: number;
+    idlePauseSeconds?: number;
+    timeoutSeconds?: number;
+    region?: string;
+    name?: string;
+}): Promise<NativeSandbox>;
+export declare function getNative(client: Client, id: string): Promise<NativeSandbox>;
+export declare function listNative(client: Client): Promise<NativeSandbox[]>;
+export declare function unsupported(provider: string, feature: string, alternative?: string): never;
+export declare function bytesToText(bytes: Uint8Array): string;

package/dist/compat/common.js

@@ -0,0 +1,85 @@
+import { Client, } from "../index.js";
+export const DEFAULT_IMAGE = "runcloud/agent-base";
+export class UnsupportedCompatibilityFeatureError extends Error {
+    constructor(provider, feature, alternative) {
+        super(`${provider} compatibility does not support ${feature} on run.cloud yet` +
+            (alternative ? `; ${alternative}` : ""));
+        this.name = "UnsupportedCompatibilityFeatureError";
+    }
+}
+export function compatibilityClient(options = {}) {
+    if (options.client)
+        return options.client;
+    const clientOptions = {
+        apiKey: options.apiKey,
+        apiUrl: options.apiUrl,
+        fetch: options.fetch,
+    };
+    return new Client(clientOptions);
+}
+export class NativeSandbox {
+    client;
+    record;
+    constructor(client, record) {
+        this.client = client;
+        this.record = record;
+    }
+    get id() {
+        return this.record.id;
+    }
+    get name() {
+        return typeof this.record.name === "string" ? this.record.name : "";
+    }
+    get state() {
+        return this.record.state;
+    }
+    async refresh() {
+        this.record = await this.client.sandboxes.get(this.id);
+        return this;
+    }
+    async exec(command, options = {}) {
+        return await this.client.sandboxes.exec(this.id, command, options);
+    }
+    async readFile(path) {
+        return await this.client.sandboxes.readFile(this.id, path);
+    }
+    async pause() {
+        this.record = await lifecycle(this.client, this.id, "pause");
+        return this;
+    }
+    async resume() {
+        this.record = await lifecycle(this.client, this.id, "resume");
+        return this;
+    }
+    async destroy() {
+        await this.client.sandboxes.destroy(this.id);
+    }
+}
+export async function createNative(client, options = {}) {
+    return new NativeSandbox(client, await client.sandboxes.create({
+        image: options.image ?? DEFAULT_IMAGE,
+        cpu: options.cpu,
+        memory: options.memory,
+        disk: options.disk,
+        idlePauseSeconds: options.idlePauseSeconds,
+        timeoutSeconds: options.timeoutSeconds,
+        region: options.region,
+        name: options.name,
+    }));
+}
+export async function getNative(client, id) {
+    return new NativeSandbox(client, await client.sandboxes.get(id));
+}
+export async function listNative(client) {
+    return (await client.sandboxes.list()).map((item) => new NativeSandbox(client, item));
+}
+async function lifecycle(client, id, action) {
+    return await client.request("POST", `/run-cloud/sandboxes/${encodeURIComponent(id)}/${action}`, {});
+}
+export function unsupported(provider, feature, alternative) {
+    throw new UnsupportedCompatibilityFeatureError(provider, feature, alternative);
+}
+export function bytesToText(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+//# sourceMappingURL=common.js.map