Documentation
¶
Index ¶
- Constants
- func CheckGateway() error
- func CollectLogs(name, source string) (string, error)
- func Create(name string, providers []string, image, policy string) error
- func CreateWithRetry(name string, providers []string, image, policy string, maxAttempts int, ...) error
- func Delete(name string) error
- func Download(sandboxName, remotePath, localPath string) error
- func DownloadFile(sandboxName, remotePath, localPath string) error
- func EnableProvidersV2() error
- func EnsureAvailable() error
- func EnsureProvider(ctx context.Context, name, providerType string, ...) error
- func Exec(sandboxName, command string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)
- func ExecContext(ctx context.Context, sandboxName, command string, timeout time.Duration) (stdout, stderr string, exitCode int, err error)
- func ExecStreamReader(ctx context.Context, sandboxName, command string, timeout time.Duration, ...) (io.ReadCloser, *exec.Cmd, context.CancelFunc, error)
- func ExtractOutputFiles(sandboxName, remoteDir, localDir string) ([]string, error)
- func ImportProfile(ctx context.Context, id, profilePath string) error
- func ImportProfiles(dir string) error
- func SafeDownload(sandboxName, remoteDir, localDir string) error
- func Upload(sandboxName, localPath, remotePath string) error
- func UploadDir(sandboxName, localPath, remotePath string) error
- func UploadFile(sandboxName, localPath, remotePath string) error
Constants ¶
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 DefaultMaxCreateAttempts = 3 )
Variables ¶
This section is empty.
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
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 ¶
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 Download ¶ added in v0.8.0
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
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 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.
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
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 ¶
ExtractOutputFiles copies all files under a remote directory in the sandbox to a local output directory, preserving relative paths.
func ImportProfile ¶ added in v0.31.0
ImportProfile imports a single openshell provider profile from a YAML file. The profile defines a provider type schema (credentials, endpoints). To ensure content changes propagate on persistent gateways, the profile is deleted by id before re-importing (mirroring the ImportProfiles flow).
func ImportProfiles ¶ added in v0.30.0
ImportProfiles imports provider profile YAMLs from a directory into the gateway via openshell provider profile import. If the directory does not exist, this is a no-op. This allows callers to import profiles from optional directories without checking existence first.
Idempotency is hash-based: the function computes a SHA-256 digest of the profile directory contents and compares it against a cached value in a temp file. When the hash matches (profiles 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.
When profiles have changed (hash mismatch or no cache), existing profiles are deleted and reimported. If the reimport fails because a parallel process already imported them, the error is treated as success.
func SafeDownload ¶ added in v0.8.0
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 Upload ¶ added in v0.8.0
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
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
UploadFile copies a single local file into a sandbox at a specific remote path. It checks if the remotePath is a file and if it is not it tries to fix it. This is because of `openshell sandbox upload` in a git environment. Check https://github.com/NVIDIA/OpenShell/issues/1740 for more information. When that gets addressed, this can go away.
Types ¶
This section is empty.
Source Files