A Sandbox is an isolated Linux MicroVM to run commands in.

Use Sandbox.create or Sandbox.get to construct.

​
Accessors

​
sandboxId

​
Get Signature

get sandboxId(): string;

Unique ID of this sandbox.

Returns

string

​
Methods

​
create()

static create(params?:
  | {
  source?:   | {
     type: "git";
     url: string;
     depth?: number;
     revision?: string;
   }
     | {
     type: "git";
     url: string;
     username: string;
     password: string;
     depth?: number;
     revision?: string;
   }
     | {
     type: "tarball";
     url: string;
   };
  ports?: number[];
  timeout?: number;
  resources?: {
     vcpus: number;
  };
  runtime?: "node22" | "python3.13";
}
  | {
  source?:   | {
     type: "git";
     url: string;
     depth?: number;
     revision?: string;
   }
     | {
     type: "git";
     url: string;
     username: string;
     password: string;
     depth?: number;
     revision?: string;
   }
     | {
     type: "tarball";
     url: string;
   };
  ports?: number[];
  timeout?: number;
  resources?: {
     vcpus: number;
  };
  runtime?: "node22" | "python3.13";
} & Credentials): Promise<Sandbox>;

Create a new sandbox.

​
Parameters

ParameterTypeDescription
params?| { source?: | { type: "git"; url: string; depth?: number; revision?: string; } | { type: "git"; url: string; username: string; password: string; depth?: number; revision?: string; } | { type: "tarball"; url: string; }; ports?: number[]; timeout?: number; resources?: { vcpus: number; }; runtime?: "node22" | "python3.13"; } | { source?: | { type: "git"; url: string; depth?: number; revision?: string; } | { type: "git"; url: string; username: string; password: string; depth?: number; revision?: string; } | { type: "tarball"; url: string; }; ports?: number[]; timeout?: number; resources?: { vcpus: number; }; runtime?: "node22" | "python3.13"; } & CredentialsCreation parameters and optional credentials.

​
Returns

Promise<Sandbox>

A promise resolving to the created Sandbox.

​
get()

static get(params:
  | {
  sandboxId: string;
}
  | {
  sandboxId: string;
} & Credentials): Promise<Sandbox>;

Retrieve an existing sandbox.

​
Parameters

ParameterTypeDescription
params| { sandboxId: string; } | { sandboxId: string; } & CredentialsGet parameters and optional credentials.

​
Returns

Promise<Sandbox>

A promise resolving to the Sandbox.

​
getCommand()

getCommand(cmdId: string): Promise<Command>;

Get a previously run command by its ID.

​
Parameters

ParameterTypeDescription
cmdIdstringID of the command to retrieve

​
Returns

Promise<Command>

A Command instance representing the command

​
runCommand()

​
Call Signature

runCommand(command: string, args?: string[]): Promise<CommandFinished>;

Start executing a command in this sandbox.

Parameters
ParameterTypeDescription
commandstringThe command to execute.
args?string[]Arguments to pass to the command.
Returns

Promise<CommandFinished>

A CommandFinished result once execution is done.

​
Call Signature

runCommand(params: {
  cmd: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
} & {
  detached: true;
}): Promise<Command>;

Start executing a command in detached mode.

Parameters
ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; detached?: boolean; stdout?: Writable; stderr?: Writable; } & { detached: true; }The command parameters.
Returns

Promise<Command>

A Command instance for the running command.

​
Call Signature

runCommand(params: {
  cmd: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
}): Promise<CommandFinished>;

Start executing a command in this sandbox.

Parameters
ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; detached?: boolean; stdout?: Writable; stderr?: Writable; }The command parameters.
params.cmdstringThe command to execute
params.args?string[]Arguments to pass to the command
params.cwd?stringWorking directory to execute the command in
params.env?Record<string, string>Environment variables to set for this command
params.detached?booleanIf true, the command will return without waiting for exitCode
params.stdout?WritableA Writable stream where stdout from the command will be piped
params.stderr?WritableA Writable stream where stderr from the command will be piped
Returns

Promise<CommandFinished>

A CommandFinished result once execution is done.

​
_runCommand()

_runCommand(params: {
  cmd: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
}): Promise<CommandFinished | Command>;

Internal

Internal helper to start a command in the sandbox.

​
Parameters

ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; detached?: boolean; stdout?: Writable; stderr?: Writable; }Command execution parameters.
params.cmdstringThe command to execute
params.args?string[]Arguments to pass to the command
params.cwd?stringWorking directory to execute the command in
params.env?Record<string, string>Environment variables to set for this command
params.detached?booleanIf true, the command will return without waiting for exitCode
params.stdout?WritableA Writable stream where stdout from the command will be piped
params.stderr?WritableA Writable stream where stderr from the command will be piped

​
Returns

Promise<CommandFinished | Command>

A Command or CommandFinished, depending on detached.

​
mkDir()

mkDir(path: string): Promise<void>;

Create a directory in the filesystem of this sandbox.

​
Parameters

ParameterTypeDescription
pathstringPath of the directory to create

​
Returns

Promise<void>

​
readFile()

readFile(file: {
  path: string;
  cwd?: string;
}): Promise<null | ReadableStream>;

Read a file from the filesystem of this sandbox.

​
Parameters

ParameterTypeDescription
file{ path: string; cwd?: string; }File to read, with path and optional cwd
file.pathstring-
file.cwd?string-

​
Returns

Promise<null | ReadableStream>

A promise that resolves to a ReadableStream containing the file contents

​
writeFiles()

writeFiles(files: {
  path: string;
  content: Buffer;
}[]): Promise<void>;

Write files to the filesystem of this sandbox.

​
Parameters

ParameterTypeDescription
files{ path: string; content: Buffer; }[]Array of files with path and stream/buffer contents

​
Returns

Promise<void>

A promise that resolves when the files are written

​
domain()

domain(p: number): string;

Get the public domain of a port of this sandbox.

​
Parameters

ParameterTypeDescription
pnumberPort number to resolve

​
Returns

string

A full domain (e.g. https://subdomain.vercel.run)

​
Throws

If the port has no associated route

​
stop()

stop(): Promise<void>;

Stop the sandbox.

​
Returns

Promise<void>

A promise that resolves when the sandbox is stopped