openshell-sandbox

openshell-sandbox --bootstrap PATH [--log-level LEVEL]openshell-sandbox copy-self DESTopenshell-sandbox bootstrapopenshell-sandbox seed-workspaceopenshell-sandbox capability-probe

openshell-sandbox is the capability-free isolation boundary that NVIDIA OpenShell places inside each sandbox. Compute drivers start it as PID 1 in the workload container or microVM. It is not the openshell CLI. openshell-supervisor stays on the host (or in a companion container), holds gateway credentials, and evaluates policy. This process never receives a gateway JWT.The default invocation is Linux-only. It reads a protected one-use bootstrap file (--bootstrap), actively qualifies the kernel primitives the boundary needs (zero capabilities, no-new-privileges, Landlock, seccomp notifications, loopback socket confinement, DNS relay bind), then runs the workload behind that boundary. The sandbox consumes and unlinks the bootstrap material before workload code starts.Init containers invoke the named helpers instead of `sh` or `cp`. copy-self writes this executable to a destination path. bootstrap stages a Kubernetes projected Secret into private tmpfs. seed-workspace copies the agent image workspace once. capability-probe prints the same qualification report the default path requires, as JSON, and does not start a workload.

These flags apply to the default boundary path. Named helpers above parse argv themselves and reject clap flags.--bootstrap PATH

Required. Protected one-use bootstrap configuration staged by the compute driver.

Console filter: trace, debug, info, warn (default), or error. Also read from OPENSHELL_LOG_LEVEL. Ignored when a tracing default filter is already set in the environment.

Print the crate version and exit.

/.openshell/bootstrap-input

Kubernetes projected Secret for bootstrap. Expected files: boundary.json, tls.crt, tls.key.

Destination of the staged sandbox binary after bootstrap (mode 0500).

Private bootstrap bundle after bootstrap. The long-lived sandbox consumes and unlinks it.

Agent-image workspace copied by seed-workspace.

Persistent workspace volume. seed-workspace writes .openshell-initialized here after a successful copy.

Default for --log-level on the boundary path.

copy-self DEST

Copy the running executable to DEST and set mode 0755 on Unix. If DEST is a directory, the source file name is used inside it. Parent directories are created as needed. Init containers use this so they do not depend on `cp`.

Kubernetes init helper. Linux only. No extra arguments. Must run as a non-root UID and GID. Copies this binary to /.openshell/runtime/openshell-sandbox (mode 0500) and copies boundary.json, tls.crt, and tls.key from /.openshell/bootstrap-input into /.openshell/state/bootstrap (directory mode 0700, files 0600). The projected Secret stays mounted only in the init container. Extra arguments are an error.

Kubernetes init helper. Linux only. No extra arguments. Copies /sandbox into /mnt/openshell-workspace unless .openshell-initialized already exists there. Directories are created mode 0700. Regular files keep an execute bit when the source had one, otherwise 0600. Symlinks are preserved. Extra arguments are an error.

Linux only. Qualify the current process as a capability-free sandbox and print one JSON object (`qualified`, UID/GID, Landlock ABI, seccomp and socket probes). Requires a non-root UID and GID, all capability sets zero, no_new_privs=1, and net.ipv4.ip_unprivileged_port_start=0. Does not start a workload.

The default path, bootstrap, seed-workspace, and capability-probe require Linux. On other platforms the binary reports that openshell-sandbox requires Linux, except copy-self, which still copies the executable.Do not run bootstrap or capability-probe as root. Both abort when the effective UID or GID is 0.The compute driver normally starts this process. Operators copy trusted bytes from the sandbox-runtime image rather than from an untrusted workload image.Internal probe helpers (capability-probe-launch, capability-socket-child, capability-landlock-child, launch-capability-free) exist for conformance tests. They are not operator commands.

openshell(1), openshell-gateway(1), openshell-supervisor(1), openshell-prover(1), openshell-seccomp-perf(1), openshell-vm-init(1), openshell-driver-docker(1), openshell-driver-podman(1), openshell-driver-kubernetes(1), openshell-driver-vm(1)

Source code · Homepage · Documentation