Class Sandbox

ReadonlysandboxId

experimentalSidecars

• get experimentalSidecars(): SidecarService

  Operations for managing sidecar containers that run alongside the Sandbox's main container.

  EXPERIMENTAL: the API is subject to change.

  Returns SidecarService

filesystem

• get filesystem(): SandboxFilesystem

  Returns SandboxFilesystem

stderr

• get stderr(): ModalReadStream<string>

  Returns ModalReadStream<string>

stdin

• get stdin(): ModalWriteStream<string>

  Returns ModalWriteStream<string>

stdout

• get stdout(): ModalReadStream<string>

  Returns ModalReadStream<string>

createConnectToken

• createConnectToken(
      params?: SandboxCreateConnectTokenParams,
  ): Promise<SandboxCreateConnectCredentials>

  Create a token for making HTTP connections to the Sandbox.

  Parameters

  • Optionalparams: SandboxCreateConnectTokenParams

  Returns Promise<SandboxCreateConnectCredentials>

detach

• detach(): void

  Disconnect from the Sandbox, cleaning up local resources. The Sandbox continues running on Modal's infrastructure. After calling detach(), most operations on this Sandbox object will throw.

  Returns void

exec

• exec(
      command: string[],
      params?: SandboxExecParams & { mode?: "text" },
  ): Promise<ContainerProcess<string>>

  Parameters

  • command: string[]
  • Optionalparams: SandboxExecParams & { mode?: "text" }

  Returns Promise<ContainerProcess<string>>

• exec(
      command: string[],
      params: SandboxExecParams & { mode: "binary" },
  ): Promise<ContainerProcess<Uint8Array<ArrayBufferLike>>>

  Parameters

  • command: string[]
  • params: SandboxExecParams & { mode: "binary" }

  Returns Promise<ContainerProcess<Uint8Array<ArrayBufferLike>>>

getTags

• getTags(): Promise<Record<string, string>>

  Get tags (key-value pairs) currently attached to this Sandbox from the server.

  Returns Promise<Record<string, string>>

mountImage

• mountImage(path: string, image?: Image): Promise<void>

  Mount an Image at a path in the Sandbox filesystem.

  Parameters

  • path: string

    The path where the directory should be mounted
  • Optionalimage: Image

    Optional Image to mount. If undefined, mounts an empty directory.

  Returns Promise<void>

poll

• poll(): Promise<null | number>

  Check if the Sandbox has finished running.

  Returns null if the Sandbox is still running, else returns the exit code.

  Returns Promise<null | number>

setTags

• setTags(tags: Record<string, string>): Promise<void>

  Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in client.sandboxes.list.

  Parameters

  • tags: Record<string, string>

  Returns Promise<void>

snapshotDirectory

• snapshotDirectory(
      path: string,
      params?: SandboxSnapshotDirectoryParams,
  ): Promise<Image>

  Snapshots and creates a new Image from a directory in the running sandbox.

  The resulting Image is retained for ttlMs (default: 30 days), as a hard cutoff measured from creation — usage does not extend the lifetime. Pass ttlMs: null to retain indefinitely.

  The call has an overall timeoutMs budget (default: 55000). If it elapses before a snapshot completes, the call is cancelled and an error is thrown.

  Parameters

  • path: string

    The path of the directory to snapshot
  • Optionalparams: SandboxSnapshotDirectoryParams

    Optional parameters; see SandboxSnapshotDirectoryParams.

  Returns Promise<Image>

  Promise that resolves to an Image

snapshotFilesystem

• snapshotFilesystem(params?: SandboxSnapshotFilesystemParams): Promise<Image>

  Snapshot the filesystem of the Sandbox.

  Returns an Image object which can be used to spawn a new Sandbox with the same filesystem.

  The call has an overall timeoutMs budget (default: 55000). If it elapses before a snapshot completes, the call is cancelled and an error is thrown.

  Parameters

  • Optionalparams: SandboxSnapshotFilesystemParams

    Optional parameters; see SandboxSnapshotFilesystemParams.

  Returns Promise<Image>

  Promise that resolves to an Image

terminate

• terminate(): Promise<void>

  Returns Promise<void>

• terminate(params: { wait: true }): Promise<number>

  Parameters

  • params: { wait: true }

  Returns Promise<number>

tunnels

• tunnels(timeoutMs?: number): Promise<Record<number, Tunnel>>

  Get Tunnel metadata for the Sandbox.

  Raises SandboxTimeoutError if the tunnels are not available after the timeout.

  Parameters

  • timeoutMs: number = 50000

  Returns Promise<Record<number, Tunnel>>

  A dictionary of Tunnel objects which are keyed by the container port.

unmountImage

• unmountImage(path: string): Promise<void>

  Unmounts an Image previously mounted at a path in the Sandbox filesystem.

  Parameters

  • path: string

    The mount path to unmount

  Returns Promise<void>

wait

• wait(): Promise<number>

  Returns Promise<number>

waitUntilReady

• waitUntilReady(timeoutMs?: number): Promise<void>

  Wait until the Sandbox readiness probe reports the Sandbox is ready.

  This method only works for Sandboxes configured with a readiness probe.

  Parameters

  • timeoutMs: number = 300_000

    Maximum total time to wait, in milliseconds.

  Returns Promise<void>

  A promise that resolves once the Sandbox is ready.

  Throws

  TimeoutError If readiness is not reported before timeoutMs.