@agent-sandbox/api

Programmatic wrapper for Agent Sandbox.

Install

npm install @agent-sandbox/api

Requirements

• Docker running locally

Quick Start

import { AgentSandbox } from "@agent-sandbox/api";

const sandbox = new AgentSandbox();
const { sandboxId } = await sandbox.create();

const { output } = await sandbox.write({ sandboxId, input: "echo hello" });
console.log(output);

await sandbox.delete({ sandboxId });

API Reference

create(options?)

sandbox.create(options?: {
  name?: string;
  image?: string;
  clone?: string;
}): Promise<{ sandboxId: string }>

delete(options)

sandbox.delete(options: {
  sandboxId: string;
}): Promise<{ ok: boolean }>

list()

sandbox.list(): Promise<{
  sandboxes: Array<{
    id: string;
    name: string;
    status: string;
    createdAt: string;
  }>;
}>

read(options)

sandbox.read(options: {
  sandboxId: string;
  tail?: number;
}): Promise<{ output: string }>

Returns container logs. tail limits to the last N lines.

write(options)

sandbox.write(options: {
  sandboxId: string;
  input: string;
  detach?: boolean;
}): Promise<{ ok: boolean; output?: string; exitCode?: number }>

Runs the command and returns its output and exit code. Set detach: true to fire-and-forget (returns immediately with no output, useful for starting background processes).

upload(options)

sandbox.upload(options: {
  sandboxId: string;
  localPath: string;
  remotePath: string;
}): Promise<{ ok: boolean }>

Both paths must be absolute.

download(options)

sandbox.download(options: {
  sandboxId: string;
  remotePath: string;
  localPath: string;
}): Promise<{ ok: boolean }>

remotePath may be a file or directory. Both paths must be absolute.

License

MIT