Sandbox

Sandbox represents a Modal Sandbox, which can run commands and manage input/output streams for a remote process. After you are done interacting with the sandbox, we recommend calling Sandbox.Detach which disconnects your client from the sandbox and cleans up any resources associated with the connection.

type Sandbox struct {
	SandboxID            string
	Stdin                io.WriteCloser
	Stdout               io.ReadCloser
	Stderr               io.ReadCloser
	Filesystem           *SandboxFilesystem // Filesystem provides high-level filesystem operations for this Sandbox.
	ExperimentalSidecars SidecarService     // ExperimentalSidecars provides operations on Sandbox Sidecar containers. EXPERIMENTAL: the API is subject to change.
}

Create

Accessed via client.Sandboxes

Create(ctx context.Context, app *App, image *Image, params *SandboxCreateParams) (*Sandbox, error)

Create creates a new Sandbox in the App with the specified Image and options.

Parameters (SandboxCreateParams)

SandboxCreateParams are options for creating a Modal Sandbox.

CPU (float64): CPU request in fractional, physical cores.
CPULimit (float64): Hard limit in fractional, physical CPU cores. Zero means no limit.
MemoryMiB (int): Memory request in MiB.
MemoryLimitMiB (int): Hard memory limit in MiB. Zero means no limit.
GPU (string): GPU reservation for the Sandbox (e.g. "A100", "T4:2", "A100-80GB:4").
Timeout (time.Duration): Maximum lifetime of the Sandbox. Defaults to 5 minutes. If you pass zero you get the default 5 minutes.
IdleTimeout (time.Duration): The amount of time that a Sandbox can be idle before being terminated.
Workdir (string): Working directory of the Sandbox.
Command ([]string): Command to run in the Sandbox on startup.
Env (map[string]string): Environment variables to set in the Sandbox.
Secrets ([]*Secret): Secrets to inject into the Sandbox as environment variables.
Volumes (map[string]*Volume): Mount points for Volumes.
CloudBucketMounts (map[string]*CloudBucketMount): Mount points for cloud buckets.
PTY (bool): Enable a PTY for the Sandbox entrypoint command. When enabled, all output (stdout and stderr from the process) is multiplexed into stdout, and the stderr stream is effectively empty.
EncryptedPorts ([]int): List of encrypted ports to tunnel into the Sandbox, with TLS encryption.
H2Ports ([]int): List of encrypted ports to tunnel into the Sandbox, using HTTP/2.
UnencryptedPorts ([]int): List of ports to tunnel into the Sandbox without encryption.
BlockNetwork (bool): Whether to block all network access from the Sandbox.
OutboundCIDRAllowlist (*Allowlist): CIDRs the Sandbox is allowed to access. Non-nil enables allowlist mode; nil means open access. Cannot be used with BlockNetwork.
OutboundDomainAllowlist (*Allowlist): Domain names the Sandbox is allowed to access (supports wildcard prefixes like *.example.com). Non-nil enables allowlist mode; nil means open access. Cannot be used with BlockNetwork.
InboundCIDRAllowlist ([]string): List of CIDRs allowed to connect inbound to the Sandbox (tunnels and connection tokens). If empty, all IPs are allowed.
I6PN (bool): Enable private IPv6 networking (i6pn) so Sandboxes in the same workspace can reach each other at their i6pn.modal.local address. Pin every Sandbox in the group to the same specific region. Cannot be used with BlockNetwork.
Cloud (string): Cloud provider to run the Sandbox on.
Regions ([]string): Region(s) to run the Sandbox on.
Verbose (bool): Enable verbose logging.
Proxy (*Proxy): Reference to a Modal Proxy to use in front of this Sandbox.
ReadinessProbe (*Probe): Probe used to determine when the Sandbox is ready.
Name (string): Optional name for the Sandbox. Unique within an App.
Tags (map[string]string): Tags to attach to the Sandbox. Filterable via SandboxList.
ExperimentalOptions (map[string]any): Experimental options
CustomDomain (string): If non-empty, connections to this Sandbox will be subdomains of this domain rather than the default. This requires prior manual setup by Modal and is only available for Enterprise customers.
IncludeOidcIdentityToken (bool): If true, the sandbox will receive a MODAL_IDENTITY_TOKEN env var for OIDC-based auth (e.g. to AWS, GCP).
ExperimentalEnableSnapshot (bool): Enable memory snapshots.

ExperimentalCreate

Accessed via client.Sandboxes

ExperimentalCreate(ctx context.Context, app *App, image *Image, params *SandboxCreateParams) (*Sandbox, error)

ExperimentalCreate creates a new Sandbox using the experimental V2 backend.

Supported features include exec, encrypted tunnels, wait/poll/terminate, CPU and memory configuration, region placement, volumes, cloud bucket mounts (with static credentials via Secret or OidcAuthRoleArn), OIDC identity tokens, proxies, filesystem snapshots, and custom domains (CustomDomain allows connections to the Sandbox via a subdomain of that parent domain rather than a default Modal domain; requires prior setup by Modal).

Set ExperimentalEnableSnapshot to create a Sandbox that can be snapshotted with Sandbox.ExperimentalSnapshot. Features like network file systems and GPUs are not supported.

V2 sandboxes created with this method are not currently returned by List. A named Sandbox can be looked up with ExperimentalFromName; otherwise store Sandbox.SandboxID and use FromID to reattach.

Parameters (SandboxCreateParams)

SandboxCreateParams are options for creating a Modal Sandbox.

CPU (float64): CPU request in fractional, physical cores.
CPULimit (float64): Hard limit in fractional, physical CPU cores. Zero means no limit.
MemoryMiB (int): Memory request in MiB.
MemoryLimitMiB (int): Hard memory limit in MiB. Zero means no limit.
GPU (string): GPU reservation for the Sandbox (e.g. "A100", "T4:2", "A100-80GB:4").
Timeout (time.Duration): Maximum lifetime of the Sandbox. Defaults to 5 minutes. If you pass zero you get the default 5 minutes.
IdleTimeout (time.Duration): The amount of time that a Sandbox can be idle before being terminated.
Workdir (string): Working directory of the Sandbox.
Command ([]string): Command to run in the Sandbox on startup.
Env (map[string]string): Environment variables to set in the Sandbox.
Secrets ([]*Secret): Secrets to inject into the Sandbox as environment variables.
Volumes (map[string]*Volume): Mount points for Volumes.
CloudBucketMounts (map[string]*CloudBucketMount): Mount points for cloud buckets.
PTY (bool): Enable a PTY for the Sandbox entrypoint command. When enabled, all output (stdout and stderr from the process) is multiplexed into stdout, and the stderr stream is effectively empty.
EncryptedPorts ([]int): List of encrypted ports to tunnel into the Sandbox, with TLS encryption.
H2Ports ([]int): List of encrypted ports to tunnel into the Sandbox, using HTTP/2.
UnencryptedPorts ([]int): List of ports to tunnel into the Sandbox without encryption.
BlockNetwork (bool): Whether to block all network access from the Sandbox.
OutboundCIDRAllowlist (*Allowlist): CIDRs the Sandbox is allowed to access. Non-nil enables allowlist mode; nil means open access. Cannot be used with BlockNetwork.
OutboundDomainAllowlist (*Allowlist): Domain names the Sandbox is allowed to access (supports wildcard prefixes like *.example.com). Non-nil enables allowlist mode; nil means open access. Cannot be used with BlockNetwork.
InboundCIDRAllowlist ([]string): List of CIDRs allowed to connect inbound to the Sandbox (tunnels and connection tokens). If empty, all IPs are allowed.
I6PN (bool): Enable private IPv6 networking (i6pn) so Sandboxes in the same workspace can reach each other at their i6pn.modal.local address. Pin every Sandbox in the group to the same specific region. Cannot be used with BlockNetwork.
Cloud (string): Cloud provider to run the Sandbox on.
Regions ([]string): Region(s) to run the Sandbox on.
Verbose (bool): Enable verbose logging.
Proxy (*Proxy): Reference to a Modal Proxy to use in front of this Sandbox.
ReadinessProbe (*Probe): Probe used to determine when the Sandbox is ready.
Name (string): Optional name for the Sandbox. Unique within an App.
Tags (map[string]string): Tags to attach to the Sandbox. Filterable via SandboxList.
ExperimentalOptions (map[string]any): Experimental options
CustomDomain (string): If non-empty, connections to this Sandbox will be subdomains of this domain rather than the default. This requires prior manual setup by Modal and is only available for Enterprise customers.
IncludeOidcIdentityToken (bool): If true, the sandbox will receive a MODAL_IDENTITY_TOKEN env var for OIDC-based auth (e.g. to AWS, GCP).
ExperimentalEnableSnapshot (bool): Enable memory snapshots.

FromID

Accessed via client.Sandboxes

FromID(ctx context.Context, sandboxID string, params *SandboxFromIDParams) (*Sandbox, error)

FromID returns a running Sandbox object from an ID.

Parameters (SandboxFromIDParams)

SandboxFromIDParams are options for SandboxService.FromID.

No configurable options.

FromName

Accessed via client.Sandboxes

FromName(ctx context.Context, appName, name string, params *SandboxFromNameParams) (*Sandbox, error)

FromName gets a running Sandbox by name from a deployed App.

Raises a NotFoundError if no running Sandbox is found with the given name. A Sandbox's name is the Name argument passed to App.CreateSandbox.

Parameters (SandboxFromNameParams)

SandboxFromNameParams are options for finding deployed Sandbox objects by name.

Environment (string)

ExperimentalFromName

Accessed via client.Sandboxes

ExperimentalFromName(ctx context.Context, appName, name string, params *SandboxExperimentalFromNameParams) (*Sandbox, error)

ExperimentalFromName gets a running V2 Sandbox by name from a deployed App, i.e. a Sandbox created via ExperimentalCreate.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalFromNameParams)

SandboxExperimentalFromNameParams are options for SandboxService.ExperimentalFromName.

Environment (string)

ExperimentalFromSnapshot

Accessed via client.Sandboxes

ExperimentalFromSnapshot(ctx context.Context, snapshot *SandboxSnapshot, params *SandboxExperimentalFromSnapshotParams) (*Sandbox, error)

ExperimentalFromSnapshot restores a Sandbox from a memory snapshot.

The restore targets the same backend the snapshot was taken from. A V1 snapshot restores as a V1 sandbox, a V2 snapshot as a V2 sandbox.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalFromSnapshotParams)

SandboxExperimentalFromSnapshotParams are options for SandboxService.ExperimentalFromSnapshot.

Name (*string): Name for the restored Sandbox. Nil reuses the original Sandbox's name, a pointer to an empty string leaves it unnamed, and a pointer to a non-empty string overrides it.

List

Accessed via client.Sandboxes

List(ctx context.Context, params *SandboxListParams) (iter.Seq2[*Sandbox, error], error)

List lists Sandboxes for the current environment (or provided App ID), optionally filtered by tags.

Parameters (SandboxListParams)

SandboxListParams are options for listing Sandboxes.

AppID (string): Filter by App ID
Tags (map[string]string): Only include Sandboxes that have all these tags
Environment (string): Override environment for this request

ExperimentalList

Accessed via client.Sandboxes

ExperimentalList(ctx context.Context, params *SandboxExperimentalListParams) (iter.Seq2[*Sandbox, error], error)

ExperimentalList lists all sandboxes (v1 and v2). Pass AppID to scope to an App; omit it to list across the environment (deprecated — prefer scoping by AppID). If Tags are specified, only Sandboxes that have all those tags are returned.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalListParams)

SandboxExperimentalListParams are options for SandboxService.ExperimentalList.

AppID (string): The App to list Sandboxes under. Omit to list across the environment (deprecated).
Tags (map[string]string): Only include Sandboxes that have all these tags.
Environment (string): Override environment for this request (used only when AppID is empty).

CreateConnectToken

CreateConnectToken(ctx context.Context, params *SandboxCreateConnectTokenParams) (*SandboxCreateConnectCredentials, error)

CreateConnectToken creates a token for making HTTP connections to the Sandbox.

Parameters (SandboxCreateConnectTokenParams)

SandboxCreateConnectTokenParams are optional parameters for CreateConnectToken.

UserMetadata (string): Optional user-provided metadata string that will be added to the headers by the proxy when forwarding requests to the Sandbox.
Port (int): Container port that requests are routed to when using this token. Defaults to 8080.

Detach

Detach() error

Detach disconnects from the running Sandbox

Exec

Exec(ctx context.Context, command []string, params *SandboxExecParams) (*ContainerProcess, error)

Exec runs a command in the Sandbox and returns the process handle.

Parameters (SandboxExecParams)

SandboxExecParams defines options for executing commands in a Sandbox.

Stdout (StdioBehavior): Stdout defines whether to pipe or ignore standard output.
Stderr (StdioBehavior): Stderr defines whether to pipe or ignore standard error.
Workdir (string): Workdir is the working directory to run the command in.
Timeout (time.Duration): Timeout is the timeout for command execution. Defaults to 0 (no timeout).
Env (map[string]string): Environment variables to set for the command.
Secrets ([]*Secret): Secrets to inject as environment variables for the command.
PTY (bool): PTY defines whether to enable a PTY for the command. When enabled, all output (stdout and stderr from the process) is multiplexed into stdout, and the stderr stream is effectively empty.

ExperimentalGetExitSnapshot

ExperimentalGetExitSnapshot(ctx context.Context, params *SandboxExperimentalGetExitSnapshotParams) (*Image, error)

ExperimentalGetExitSnapshot gets the exit filesystem snapshot image.

Returns InvalidError if the Timeout is negative, or if exit snapshot is not enabled for the Sandbox. Returns TimeoutError if the Timeout elapses before the snapshot reaches a terminal state. This includes a Timeout of 0 when the snapshot is still pending. Returns SnapshotCreationError if no exit snapshot image will be produced. Returns NotFoundError if the Sandbox does not exist.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalGetExitSnapshotParams)

SandboxExperimentalGetExitSnapshotParams are options for Sandbox.ExperimentalGetExitSnapshot.

Timeout (*time.Duration): Timeout is the total time to wait, spread across repeated long polls of at most exitSnapshotLongPollTimeout each. nil (the default) waits until the snapshot reaches a terminal state. 0 performs an immediate check without waiting.

ExperimentalSetName

ExperimentalSetName(ctx context.Context, name string, params *SandboxExperimentalSetNameParams) error

ExperimentalSetName assigns a name to a running V2 Sandbox that was created without one, i.e. a Sandbox created via ExperimentalCreate. A name may only be set once, and only on a Sandbox that has never had one; afterwards the Sandbox can be looked up with ExperimentalFromName. Names must be unique within an App.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalSetNameParams)

SandboxExperimentalSetNameParams are options for Sandbox.ExperimentalSetName.

No configurable options.

ExperimentalSnapshot

ExperimentalSnapshot(ctx context.Context, params *SandboxExperimentalSnapshotParams) (*SandboxSnapshot, error)

ExperimentalSnapshot snapshots the filesystem and memory of the Sandbox.

Returns a SandboxSnapshot which can be restored into a new Sandbox with SandboxService.ExperimentalFromSnapshot. The Sandbox must have been created with SandboxCreateParams.ExperimentalEnableSnapshot set.

EXPERIMENTAL: the API is subject to change.

Parameters (SandboxExperimentalSnapshotParams)

SandboxExperimentalSnapshotParams are options for Sandbox.ExperimentalSnapshot.

No configurable options.

GetTags

GetTags(ctx context.Context, params *SandboxGetTagsParams) (map[string]string, error)

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

Parameters (SandboxGetTagsParams)

SandboxGetTagsParams are options for Sandbox.GetTags.

No configurable options.

MountImage

MountImage(ctx context.Context, path string, image *Image, params *SandboxMountImageParams) error

MountImage mounts an Image at a path in the Sandbox filesystem.

If image is nil, mounts an empty directory.

Parameters (SandboxMountImageParams)

SandboxMountImageParams are options for Sandbox.MountImage.

ExperimentalEncryptionKey ([]byte): ExperimentalEncryptionKey is a customer-supplied encryption key used to decrypt the image. Use the same key that encrypted the snapshot.

Poll

Poll(ctx context.Context, params *SandboxPollParams) (*int, error)

Poll checks if the Sandbox has finished running. Returns nil if the Sandbox is still running, else returns the exit code.

Parameters (SandboxPollParams)

SandboxPollParams are options for Sandbox.Poll.

No configurable options.

ReloadVolumes

ReloadVolumes(ctx context.Context, params *SandboxReloadVolumesParams) error

ReloadVolumes reloads all Volumes mounted in the Sandbox.

Blocks until the reload completes, or returns a TimeoutError on timeout (the reload may still complete in the background).

Parameters (SandboxReloadVolumesParams)

SandboxReloadVolumesParams are options for Sandbox.ReloadVolumes.

Timeout (time.Duration): Timeout bounds how long the call waits. Defaults to 55 seconds.

SetTags

SetTags(ctx context.Context, tags map[string]string, params *SandboxSetTagsParams) error

SetTags sets key-value tags on the Sandbox. Tags can be used to filter results in SandboxList.

Parameters (SandboxSetTagsParams)

SandboxSetTagsParams are options for Sandbox.SetTags.

No configurable options.

SnapshotDirectory

SnapshotDirectory(ctx context.Context, path string, params *SandboxSnapshotDirectoryParams) (*Image, error)

SnapshotDirectory snapshots and creates a new image from a directory in the running sandbox.

If params is nil, the resulting image is retained for 30 days as a hard cutoff measured from creation, and the call has a 55-second timeout. See SandboxSnapshotDirectoryParams for control over both.

Parameters (SandboxSnapshotDirectoryParams)

SandboxSnapshotDirectoryParams configures a Sandbox.SnapshotDirectory call.

Timeout (time.Duration): Timeout is the overall budget for the snapshot call. Zero means the default (55 seconds). If it elapses before a snapshot completes, a TimeoutError is returned.
TTL (time.Duration): TTL is the lifetime of the resulting image. Zero (or omitted) means use the default of 30 days, as a hard cutoff measured from creation. A positive value sets a custom lifetime; sub-second values are rejected. Pass NoExpiryTTL to retain the image indefinitely. See NoExpiryTTL.
ExperimentalEncryptionKey ([]byte): ExperimentalEncryptionKey is a customer-supplied encryption key used to encrypt the resulting snapshot. The same key is required when mounting the image. Modal does not persist the key.

SnapshotFilesystem

SnapshotFilesystem(ctx context.Context, params *SandboxSnapshotFilesystemParams) (*Image, error)

SnapshotFilesystem takes a snapshot of the Sandbox's filesystem. Returns an Image object which can be used to spawn a new Sandbox with the same filesystem.

If params is nil, the resulting image is retained for 30 days as a hard cutoff measured from creation, and the call has a 55-second timeout. See SandboxSnapshotFilesystemParams for control over both.

Parameters (SandboxSnapshotFilesystemParams)

SandboxSnapshotFilesystemParams configures a Sandbox.SnapshotFilesystem call.

Timeout (time.Duration): Timeout is the overall budget for the snapshot call. Zero means the default (55 seconds). If it elapses before a snapshot completes, a TimeoutError is returned.
TTL (time.Duration): TTL is the lifetime of the resulting image. Zero (or omitted) means use the default of 30 days, as a hard cutoff measured from creation. A positive value sets a custom lifetime; sub-second values are rejected. Pass NoExpiryTTL to retain the image indefinitely. See NoExpiryTTL.

Terminate

Terminate(ctx context.Context, params *SandboxTerminateParams) (int, error)

Terminate stops the Sandbox.

Parameters (SandboxTerminateParams)

SandboxTerminateParams are options for Terminate.

Wait (bool): Wait, when true, will wait for the Sandbox to terminate and return the exit code.

Tunnels

Tunnels(ctx context.Context, timeout time.Duration, params *SandboxTunnelsParams) (map[int]*Tunnel, error)

Tunnels gets Tunnel metadata for the Sandbox. Returns SandboxTimeoutError if the tunnels are not available after the timeout. Returns a map of Tunnel objects keyed by the container port.

Parameters (SandboxTunnelsParams)

SandboxTunnelsParams are options for Sandbox.Tunnels.

No configurable options.

UnmountImage

UnmountImage(ctx context.Context, path string, params *SandboxUnmountImageParams) error

UnmountImage removes an image mount from a path in the Sandbox filesystem.

Parameters (SandboxUnmountImageParams)

SandboxUnmountImageParams are options for Sandbox.UnmountImage.

No configurable options.

UpdateNetworkPolicy

UpdateNetworkPolicy(ctx context.Context, params *SandboxUpdateNetworkPolicyParams) error

UpdateNetworkPolicy updates the outbound network policy of a running Sandbox.

Established connections that the new policy no longer permits are terminated.

Parameters (SandboxUpdateNetworkPolicyParams)

SandboxUpdateNetworkPolicyParams are options for Sandbox.UpdateNetworkPolicy.

Each dimension is independent: a nil Allowlist leaves that dimension unchanged, while a non-nil value replaces it (an empty Entries blocks all egress; an allow-all entry such as "0.0.0.0/0" or "" allows everything).

Currently, both dimensions must be provided (the underlying transport does not yet support partial updates). This requirement will be relaxed in a future release.

OutboundCIDRAllowlist (*Allowlist)
OutboundDomainAllowlist (*Allowlist)

Wait

Wait(ctx context.Context, params *SandboxWaitParams) (int, error)

Wait blocks until the Sandbox exits, and returns its exit code.

Parameters (SandboxWaitParams)

SandboxWaitParams are options for Sandbox.Wait.

No configurable options.

WaitUntilReady

WaitUntilReady(ctx context.Context, timeout time.Duration, params *SandboxWaitUntilReadyParams) error

WaitUntilReady blocks until the Sandbox readiness probe reports ready.

Parameters (SandboxWaitUntilReadyParams)

SandboxWaitUntilReadyParams are options for Sandbox.WaitUntilReady.

No configurable options.

Sandbox.ExperimentalSidecars

ExperimentalSidecars provides operations on Sandbox Sidecar containers.

EXPERIMENTAL: the API is subject to change.

Create

Create(ctx context.Context, name string, image *Image, params *SidecarCreateParams) (*SidecarContainer, error)

Create starts a new sidecar container in the Sandbox. The Image must already be built by calling Image.Build before it's passed to Create.

Parameters (SidecarCreateParams)

SidecarCreateParams holds options for creating a sidecar container.

Command ([]string): Command to run in the sidecar container on startup.
Env (map[string]string): Env are environment variables to set in the sidecar container.
Secrets ([]*Secret): Secrets to inject into the sidecar container as environment variables.
Workdir (string): Workdir sets the working directory of the sidecar container.
OutboundCIDRAllowlist (*Allowlist): OutboundCIDRAllowlist restricts the sidecar's outbound traffic to these CIDRs. Independent of the main container; nil means all CIDRs are allowed. A non-nil allowlist with empty Entries blocks all external egress while preserving connectivity to the main container.
OutboundDomainAllowlist (*Allowlist): OutboundDomainAllowlist restricts the sidecar's outbound TLS connections (port 443) to these SNI domains. Supports wildcard prefixes (*.example.com). Independent of the main container.
PTY (bool): PTY sets whether to enable a PTY for the sidecar container.

Get

Get(ctx context.Context, name string, params *SidecarGetParams) (*SidecarContainer, error)

Get returns a sidecar container by name.

Parameters (SidecarGetParams)

SidecarGetParams holds options for retrieving a sidecar by name.

IncludeTerminated (bool)

List

List(ctx context.Context, params *SidecarListParams) ([]*SidecarContainer, error)

List returns all sidecar containers (not including the main container).

Parameters (SidecarListParams)

SidecarListParams holds options for listing sidecars.

IncludeTerminated (bool)

Sandbox.Filesystem

Filesystem provides high-level filesystem operations for this Sandbox.

CopyFromLocal

CopyFromLocal(ctx context.Context, localPath, remotePath string, params *SandboxFilesystemCopyFromLocalParams) error

CopyFromLocal copies a local file into the Sandbox.

remotePath must be an absolute path to a file in the Sandbox. Parent directories are created if needed. The remote file is overwritten if it already exists.

Returns SandboxFilesystemNotADirectoryError if a parent component of remotePath is not a directory, SandboxFilesystemIsADirectoryError if remotePath points to a directory, SandboxFilesystemPermissionError if write permission is denied, or an *os.PathError if localPath does not exist, is a directory, or cannot be read.

Parameters (SandboxFilesystemCopyFromLocalParams)

SandboxFilesystemCopyFromLocalParams holds optional parameters for SandboxFilesystem.CopyFromLocal.

No configurable options.

CopyToLocal

CopyToLocal(ctx context.Context, remotePath, localPath string, params *SandboxFilesystemCopyToLocalParams) (retErr error)

CopyToLocal copies a file from the Sandbox to a local path.

remotePath must be an absolute path to a file in the Sandbox. Parent directories for localPath are created if needed. The local file is overwritten if it already exists.

Returns SandboxFilesystemNotFoundError if the remote path does not exist, SandboxFilesystemIsADirectoryError if the remote path points to a directory, SandboxFilesystemFileTooLargeError if the file exceeds the read size limit, or SandboxFilesystemPermissionError if read permission is denied.

Parameters (SandboxFilesystemCopyToLocalParams)

SandboxFilesystemCopyToLocalParams holds optional parameters for SandboxFilesystem.CopyToLocal.

No configurable options.

ListFiles

ListFiles(ctx context.Context, remotePath string, params *SandboxFilesystemListFilesParams) ([]FileInfo, error)

ListFiles lists files and directories in a Sandbox directory.

remotePath must be an absolute path to a directory in the Sandbox. Returns a slice of FileInfo objects sorted by name.

Returns SandboxFilesystemNotFoundError if the path does not exist, SandboxFilesystemNotADirectoryError if the path is not a directory, or SandboxFilesystemPermissionError if read permission is denied.

Parameters (SandboxFilesystemListFilesParams)

SandboxFilesystemListFilesParams holds optional parameters for SandboxFilesystem.ListFiles.

No configurable options.

MakeDirectory

MakeDirectory(ctx context.Context, remotePath string, params *SandboxFilesystemMakeDirectoryParams) error

MakeDirectory creates a new directory in the Sandbox.

remotePath must be an absolute path in the Sandbox.

When params.CreateParents is true (the default when params is nil), any missing parent directories are created and the call is idempotent (succeeds if the directory already exists). When false, the immediate parent must already exist and the path must not already exist.

Returns SandboxFilesystemNotFoundError if the parent does not exist and CreateParents is false, SandboxFilesystemPathAlreadyExistsError if the path already exists, SandboxFilesystemNotADirectoryError if a path component is not a directory, SandboxFilesystemPermissionError if creation is not permitted, or InvalidError if the mount does not support this operation.

Parameters (SandboxFilesystemMakeDirectoryParams)

SandboxFilesystemMakeDirectoryParams holds optional parameters for SandboxFilesystem.MakeDirectory.

CreateParents (*bool): CreateParents controls whether missing parent directories are created automatically. Defaults to true when nil.

ReadBytes

ReadBytes(ctx context.Context, remotePath string, params *SandboxFilesystemReadParams) ([]byte, error)

ReadBytes reads a file from the Sandbox and returns its contents as bytes.

remotePath must be an absolute path to a file in the Sandbox.

Returns SandboxFilesystemNotFoundError if the path does not exist, SandboxFilesystemIsADirectoryError if the path points to a directory, SandboxFilesystemFileTooLargeError if the file exceeds the read size limit, or SandboxFilesystemPermissionError if read permission is denied.

Parameters (SandboxFilesystemReadParams)

SandboxFilesystemReadParams holds optional parameters for SandboxFilesystem.ReadBytes and SandboxFilesystem.ReadText.

No configurable options.

ReadText

ReadText(ctx context.Context, remotePath string, params *SandboxFilesystemReadParams) (string, error)

ReadText reads a file from the Sandbox and returns its contents as a UTF-8 string.

remotePath must be an absolute path to a file in the Sandbox.

Parameters (SandboxFilesystemReadParams)

SandboxFilesystemReadParams holds optional parameters for SandboxFilesystem.ReadBytes and SandboxFilesystem.ReadText.

No configurable options.

Remove

Remove(ctx context.Context, remotePath string, params *SandboxFilesystemRemoveParams) error

Remove a file or directory in the Sandbox.

remotePath must be an absolute path in the Sandbox. When remotePath is a directory and params.Recursive is false (the default when params is nil), it is removed only if empty. When Recursive is true, the directory and all its contents are removed. Recursive removal is not supported on all mounts.

Returns SandboxFilesystemNotFoundError if the path does not exist, SandboxFilesystemDirectoryNotEmptyError if Recursive is false and the directory is not empty, SandboxFilesystemPermissionError if removal is not permitted, or InvalidError if the mount does not support this operation.

Parameters (SandboxFilesystemRemoveParams)

SandboxFilesystemRemoveParams holds optional parameters for SandboxFilesystem.Remove.

Recursive (bool): Recurisve controls whether contens of a removed directory are recursively removed. Defaults to false when nil.

Stat

Stat(ctx context.Context, remotePath string, params *SandboxFilesystemStatParams) (*FileInfo, error)

Stat returns metadata for a single file, directory, or symlink in the Sandbox.

remotePath must be an absolute path in the Sandbox. If remotePath is a symlink, the returned FileInfo describes the symlink itself, not the target it points to.

Returns SandboxFilesystemNotFoundError if the path does not exist, SandboxFilesystemNotADirectoryError if a non-leaf component of the path is not a directory, or SandboxFilesystemPermissionError if a path component is not searchable.

Parameters (SandboxFilesystemStatParams)

SandboxFilesystemStatParams holds optional parameters for SandboxFilesystem.Stat.

No configurable options.

Watch

Watch(
	ctx context.Context,
	remotePath string,
	params *SandboxFilesystemWatchParams,
) (iter.Seq2[FileWatchEvent, error], error)

Watch a path in the Sandbox for filesystem changes.

remotePath must be an absolute path in the Sandbox. If it points to a file, events for that file are reported. If it points to a directory, events for entries directly inside it are reported. Set params.Recursive to also receive events for all nested subdirectories. If remotePath is a symlink, it is followed and events reference paths under the resolved target.

The returned iter.Seq2 yields FileWatchEvent values as changes occur, until the timeout elapses, the caller breaks from the range loop, ctx is cancelled, or the Sandbox is terminated. The remote watch process is not started until iteration begins, so a sequence that is never ranged over launches nothing.

Set params.Filter to restrict which event types are emitted. A nil filter permits all types; an empty slice suppresses all events.

A nil params.Timeout watches indefinitely, while a zero params.Timeout returns immediately without waiting for events. Otherwise the duration is rounded down to whole seconds, and when it elapses the iterator stops without returning an error.

Pass nil params for defaults (no filter, non-recursive, no timeout).

Returns SandboxFilesystemNotFoundError if remotePath does not exist, SandboxFilesystemPermissionError if watch access is denied, or InvalidError if the filesystem does not support watching.

Parameters (SandboxFilesystemWatchParams)

SandboxFilesystemWatchParams holds optional parameters for SandboxFilesystem.Watch.

Filter ([]FileWatchEventType)
Recursive (bool)
Timeout (*time.Duration): Timeout is the maximum duration to watch. A nil Timeout watches indefinitely, while a zero Timeout returns immediately without waiting for events. Durations are rounded-down to the nearest whole number of seconds.

WriteBytes

WriteBytes(ctx context.Context, data []byte, remotePath string, params *SandboxFilesystemWriteParams) error

WriteBytes writes binary content to a file in the Sandbox.

remotePath must be an absolute path to a file in the Sandbox. Parent directories are created if needed. The remote file is overwritten if it already exists.

Returns SandboxFilesystemNotADirectoryError if a parent component of remotePath is not a directory, SandboxFilesystemIsADirectoryError if remotePath points to a directory, or SandboxFilesystemPermissionError if write permission is denied.

Parameters (SandboxFilesystemWriteParams)

SandboxFilesystemWriteParams holds optional parameters for SandboxFilesystem.WriteBytes and SandboxFilesystem.WriteText.

No configurable options.

WriteText

WriteText(ctx context.Context, data string, remotePath string, params *SandboxFilesystemWriteParams) error

WriteText writes UTF-8 text to a file in the Sandbox.

remotePath must be an absolute path to a file in the Sandbox. Parent directories are created if needed. The remote file is overwritten if it already exists.

Returns SandboxFilesystemNotADirectoryError if a parent component of remotePath is not a directory, SandboxFilesystemIsADirectoryError if remotePath points to a directory, or SandboxFilesystemPermissionError if write permission is denied.

Parameters (SandboxFilesystemWriteParams)

SandboxFilesystemWriteParams holds optional parameters for SandboxFilesystem.WriteBytes and SandboxFilesystem.WriteText.

No configurable options.