Skip to main content
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

​
status

​
Get Signature

get status(): "pending" | "running" | "stopping" | "stopped" | "failed";
The status of the sandbox.
Returns
"pending" | "running" | "stopping" | "stopped" | "failed"

​
timeout

​
Get Signature

get timeout(): number;
The timeout of the sandbox in milliseconds.
Returns
number

​
Methods

​
list()

static list(params: {
  projectId: string;
  limit?: number;
  since?: number | Date;
  until?: number | Date;
  signal?: AbortSignal;
} & Partial<Credentials>): Promise<Parsed<{
  sandboxes: {
     id: string;
     memory: number;
     vcpus: number;
     region: string;
     runtime: string;
     timeout: number;
     status: "pending" | "running" | "stopping" | "stopped" | "failed";
     requestedAt: number;
     startedAt?: number;
     requestedStopAt?: number;
     stoppedAt?: number;
     duration?: number;
     createdAt: number;
     cwd: string;
     updatedAt: number;
  }[];
  pagination: {
     count: number;
     next: null | number;
     prev: null | number;
  };
}>>;
Allow to get a list of sandboxes for a team narrowed to the given params. It returns both the sandboxes and the pagination metadata to allow getting the next page of results.

​
Parameters

ParameterType
params{ projectId: string; limit?: number; since?: number | Date; until?: number | Date; signal?: AbortSignal; } & Partial<Credentials>

​
Returns

Promise<Parsed<{ sandboxes: { id: string; memory: number; vcpus: number; region: string; runtime: string; timeout: number; status: "pending" | "running" | "stopping" | "stopped" | "failed"; requestedAt: number; startedAt?: number; requestedStopAt?: number; stoppedAt?: number; duration?: number; createdAt: number; cwd: string; updatedAt: number; }[]; pagination: { count: number; next: null | number; prev: null | number; }; }>>

​
create()

static create(params?: WithPrivate<
  | {
  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?:   | string & {
   }
     | "node22"
     | "python3.13";
  signal?: AbortSignal;
}
  | {
  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?:   | string & {
   }
     | "node22"
     | "python3.13";
  signal?: AbortSignal;
} & Credentials>): Promise<Sandbox>;
Create a new sandbox.

​
Parameters

ParameterTypeDescription
params?WithPrivate< | { 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?: | string & { } | "node22" | "python3.13"; signal?: AbortSignal; } | { 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?: | string & { } | "node22" | "python3.13"; signal?: AbortSignal; } & Credentials>Creation parameters and optional credentials.

​
Returns

Promise<Sandbox> A promise resolving to the created Sandbox.

​
get()

static get(params:
  | {
  sandboxId: string;
  signal?: AbortSignal;
}
  | {
  sandboxId: string;
  signal?: AbortSignal;
} & Credentials): Promise<Sandbox>;
Retrieve an existing sandbox.

​
Parameters

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

​
Returns

Promise<Sandbox> A promise resolving to the Sandbox.

​
getCommand()

getCommand(cmdId: string, opts?: {
  signal?: AbortSignal;
}): Promise<Command>;
Get a previously run command by its ID.

​
Parameters

ParameterTypeDescription
cmdIdstringID of the command to retrieve
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
Returns

Promise<Command> A Command instance representing the command

​
runCommand()

​
Call Signature

runCommand(
   command: string,
   args?: string[],
   opts?: {
  signal?: AbortSignal;
}): Promise<CommandFinished>;
Start executing a command in this sandbox.
Parameters
ParameterTypeDescription
commandstringThe command to execute.
args?string[]Arguments to pass to the command.
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the command execution.
Returns
Promise<CommandFinished> A CommandFinished result once execution is done.

​
Call Signature

runCommand(params: {
  cmd: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  sudo?: boolean;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
  signal?: AbortSignal;
} & {
  detached: true;
}): Promise<Command>;
Start executing a command in detached mode.
Parameters
ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; sudo?: boolean; detached?: boolean; stdout?: Writable; stderr?: Writable; signal?: AbortSignal; } & { 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>;
  sudo?: boolean;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
  signal?: AbortSignal;
}): Promise<CommandFinished>;
Start executing a command in this sandbox.
Parameters
ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; sudo?: boolean; detached?: boolean; stdout?: Writable; stderr?: Writable; signal?: AbortSignal; }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.sudo?booleanIf true, execute this command with root privileges. Defaults to false.
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
params.signal?AbortSignalAn AbortSignal to cancel the command execution
Returns
Promise<CommandFinished> A CommandFinished result once execution is done.

​
_runCommand()

_runCommand(params: {
  cmd: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  sudo?: boolean;
  detached?: boolean;
  stdout?: Writable;
  stderr?: Writable;
  signal?: AbortSignal;
}): Promise<Command | CommandFinished>;
Internal Internal helper to start a command in the sandbox.

​
Parameters

ParameterTypeDescription
params{ cmd: string; args?: string[]; cwd?: string; env?: Record<string, string>; sudo?: boolean; detached?: boolean; stdout?: Writable; stderr?: Writable; signal?: AbortSignal; }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.sudo?booleanIf true, execute this command with root privileges. Defaults to false.
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
params.signal?AbortSignalAn AbortSignal to cancel the command execution

​
Returns

Promise<Command | CommandFinished> A Command or CommandFinished, depending on detached.

​
mkDir()

mkDir(path: string, opts?: {
  signal?: AbortSignal;
}): Promise<void>;
Create a directory in the filesystem of this sandbox.

​
Parameters

ParameterTypeDescription
pathstringPath of the directory to create
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
Returns

Promise<void>

​
readFile()

readFile(file: {
  path: string;
  cwd?: string;
}, opts?: {
  signal?: AbortSignal;
}): 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-
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
Returns

Promise<null | ReadableStream> A promise that resolves to a ReadableStream containing the file contents

​
writeFiles()

writeFiles(files: {
  path: string;
  content: Buffer;
}[], opts?: {
  signal?: AbortSignal;
}): Promise<void>;
Write files to the filesystem of this sandbox. Defaults to writing to /vercel/sandbox unless an absolute path is specified. Writes files using the vercel-sandbox user.

​
Parameters

ParameterTypeDescription
files{ path: string; content: Buffer; }[]Array of files with path and stream/buffer contents
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
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(opts?: {
  signal?: AbortSignal;
}): Promise<void>;
Stop the sandbox.

​
Parameters

ParameterTypeDescription
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
Returns

Promise<void> A promise that resolves when the sandbox is stopped

​
extendTimeout()

extendTimeout(duration: number, opts?: {
  signal?: AbortSignal;
}): Promise<void>;
Extend the timeout of the sandbox by the specified duration. This allows you to extend the lifetime of a sandbox up until the maximum execution timeout for your plan.

​
Parameters

ParameterTypeDescription
durationnumberThe duration in milliseconds to extend the timeout by
opts?{ signal?: AbortSignal; }Optional parameters.
opts.signal?AbortSignalAn AbortSignal to cancel the operation.

​
Returns

Promise<void> A promise that resolves when the timeout is extended