sandbox

package
v0.47.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// SandboxWorkspace is the workspace directory inside the sandbox.
	SandboxWorkspace = "/sandbox/workspace" //nolint:gosec // not a credential
	// SandboxClaudeConfig is the Claude config directory inside the sandbox.
	SandboxClaudeConfig = "/sandbox/claude-config" //nolint:gosec // not a credential
	// SandboxCodexConfig is the codex config directory inside the sandbox.
	// Exported as CODEX_HOME. Outside the cloned repo tree, like
	// SandboxClaudeConfig and SandboxPiConfig, so repo contents cannot
	// pre-seed it and workspace resets do not clear it. It is not a
	// permission boundary: the agent process runs as the same user, so the
	// runner-written files under it (config.toml, hooks, the auth helper)
	// have to be checksum-guarded before every launch rather than trusted.
	// codex refuses to start when CODEX_HOME does not exist; the sandbox
	// image creates it (images/sandbox/Containerfile).
	SandboxCodexConfig = "/sandbox/codex-config" //nolint:gosec // not a credential
	// SandboxPiConfig is the pi config directory inside the sandbox.
	// Exported as PI_CODING_AGENT_DIR. Outside the cloned repo tree, like
	// SandboxClaudeConfig, so repo contents cannot pre-seed it and workspace
	// resets do not clear it. It is not a permission boundary: the agent
	// process runs as the same user, and pi loads extensions from
	// <dir>/extensions/, so Bootstrap must pass --no-extensions plus the
	// runner-supplied adapter explicitly.
	SandboxPiConfig = "/sandbox/pi-config" //nolint:gosec // not a credential
	// SandboxPiExtensionsDir holds runner-vetted pi extensions baked into the
	// sandbox image (images/sandbox/Containerfile), root-owned and outside
	// PI_CODING_AGENT_DIR so pi never auto-loads them; PiRuntime.Run passes
	// each one explicitly with -e.
	SandboxPiExtensionsDir = "/usr/local/share/pi-extensions"

	// KeepAliveCommand is the sandbox's canonical main process, started by
	// createOnce so the sandbox stays Ready between `sandbox exec` calls
	// (OpenShell 0.0.111+ makes a sandbox terminal once its main process
	// exits). It runs as the sandbox user, so anything that sweeps the
	// sandbox user's processes (runtime.killStrayProcesses) must spare
	// exactly this argv — keep the two in sync through this constant.
	KeepAliveCommand = "sleep infinity"

	DefaultMaxCreateAttempts = 3
)

Variables

View Source
var ErrProviderNotFound = errors.New("provider not found")

ErrProviderNotFound is returned by DeleteProvider when the gateway has no provider of that name — already gone, which callers treat as done.

View Source
var RetrySleepFn = time.Sleep

RetrySleepFn is the function called between retry attempts in CreateWithRetry. It defaults to time.Sleep. Override in tests to avoid real delays.

Functions

func CheckGateway added in v0.10.0

func CheckGateway() error

CheckGateway verifies that an openshell gateway is already running. The gateway must be started externally (e.g. in CI via the action.yml steps) before invoking fullsend run.

func CollectLogs added in v0.5.0

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. It retries up to DefaultMaxCreateAttempts times with exponential backoff, deleting the failed sandbox between attempts.

func CreateWithRetry added in v0.11.0

func CreateWithRetry(name string, providers []string, image, policy string, maxAttempts int, readyTimeoutOverride time.Duration) error

CreateWithRetry creates a sandbox, retrying up to maxAttempts times with exponential backoff on failure. Between attempts the failed sandbox is deleted to avoid name conflicts. If readyTimeoutOverride is positive, it overrides the default ready timeout.

func CredentialOnlyExpansionKeys added in v0.44.0

func CredentialOnlyExpansionKeys(keys ...string)

CredentialOnlyExpansionKeys marks environment variable names that provider credential values may expand but provider config values may not.

func Delete

func Delete(name string) error

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

func DeleteProvider added in v0.38.0

func DeleteProvider(name string) error

DeleteProvider deletes a named provider from the gateway. Run-scoped providers (e.g. openai-<suffix>) must be cleaned up regardless of --keep-sandbox so a live-token provider does not outlive the run (#6689). The 0.0.115 CLI reports a missing provider as "! Provider <name> not found" with exit 0; that and any non-zero "not found" variant surface as ErrProviderNotFound. A provider a sandbox still references cannot be deleted (FAILED_PRECONDITION) and is reported as an error.

func DenyExpansionKeys added in v0.38.0

func DenyExpansionKeys(keys ...string)

DenyExpansionKeys marks environment variable names that provider definitions may not expand.

func Download added in v0.8.0

func Download(sandboxName, remotePath, localPath string) error

Download copies a file or directory from a sandbox to the local machine. The localPath is always treated as a directory by openshell — for single-file downloads use DownloadFile instead.

func DownloadFile added in v0.8.0

func DownloadFile(sandboxName, remotePath, localPath string) error

DownloadFile copies a single file from a sandbox to a specific local path. openshell sandbox download always treats the destination as a directory, so this downloads to the parent directory and renames if the resulting filename differs from the desired local name.

func EffectivePolicy added in v0.38.0

func EffectivePolicy(ctx context.Context, name string) ([]byte, error)

EffectivePolicy returns the policy the sandbox is enforcing, as YAML, from `openshell policy get <name> --full` (the composed policy, including the gateway's provider entries). The CLI's metadata header is removed.

func EnableProvidersV2 added in v0.30.0

func EnableProvidersV2() error

EnableProvidersV2 enables the providers_v2_enabled setting globally in the openshell gateway. This is idempotent and can be called multiple times.

If OpenShell has dropped the setting (v2 is the sole/default mode), the unknown-key error is treated as success so a gateway bump does not abort the run.

func EnsureAvailable

func EnsureAvailable() error

EnsureAvailable checks that the openshell binary is in PATH.

func EnsureProvider

func EnsureProvider(ctx context.Context, name, providerType string, credentials, config map[string]string, fromURL bool) 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

Transient errors from concurrent runs on the same gateway are retried with short backoff: "unsupported provider type or profile" occurs when a concurrent ImportProfile process temporarily removes a profile during its delete+reimport cycle, and "provider was modified concurrently" when two runs update the same provider at once (the gateway rejects the stale resource_version; the update is idempotent, so retrying is safe).

func EnsureProviderLiteral added in v0.38.0

func EnsureProviderLiteral(ctx context.Context, name, providerType string, credentials map[string]string) error

EnsureProviderLiteral creates or updates a provider whose credential values were resolved in process — a token the runner exchanged or read from its own environment — and must be passed to openshell verbatim. Unlike EnsureProvider, values are never run through os.ExpandEnv: an opaque access token may legitimately contain `$`, and expanding it would mangle the credential silently (#6689). Values still travel by bare-key form in the child process environment, never on the command line.

func Exec added in v0.8.0

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

Exec runs a command inside a sandbox and returns stdout, stderr, and exit code. It uses context.Background() internally. Use ExecContext for cancellation support.

func ExecContext added in v0.18.0

func ExecContext(ctx context.Context, sandboxName, command string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)

ExecContext is like Exec but accepts a parent context for cancellation. Cancelling the parent (e.g. on SIGTERM) terminates the subprocess.

func ExecStreamReader added in v0.8.0

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

ExecStreamReader 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().

The parent context is used as the base for the timeout context, so cancelling the parent (e.g. on SIGTERM) terminates the subprocess. This allows CLI-level signal handling to propagate into long-running sandbox commands.

func ExtractOutputFiles

func ExtractOutputFiles(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 ForgetProfileCache added in v0.38.0

func ForgetProfileCache(id string)

ForgetProfileCache drops ImportProfile's content cache for a profile id so the next ImportProfile re-sends it.

func ImportProfile added in v0.31.0

func ImportProfile(ctx context.Context, id, profilePath string) error

ImportProfile imports a single openshell provider profile from a YAML file. The profile defines a provider type schema (credentials, endpoints).

Idempotency is hash-based: the function computes a SHA-256 digest of the profile file and compares it against a cached value in a temp file keyed by the profile id. When the hash matches (content unchanged), the import is skipped entirely. This makes parallel fullsend run invocations safe — only the first process imports, and subsequent processes see the cache hit.

Concurrency safety: the delete+reimport critical section is protected by a cross-process file lock (flock) keyed by profile id. This prevents the race where a concurrent process deletes a profile between another process's import and provider creation. Processes that block on the lock re-check the cache after acquiring it (double-check pattern) and skip the import if the winner already wrote the cache.

When content has changed (hash mismatch or no cache), the existing profile is deleted and reimported. The delete is best-effort: it fails while a provider still references the profile, and the reimport then fails with "already exists" even though the gateway may still hold the old content. So "already exists" is only treated as success if the gateway's exported content matches profilePath; otherwise an error is returned. See #7973.

func ImportProfileVerified added in v0.44.0

func ImportProfileVerified(ctx context.Context, id, profilePath string) error

ImportProfileVerified imports a provider profile after dropping any local content cache, then confirms the gateway lists it. ImportProfile trusts a hash in os.TempDir() and skips the send on a match; that cache can outlive the gateway it was written against (a per-job GitLab gateway, a restarted local daemon). Callers that must have the profile present — the generic URL-resolved import path and the OpenAI scaffold import — use this instead of ImportProfile alone. See #7218.

func ProfileExists added in v0.38.0

func ProfileExists(ctx context.Context, id string) (bool, error)

ProfileExists reports whether the gateway lists a provider profile with the given id (`openshell provider list-profiles`). ImportProfile trusts a local content cache, which goes stale when the gateway is recreated or the cache was written against another gateway; callers that must have the profile present check here and ForgetProfileCache before importing again.

func SafeDownload added in v0.8.0

func SafeDownload(sandboxName, remoteDir, localDir string) error

SafeDownload copies a directory from a sandbox to the local machine and then sanitizes the result by removing dangerous symlinks (absolute or repo-escaping) and .git/hooks/.

func SetProviderCredentialExpiry added in v0.38.0

func SetProviderCredentialExpiry(ctx context.Context, name, key string, expiresAt time.Time) error

SetProviderCredentialExpiry records when a provider credential stops being valid (`openshell provider update --credential-expires-at`). The gateway then fails placeholder resolution closed after that instant, which is the backstop for a run-scoped provider whose runner died before the deferred DeleteProvider ran (#6689).

func StripPolicyHeader added in v0.38.0

func StripPolicyHeader(out []byte) []byte

StripPolicyHeader removes the `Version:/Hash:/Status:` metadata block that `openshell policy get` prints before the first `---` document marker. Output without a marker is returned unchanged.

func UpdateProviderLiteral added in v0.38.0

func UpdateProviderLiteral(ctx context.Context, name string, credentials map[string]string) error

UpdateProviderLiteral replaces the credential values of an existing provider with in-process values (no expansion), the refresh counterpart of EnsureProviderLiteral. OpenShell propagates the new generation to running sandboxes within seconds; old placeholders keep resolving by credential key.

func UpdateProviderLiteralWithExpiry added in v0.38.0

func UpdateProviderLiteralWithExpiry(ctx context.Context, name string, credentials map[string]string, expiresAt time.Time) error

UpdateProviderLiteralWithExpiry replaces credential values and records their expiry in one `provider update`, so the new value never carries the old expiry between two calls.

func Upload added in v0.8.0

func Upload(sandboxName, localPath, remotePath string) error

Upload copies a local file or directory into a sandbox. Directories, and symlinks that resolve to a directory, are transferred via UploadDir's tar archive so that directory contents — including symlinked sources such as cache-resolved skill or plugin paths (see CacheNamedSymlink) — survive the transfer. openshell's own "sandbox upload" archives only the symlink entry when the source itself is a symlink, silently dropping the target's content; delegating to the tar path here closes that gap for every caller instead of relying on each one to remember to call UploadDir directly. Regular files are uploaded directly, unchanged from before. A symlink that resolves to a regular file is resolved to its real path before upload, so correctness doesn't depend on whether openshell's own "sandbox upload" dereferences a symlink argument. A symlink whose target is missing is still routed to the tar path so it fails loudly (tar's -C can't chdir into it) rather than silently uploading a content-less link.

func UploadDir added in v0.8.6

func UploadDir(sandboxName, localPath, remotePath string, excludes ...string) error

UploadDir uploads the contents of a local directory into a sandbox, preserving symlinks. It builds a local tar archive (tar preserves symlinks by default), uploads it, and extracts it in the sandbox at remotePath. localPath itself may be a symlink to a directory — tar's -C follows it via chdir(2) before archiving. Upload delegates here automatically whenever its source is a directory or a symlink; call this directly only when you already know the exact destination directory you want.

remotePath is fully owned and replaced by this call: any existing content there is removed before extraction, so two uploads that resolve to the same remotePath overwrite deterministically rather than merging files from both. Do not point two different, unrelated sources at the same remotePath expecting their content to coexist.

func UploadFile added in v0.16.0

func UploadFile(sandboxName, localPath, remotePath string) error

UploadFile copies a single local file to an exact destination filename. OpenShell upload treats its destination as a directory, so stage the file separately and then move it into place. This supports existing files and preserves neighboring files; directory destinations are rejected.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL