@hasna/sandboxes 0.1.26 → 0.1.28

package/README.md

@@ -17,6 +17,29 @@ npm install -g @hasna/sandboxes
 sandboxes --help
 ```
 
+## SDK One-shot Commands
+
+Use the SDK to create a sandbox, upload a local project, run a command, and clean up:
+
+```ts
+import { createSandboxesSDK } from "@hasna/sandboxes";
+
+const sandboxes = createSandboxesSDK();
+
+await sandboxes.runCommandInSandbox({
+  provider: "e2b",
+  command: "bun test",
+  upload: {
+    localDir: process.cwd(),
+    remoteDir: "/workspace/app",
+    syncStrategy: "rsync",
+  },
+  cleanup: "delete",
+});
+```
+
+Set `E2B_API_KEY` for E2B-backed runs. `syncStrategy: "rsync"` mirrors the local directory into a temporary staging tree with `rsync` before uploading it through the provider file APIs.
+
 ## MCP Server
 
 ```bash

package/dist/cli/index.js

@@ -12060,7 +12060,9 @@ var init_config2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -12068,6 +12070,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -12084,6 +12095,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { BUILTIN_IMAGES, resolveImage, getBuiltinImageSetupScript } from "./lib/
 export { getProvider } from "./providers/index.js";
 export type { SandboxProvider, ProviderSandbox, CreateSandboxOpts, ExecOptions } from "./providers/types.js";
 export { SandboxesSDK, createSandboxesSDK, } from "./sdk.js";
-export type { ExecCommandResult, ProviderFactory, RunAgentOptions, SandboxesSDKOptions, WaitForSessionOptions, } from "./sdk.js";
+export type { ExecCommandResult, ProviderFactory, RunAgentOptions, RunCommandInSandboxOptions, RunCommandInSandboxResult, RunCommandInSandboxUploadOptions, SandboxesSDKOptions, OneShotSandboxCleanup, WaitForSessionOptions, } from "./sdk.js";
 export { createStreamCollector, addStreamListener, emitLifecycleEvent } from "./lib/stream.js";
 export { getAgentDriver, listAgentDrivers } from "./lib/agents/index.js";
 export type { AgentDriver } from "./lib/agents/types.js";

package/dist/index.js

@@ -88,7 +88,9 @@ var init_types = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -96,6 +98,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -112,6 +123,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);
@@ -11643,6 +11671,54 @@ class SandboxesSDK {
     emitLifecycleEvent(sandbox.id, `uploaded ${localDir} -> ${remoteDir} (${result.bytes} bytes)`);
     return result;
   }
+  async runCommandInSandbox(input) {
+    const cleanupMode = input.cleanup ?? "delete";
+    const sandbox = await this.createSandbox({
+      provider: input.provider,
+      name: input.name,
+      image: input.image,
+      timeout: input.sandboxTimeout,
+      env_vars: input.sandboxEnvVars,
+      config: input.config,
+      project_id: input.projectId
+    });
+    let upload;
+    let exec;
+    try {
+      if (input.upload) {
+        const uploadOptions = {};
+        if (input.upload.exclude !== undefined)
+          uploadOptions.exclude = input.upload.exclude;
+        if (input.upload.syncStrategy !== undefined)
+          uploadOptions.syncStrategy = input.upload.syncStrategy;
+        upload = await this.uploadDir(sandbox.id, input.upload.localDir, input.upload.remoteDir, uploadOptions);
+      }
+      exec = await this.execCommand(sandbox.id, input.command, {
+        cwd: input.cwd ?? input.upload?.remoteDir,
+        env: input.callEnvVars,
+        timeout: input.commandTimeoutMs,
+        onStdout: input.onStdout,
+        onStderr: input.onStderr
+      });
+    } finally {
+      if (cleanupMode === "delete") {
+        await this.deleteSandbox(sandbox.id);
+      } else if (cleanupMode === "stop") {
+        await this.stopSandbox(sandbox.id);
+      }
+    }
+    if (!exec) {
+      throw new Error("Sandbox command did not produce an execution result");
+    }
+    return {
+      sandbox,
+      session: exec.session,
+      result: exec.result,
+      upload,
+      remoteDir: input.upload?.remoteDir,
+      cleanup: cleanupMode === "delete" ? "deleted" : cleanupMode === "stop" ? "stopped" : "kept"
+    };
+  }
   async runAgent(sandboxId, opts) {
     const sandbox = this.requireProviderSandbox(sandboxId);
     const provider = await this.getProvider(sandbox.provider);

package/dist/lib/archive.d.ts

@@ -11,6 +11,8 @@ export interface TarDirectoryOptions {
      * {@link DEFAULT_UPLOAD_EXCLUDES}; pass `[]` to include everything.
      */
     exclude?: string[];
+    /** Prepare a temporary upload tree with rsync before creating the archive. */
+    syncStrategy?: "archive" | "rsync";
 }
 /** Single-quote a value for safe POSIX shell interpolation. */
 export declare function shellQuote(value: string): string;

package/dist/mcp/index.js

@@ -61,7 +61,9 @@ var init_types2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -69,6 +71,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -85,6 +96,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);

package/dist/sdk.d.ts

@@ -15,6 +15,38 @@ export interface ExecCommandResult {
     session: SandboxSession;
     result: ExecResult;
 }
+export type OneShotSandboxCleanup = "delete" | "stop" | "keep";
+export interface RunCommandInSandboxUploadOptions {
+    localDir: string;
+    remoteDir: string;
+    exclude?: string[];
+    syncStrategy?: "archive" | "rsync";
+}
+export interface RunCommandInSandboxOptions {
+    command: string;
+    provider?: SandboxProviderName;
+    name?: string;
+    image?: string;
+    sandboxTimeout?: number;
+    commandTimeoutMs?: number;
+    projectId?: string;
+    config?: Record<string, unknown>;
+    sandboxEnvVars?: Record<string, string>;
+    callEnvVars?: Record<string, string>;
+    cwd?: string;
+    upload?: RunCommandInSandboxUploadOptions;
+    cleanup?: OneShotSandboxCleanup;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+}
+export interface RunCommandInSandboxResult {
+    sandbox: Sandbox;
+    session: SandboxSession;
+    result: ExecResult;
+    upload?: UploadDirResult;
+    remoteDir?: string;
+    cleanup: "deleted" | "stopped" | "kept";
+}
 export interface RunAgentOptions {
     agentType: AgentType;
     prompt: string;
@@ -54,6 +86,7 @@ export declare class SandboxesSDK {
         glob?: string;
     }): Promise<FileInfo[]>;
     uploadDir(sandboxId: string, localDir: string, remoteDir: string, opts?: UploadDirOptions): Promise<UploadDirResult>;
+    runCommandInSandbox(input: RunCommandInSandboxOptions): Promise<RunCommandInSandboxResult>;
     runAgent(sandboxId: string, opts: RunAgentOptions): Promise<SandboxSession>;
     getSession(sessionId: string): SandboxSession;
     waitForSession(sessionId: string, opts?: WaitForSessionOptions): Promise<SandboxSession>;

package/dist/server/index.js

@@ -97,7 +97,9 @@ var init_types2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -105,6 +107,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -121,6 +132,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);

package/dist/types/index.d.ts

@@ -179,6 +179,12 @@ export interface FileInfo {
 export interface UploadDirOptions {
     /** Patterns to exclude (passed to `tar --exclude`); defaults applied by the archiver. */
     exclude?: string[];
+    /**
+     * How to prepare the upload payload. `archive` tars the source directory
+     * directly; `rsync` first mirrors the source into a temporary staging
+     * directory with rsync, then uploads the staged tree.
+     */
+    syncStrategy?: "archive" | "rsync";
 }
 export interface UploadDirResult {
     /** Number of bytes uploaded (compressed archive size). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/sandboxes",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "author": "Andrei Hasna <andrei@hasna.com>",
   "repository": {
     "type": "git",