Class Sandbox

ReadonlysandboxId

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>

open

• open(path: string, mode?: SandboxFileMode): Promise<SandboxFile>

  Open a file in the Sandbox filesystem.

  Parameters

  • path: string

    Path to the file to open
  • mode: SandboxFileMode = "r"

    File open mode (r, w, a, r+, w+, a+)

  Returns Promise<SandboxFile>

  Promise that resolves to a SandboxFile

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 Sandbox.list.

  Parameters

  • tags: Record<string, string>

  Returns Promise<void>

snapshotDirectory

• snapshotDirectory(path: string): Promise<Image>

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

  Parameters

  • path: string

    The path of the directory to snapshot

  Returns Promise<Image>

  Promise that resolves to an Image

snapshotFilesystem

• snapshotFilesystem(timeoutMs?: number): 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.

  Parameters

  • timeoutMs: number = 55000

    Timeout for the snapshot operation in milliseconds

  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.

wait

• wait(): Promise<number>

  Returns Promise<number>

StaticfromId

• fromId(sandboxId: string): Promise<Sandbox>

  Parameters

  • sandboxId: string

  Returns Promise<Sandbox>

  Deprecated

  Use client.sandboxes.fromId() instead.

StaticfromName

• fromName(appName: string, name: string, environment?: string): Promise<Sandbox>

  Parameters

  • appName: string
  • name: string
  • Optionalenvironment: string

  Returns Promise<Sandbox>

  Deprecated

  Use client.sandboxes.fromName() instead.

Staticlist

• list(params?: SandboxListParams): AsyncGenerator<Sandbox, void, unknown>

  Parameters

  • params: SandboxListParams = {}

  Returns AsyncGenerator<Sandbox, void, unknown>

  Deprecated

  Use client.sandboxes.list() instead.