sandbox

Documentation

Index

• Constants
• func CollectLogs(name, source string) (string, error)
• func Create(name string, providers []string, image, policy string) error
• func Delete(name string) error
• func EnsureAvailable() error
• func EnsureGateway() error
• func EnsureProvider(name, providerType string, credentials, config map[string]string) error
• func ExtractOutputFiles(sshConfigPath, sandboxName, remoteDir, localDir string) ([]string, error)
• func ExtractTranscripts(sshConfigPath, sandboxName, agentName, outputDir string) error
• func GetSSHConfig(name string) (string, error)
• func RsyncFrom(sshConfigPath, sandboxName, remoteDir, localDir string) error
• func SCP(sshConfigPath, sandboxName, localPath, remotePath string) error
• func SCPFrom(sshConfigPath, sandboxName, remotePath, localPath string) error
• func SSH(sshConfigPath, sandboxName, command string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)
• func SSHStream(sshConfigPath, sandboxName, command string, timeout time.Duration, ...) (int, error)
• func SSHStreamReader(sshConfigPath, sandboxName, command string, timeout time.Duration, ...) (io.ReadCloser, *exec.Cmd, context.CancelFunc, error)

Constants

const (
	// SandboxWorkspace is the workspace directory inside the sandbox.
	SandboxWorkspace = "/tmp/workspace" //nolint:gosec // not a credential
	// SandboxClaudeConfig is the Claude config directory inside the sandbox.
	SandboxClaudeConfig = "/tmp/claude-config" //nolint:gosec // not a credential

)

Functions

func CollectLogs

func CollectLogs(name, source string) (string, error)

CollectLogs runs `openshell logs <name> --source <source> -n 0` and returns the log output. The -n 0 flag requests all available log lines (no limit). This is a host-side command that talks to the gateway — no SSH needed.

func Create

func Create(name string, providers []string, image, policy string) error

Create creates a persistent OpenShell sandbox and waits for it to be ready. If providers are given, they are passed as --provider flags. If image is non-empty, it is passed as --from to start the sandbox from a container image. If policy is non-empty, it is applied at creation time via --policy.

func Delete

func Delete(name string) error

Delete deletes a sandbox, returning any error for the caller to log.

func EnsureAvailable

func EnsureAvailable() error

EnsureAvailable checks that the openshell binary is in PATH.

func EnsureGateway

func EnsureGateway() error

EnsureGateway starts a local gateway if none is active. It is idempotent — if a gateway is already running the command is a no-op.

func EnsureProvider

func EnsureProvider(name, providerType string, credentials, config map[string]string) error

EnsureProvider creates or updates a provider on the gateway. Credential values may contain ${VAR} references which are expanded from the host environment before being passed to openshell.

Credentials use the bare-key form (--credential KEY) so that secret values never appear on the process command line. The expanded values are injected into the child process environment, where openshell reads them directly. See https://docs.nvidia.com/openshell/latest/sandboxes/manage-providers#bare-key-form

func ExtractOutputFiles

func ExtractOutputFiles(sshConfigPath, sandboxName, remoteDir, localDir string) ([]string, error)

ExtractOutputFiles copies all files under a remote directory in the sandbox to a local output directory, preserving relative paths.

func ExtractTranscripts

func ExtractTranscripts(sshConfigPath, sandboxName, agentName, outputDir string) error

ExtractTranscripts copies Claude transcript files (.jsonl) from the sandbox to a local output directory.

func GetSSHConfig

func GetSSHConfig(name string) (string, error)

GetSSHConfig retrieves the SSH config for a sandbox.

func RsyncFrom

func RsyncFrom(sshConfigPath, sandboxName, remoteDir, localDir string) error

RsyncFrom copies a directory from a sandbox to the local machine using rsync with safety flags: symlinks are skipped (--no-links) and .git/hooks/ is excluded to prevent a compromised sandbox from injecting executable content into the host repo. Requires rsync on both host and sandbox.

func SCP

func SCP(sshConfigPath, sandboxName, localPath, remotePath string) error

SCP copies a local file or directory into a sandbox.

func SCPFrom

func SCPFrom(sshConfigPath, sandboxName, remotePath, localPath string) error

SCPFrom copies a file or directory from a sandbox to the local machine.

func SSH

func SSH(sshConfigPath, sandboxName, command string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)

SSH runs a command inside a sandbox and returns stdout, stderr, and exit code.

func SSHStream

func SSHStream(sshConfigPath, sandboxName, command string, timeout time.Duration, stdoutW, stderrW *os.File) (int, error)

SSHStream runs a command inside a sandbox, streaming output to the given writers.

func SSHStreamReader

func SSHStreamReader(sshConfigPath, sandboxName, command string, timeout time.Duration, stderrW io.Writer) (io.ReadCloser, *exec.Cmd, context.CancelFunc, error)

SSHStreamReader runs a command inside a sandbox, returning an io.ReadCloser for stdout so the caller can parse structured output. Stderr is forwarded to the given writer. The caller must read stdout to completion, then call cmd.Wait().