SidecarContainer

SidecarContainer is a handle to a sidecar container running in a Sandbox.

type SidecarContainer struct {
	ContainerID   string             // ContainerID is the fully qualified container ID.
	ContainerName string             // ContainerName is the logical name of the container within the Sandbox.
	Filesystem    *SandboxFilesystem // Filesystem provides high-level filesystem operations for this container.
}

Exec

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

Exec runs a command in the sidecar container and returns the process handle.

Parameters (SidecarExecParams)

SidecarExecParams holds options for [SidecarContainer.Exec].

• 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.

Poll

Poll(ctx context.Context, _ *SidecarPollParams) (*int, error)

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

Parameters (SidecarPollParams)

SidecarPollParams holds options for [SidecarContainer.Poll].

No configurable options.

Terminate

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

Terminate stops the sidecar container.

The returned exit code is only meaningful when Wait is true.

Parameters (SidecarTerminateParams)

SidecarTerminateParams holds options for [SidecarContainer.Terminate].

• Wait (bool): Wait, when true, will wait for the sidecar container to terminate.

Wait

Wait(ctx context.Context, _ *SidecarWaitParams) (int, error)

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

Parameters (SidecarWaitParams)

SidecarWaitParams holds options for [SidecarContainer.Wait].

No configurable options.

SidecarContainer.Filesystem

Filesystem provides high-level filesystem operations for this container.

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.

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.

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.