OpenShell Files

OpenShell v0.1.5

Quick install

:::bash
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.1.5 sh

Upgrade notes

• Supervisor OCSF log files are now named openshell-ocsf.YYYY-MM-DD.jsonl instead of .log, so update any collector patterns from openshell-ocsf.*.log to openshell-ocsf.*.jsonl. Old .log files are not migrated and may be cleaned up, so collect any history you need before upgrading. #4263
• On Kubernetes, sandbox templates that set pod annotations or labels are now rejected unless an operator allowlists those keys with the new allowed_pod_annotations and allowed_pod_labels settings in [openshell.drivers.kubernetes]. This affects direct API or SDK callers that set SandboxTemplate.labels or SandboxTemplate.annotations, including recovery of timed-out sandboxes; the openshell CLI and --label metadata labels are unaffected. #4497
• The gateway now rejects annotation keys with the reserved internal.openshell.ai/ prefix on CreateSandbox and UpdateConfig. #4626
• The Go SDK's SandboxInterface.Create() and CreateFromTemplate() now take functional options such as WithLabels(), WithAnnotations(), and WithServiceExposures() instead of a positional labels argument and the removed CreateOptions struct. Update call sites to the new options. #3198
• External compute drivers that provision openshell-sandbox must update their bootstrap descriptor from outer_fence to provisioning_evidence; drivers that use their own isolation backend are unaffected. This release also publishes the versioned Sandbox Protocol for independently implemented backends. #3898
• The snap no longer enables the user gateway service for every user; the install script enables it only for the user who ran it. After a direct snap install, or if an older snap revision enabled it globally, run sudo systemctl disable --global snap.openshell.user-gateway.service once and then systemctl --user enable --now snap.openshell.user-gateway.service from the single account that should run the gateway. #4615

Bug fixes

• Hostname-based network policy is now bound to supervisor-controlled DNS, while sandbox host aliases still require explicit IP validation or a trusted gateway pin. #4602
• Stopping a MicroVM sandbox no longer discards recent writes, because the guest now flushes its filesystem before shutdown. #4195
• You can now stop a sandbox stuck in Error after a startup failure and start it again, without deleting it or its persistent workspace. #4231
• OTLP export with gzip compression or an https:// endpoint no longer fails at startup. #4399
• Podman deployments can trust a private CA for inspected HTTPS egress with the new additional_ca_bundle setting, without rebuilding the supervisor image. The CA is trusted for all destinations by both the supervisor and the workload. #3996
• The Helm chart now installs in namespaces that enforce the Restricted Pod Security standard, and the certgen hook security context can be overridden with pkiInitJob.securityContext. #3340
• GitHub App OAuth token refresh now works, because the gateway asks for a JSON response. #4530
• A deleted provider that sandboxes still reference no longer blocks gateway startup; the gateway logs a warning instead. #4661
• In Kubernetes operator workspace mode, labeled workspaces are no longer rejected with PermissionDenied right after gateway startup. #4527
• Kubernetes PVC mounts can no longer overlap driver-managed runtime and control paths. #4522
• The sandbox network broker now denies operations when it cannot verify a descriptor, instead of falling back to native handling. #4494
• VM guest startup is hardened so the packaged sandbox keeps its expected executable identity. #4539
• Seccomp notification probe failures now report the actual kernel error instead of a generic "notification launcher disappeared" message. #4051
• e2fsprogs preflight checks no longer fail when Linux briefly reports a newly installed executable as busy. #4315
• Middleware now sees http and ws for plaintext requests in a tunnel instead of https and wss. #4397
• L7 OCSF HTTP events now report https for TLS-terminated requests. #4684
• OCSF events now include the required device.os.type_id, so they validate against the OCSF 1.8 schema. #4677
• Mutation-lock metrics from the gateway's startup reconciliation are no longer dropped. #4524
• Updated rustls to 0.23.46 to address RUSTSEC-2026-0346 through RUSTSEC-2026-0349. #4568
• The RPM-installed Python SDK now imports correctly, and its stubs can be generated with older protoc versions. #4439
• Builds now honor the PROTOC environment variable, so distribution builds can use their system protobuf compiler. #4441

Features

• Supervisors can now receive configuration changes pushed over their gateway session by setting config_delivery_mode = "push", so policy and setting changes reach sandboxes in about 100 ms instead of up to 10 seconds. Polling remains the default in this release. #4320
• The gateway and sandbox supervisors can export OCSF events as OTLP log records when [openshell.gateway.otlp.ocsf] sets enabled = true, and you can now send traces and OCSF events to different OTLP endpoints. Existing configurations with only [openshell.gateway.otlp] endpoint behave as before. #4500, #4545
• The gateway now emits OCSF Authentication events for rejected requests, including the authentication mechanism, a reason category, the peer address, and the request ID. #4632, #4655, #4673
• MicroVM sandboxes can mount host directories through virtiofs after an operator sets enable_bind_mounts = true in [openshell.drivers.vm]. You can use up to 3 mounts on x86_64 or 32 on aarch64, and QEMU-backed and GPU launches do not support mounts. #3463
• The Docker supervisor can now use bridge networking with the new supervisor_network_mode setting; host networking remains the default. #4016
• openshell sandbox create now accepts repeatable --annotation KEY=VALUE flags. #4325
• openshell sandbox create adds --env-from KEY[=ENVVAR] to set sandbox environment variables from the CLI's environment without putting values on the command line. The OPENSHELL_OCSF_JSON=1 gateway audit sink is also now available on all platforms. #4106
• When a dynamic token grant is refused, sandbox reads now show a bounded cause and recovery action, while the workload gets an HTTP 502 with an x-openshell-request-id it can share. #4427
• The Helm chart adds server.dataStorageSize and server.dataStorageClass to configure the gateway data PVC. #3854
• Gateway mutation locks are now scoped per workspace and sandbox, with bounded waits, so bursts of supervisor reconnects no longer queue behind a single fleet-wide lock. #4147

Other

• Added documentation for the Port Forwarding IPv6 loopback example, sandbox create size limits, Kubernetes managed workspace setup, and new Observability overview and Traces pages. #2449, #4447, #4622, #4560
• Removed the grpcurl walkthrough from the README. #4585
• Added an RFC that proposes a sandbox service exposure architecture. #4267
• Introduced a backend-neutral cryptography interface while keeping AWS-LC as the production backend and preserving existing credential formats and TLS defaults. #3351
• The CLI and gateway no longer link ring alongside AWS-LC. #4468
• Sped up gateway server builds by removing async_trait from internal traits. #4619
• Updated development and build dependencies, including setuptools, pytest, TypeScript SDK test dependencies, and GitHub Actions, and temporarily accepted build-only zip advisories. #4711, #4713, #4712, #4710, #2625, #3002, #4552
• Reworked the release pipeline to separate prerelease publication from qualification, promote qualified prereleases to stable, generate PR-based release notes, retry Helm chart pushes, and improve Slack notifications. #4419, #4420, #4611, #4654, #4747, #4578, #4605, #4719
• Improved CI reliability and coverage, including restored default E2E coverage, Kubernetes conformance readiness, paginated required-gate lookups, Determinate Nix setup, and stricter compatibility-review risk acceptance. #4424, #4676, #4663, #4593, #4601, #4595
• Added and stabilized tests for OCI image identities, Landlock descriptor limits, CLI port forwarding, and Kubernetes 1.29 conformance. #4521, #4457, #4570, #4463
• tmachine can now build local Debian and RPM artifacts from a checkout. #4598, #4651
• Updated contributor tooling with triage duty workflows, explicit frozen labels for stale issues, and earlier Gator sandbox name validation. #3082, #4534, #4660