NVIDIA/OpenShell
70.9
Strong · 27 October 2026
566k
lines of production code
Rust
primary language
4
measurements over time
What this system is
OpenShell is a secure sandboxing platform that manages isolated execution environments for AI agents and workloads across diverse compute backends, including Docker, Podman, Kubernetes, VMs, and Windows MXC. It enforces strict network and filesystem policies through a formal verification engine and a dynamic policy advisor, while providing comprehensive observability via standardized OCSF audit logs. The system offers a unified gateway for lifecycle management, credential injection, and multi-language SDKs, ensuring that untrusted code runs with capability-free isolation and verifiable identity.
Features
Add Dockerfile for external Kubernetes gateway
A new Dockerfile has been added to build the external Kubernetes gateway container. This image packages the prebuilt gateway and Kubernetes driver binaries, configures environment variables for the Kubernetes compute driver and sandbox runtime, and exposes port 8080 for the gateway service.
e2e/docker · high confidence
Add GPU workload test images and manifest-driven validation
The e2e/gpu directory now includes Dockerfiles and scripts for three GPU workload images—smoke-pass, smoke-fail, and cuda-basic—along with a README detailing their contract and build process. These images are used by a new manifest-driven validation approach, where a local \workloads.yaml\ manifest defines the image, command, and expected outcome for each workload, allowing the e2e suite to run GPU tests against OpenShell sandboxes using explicit manifest entries rather than relying on external community image dependencies.
e2e/gpu · high confidence
Add Nix package definitions for VM runtime and build dependencies
New Nix package files have been added to support the VM runtime and its dependencies. The vm-runtime.nix package fetches and extracts platform-specific artifacts (libkrun, umoci) for x86\_64-linux, aarch64-linux, and aarch64-darwin, compressing them with zstd. The aws-lc.nix package configures the AWS-LC library with Rust bindings and specific target settings. The z3.nix package overrides the Z3 solver to disable Python bindings and shared library building.
nix/pkgs · high confidence
Add OCSF v1.8.0 enum types for structured event data
The \openshell-ocsf\ crate now includes a comprehensive set of strongly-typed enums for Open Cybersecurity Schema Framework (OCSF) v1.8.0 fields. This adds definitions for action, activity, authentication, device type, disposition, HTTP method, launch type, security level, confidence, risk level, severity, status, and state. These enums provide consistent integer IDs and human-readable labels, enabling structured serialization of OCSF events and ensuring that activity contexts (such as HTTP methods mapping to network or detection activities) are handled uniformly across the system.
crates/openshell-ocsf/src/enums · high confidence
Add SBOM license resolution and CSV export tooling
New scripts have been added to the deploy/sbom directory to enhance Software Bill of Materials (SBOM) management. The \resolve\_licenses.py\ tool automatically detects missing or hash-based (sha256) license identifiers in CycloneDX JSON files and resolves them by querying public registries (crates.io, npm, PyPI) and applying a built-in map of known licenses for specific Go modules and system packages. Additionally, \sbom\_to\_csv.py\ provides a new capability to convert these CycloneDX JSON SBOMs into CSV format, extracting key component details like name, version, type, purl, and resolved licenses for easier downstream analysis.
deploy/sbom · high confidence
Add SPIFFE-backed token grant demo
The \examples/spiffe-token-grant-demo\ directory now includes a complete example demonstrating dynamic token grants using SPIFFE JWT-SVIDs. This demo deploys three in-cluster workloads (\token-issuer\, \alpha\, and \beta\) and provides a \demo.sh\ script to validate the flow where a sandbox supervisor fetches a JWT-SVID, exchanges it for a short-lived access token, and injects it into outbound requests. The example includes Kubernetes manifests (\k8s/\), Node.js scripts for the issuer and protected services, and a \provider-profile.yaml\ configuration for the OpenShell provider.
examples/spiffe-token-grant-demo · high confidence
Add built-in Google Cloud and Vertex AI provider plugins
Users can now configure Google Cloud and Vertex AI as built-in inference providers. The new \google\_cloud.rs\ and \vertex.rs\ modules implement the \ProviderPlugin\ interface, automatically injecting necessary environment variables (such as project IDs, regions, and service account emails) into the sandbox environment while respecting existing values and skipping empty configurations. This enables seamless integration with Google Cloud services without manual environment setup.
crates/openshell-providers/src/providers · high confidence
Add custom footer component for Fern documentation
A new \CustomFooter\ component has been added to the Fern documentation site, replacing the default footer with a branded NVIDIA footer. This component displays the NVIDIA logo (with light and dark mode variants), a "Built with Fern" badge, and standard legal links including Privacy Policy, Terms of Service, and Accessibility, ensuring the documentation footer matches NVIDIA's branding and legal requirements.
fern/components · high confidence
Add example supervisor middleware content guard
Introduces a new example supervisor middleware service that inspects HTTP request and response bodies as well as WebSocket text messages for case-sensitive literal terms. The service operates in redact mode (replacing matches with a configurable string, defaulting to \[FILTERED\]) or deny mode (blocking delivery with a 403 response). It is provided as a research preview with a smoke test script, a sample policy, and an upstream fixture to demonstrate the middleware integration.
examples/supervisor-middleware-content-guard · high confidence
Add local inference example for NVIDIA API Catalog
Added a new example in \examples/local-inference\ that demonstrates calling the NVIDIA API Catalog via its native OpenAI-compatible endpoint. The example includes a Python client (\inference.py\) supporting both streaming and non-streaming requests, a provider profile (\nvidia-inference.yaml\) defining endpoint credentials and network policies, and a sandbox policy (\sandbox-policy.yaml\) allowing PyPI access. This provides users with a reference implementation for configuring local inference workloads with explicit policy-based credential injection.
examples/local-inference · high confidence
Add multi-agent notepad demo
Introduces a new example in \examples/multi-agent-notepad\ that demonstrates running multiple Codex coding agents in parallel OpenShell sandboxes, using a GitHub repository as a durable, concurrent shared notepad. The demo includes orchestration scripts (\demo.sh\, \runner.sh\), network and filesystem policies (\policy.template.yaml\), and agent prompts to illustrate a map/reduce pattern where worker agents write individual notes and a synthesis agent produces a summary, highlighting features like provider-backed credentials and scoped network policies.
examples/multi-agent-notepad · high confidence
Added fake broadcaster for testing watch functionality
The Go SDK now includes a fake implementation of the watch broadcaster in the \openshell/v1/fake\ package. This component allows developers to simulate event broadcasting and watching behavior in tests, supporting optional filtering by resource name and safe concurrent access to watcher channels.
github.com/NVIDIA/OpenShell/sdk/go · high confidence
Custom kernel configuration for OpenShell VM sandboxes
A new kernel configuration fragment (openshell.kconfig) is introduced to tailor the VM kernel for capability-free sandboxes. This configuration enables ext4 root disk support, cgroups for resource limits, and enforces security via Landlock, seccomp, and other LSMs, while disabling heavy hardening features like init-on-free to maintain performance.
crates/openshell-driver-vm/runtime/kernel · high confidence
Docker driver now enforces the shared authenticated boundary protocol
The Docker compute driver has been refactored to implement the new isolation backend, replacing the previous standalone model with a shared authenticated boundary. This change introduces strict outer-fence guarantees—such as default-deny egress and controller-loss fail-closed behavior—by binding container placement, protected sockets, and immutable OCI resource claims (container ID, image identity, and GPU claims) to a unified boundary configuration. Users benefit from stronger security isolation where sandbox network egress is strictly controlled and identity is cryptographically verified against the gateway, while the driver now exposes its capabilities and lifecycle through the standardized \openshell-isolation-interface\ contract.
crates/openshell-driver-docker/src · high confidence
Go SDK gateway package for CLI-managed gateway discovery and authentication
The Go SDK now includes a gateway package that automatically discovers gateways configured by the OpenShell Rust CLI in user ($XDG\_CONFIG\_HOME/openshell/gateways) and system (/etc/openshell/gateways) directories. It parses on-disk metadata.json files to resolve endpoints and authentication modes (none, plaintext, Cloudflare JWT, OIDC, and mTLS), handling lazy token loading for edge and OIDC tokens so that client construction succeeds even if tokens are missing. The package provides typed errors for configuration and token failures, validates gateway names for cross-platform safety, and allows callers to override authentication, TLS, timeouts, and retry policies via functional options.
sdk/go/openshell/v1/gateway · high confidence
Go SDK v1 introduces comprehensive authentication, client, and edge-proxy support
The Go SDK v1 now provides a complete client library for interacting with OpenShell gateways, featuring a unified \Client\ that exposes sub-clients for sandboxes, providers, exec, files, and more. Authentication is handled via pluggable \AuthProvider\ implementations, including static tokens, no-auth, and automatic OAuth2 token refresh with single-flight deduplication and exponential backoff. Users can also wrap any auth provider with extra headers for edge proxies, with a built-in \CloudflareAccess\ helper and a \TunnelProxy\ for bridging gRPC over WebSockets through HTTP/1.1-only edge proxies. Also in this area: Sandbox suspend and resume lifecycle support; Stable credential placeholders for provider profiles.
sdk/go/openshell/v1, sdk/go/openshell/v1/internal/converter, sdk/go/openshell/v1/types · high confidence
Initial public API and internal contract definitions
The \proto\ directory now contains the authoritative source for OpenShell's gRPC contracts, establishing the public API (\openshell.proto\) and internal driver/interceptor contracts. This introduces the \OpenShell\ service with workspace-scoped resource management (sandboxes, templates, providers), a \ComputeDriver\ service for platform-agnostic sandbox lifecycle and capability negotiation, and a \CredentialDriver\ service for secure secret storage and resolution. The schema defines a \WorkspaceSelector\ for explicit workspace scoping, \ObjectMeta\ for consistent resource metadata, and a \SandboxPolicy\ supporting L7 protocol-aware network inspection (REST, GraphQL, WebSocket, MCP) with middleware injection. Additionally, \GatewayInterceptor\ and \SupervisorMiddleware\ services enable external governance and request/response mutation, while the legacy \navigator.proto\ has been removed.
proto · high confidence
Initial release of the Go SDK sandbox v1 protocol buffer definitions
This change introduces the generated Go code for the sandbox v1 API (\sdk/go/proto/sandboxv1/sandbox.pb.go\), establishing the foundational types and enums for the Go SDK. It defines core network configuration models, including \NetworkTlsMode\ (with \SKIP\, \TERMINATE\, and \PASSTHROUGH\ options), \NetworkEnforcementMode\ (supporting \ENFORCE\ and \AUDIT\ behaviors), and \NetworkAccessPreset\ (ranging from \READ\_ONLY\ to \FULL\ access). This file serves as the client-side type definition layer for interacting with sandbox network policies.
sdk/go/proto/sandboxv1 · high confidence
Initial release of the OpenShell TUI application
Introduces the OpenShell terminal user interface, providing a dashboard for managing gateways, providers, and sandboxes. The application features a splash screen, theme support (auto-detect, dark, and light modes), and interactive panels for viewing logs, editing global and sandbox settings, and managing provider configurations. It includes clipboard integration via OSC 52, keyboard navigation, and real-time log streaming from gateway and sandbox sources.
crates/openshell-tui/src · high confidence
Initial repository scaffolding and compliance setup
The repository has been initialized with foundational configuration and compliance files. This includes a \.dockerignore\ to exclude build artifacts, a \.env.example\ for local gateway configuration, and a \.markdownlint-cli2.jsonc\ to standardize documentation formatting. Compliance is established with Apache 2.0 licensing, a Developer Certificate of Origin (DCO), a Code of Conduct, and a Security policy. Additionally, a \.packit.yaml\ file is added to enable RPM builds via Fedora COPR, and a \.trivyignore.yaml\ is configured to manage security scan exceptions for Kubernetes manifests.
(repo-wide) · high confidence
Introduce @nvidia/openshell-sdk TypeScript client
The new \@nvidia/openshell-sdk\ package provides idiomatic TypeScript bindings for the OpenShell gateway, generated from protobuf definitions. It supports sandbox lifecycle management (create, delete, exec, streaming, and interactive sessions), port forwarding, and SSH sessions. Authentication is handled via static OIDC tokens or a renewable client-credentials provider that automatically discovers the issuer, validates the response, and handles token renewal. The SDK also includes a structured error taxonomy that decodes gateway error details and a typed deletion outcome system to clearly distinguish between completed, accepted, and missing-target states.
sdk/typescript · high confidence
Introduce Debian package for OpenShell with user-scoped gateway service
Users can now install OpenShell via a Debian package that includes the CLI, gateway daemon, policy prover, and VM compute driver helper. The package installs a user-scoped systemd unit for the gateway, which requires the user to manually enable and start it using \systemctl --user enable --now openshell-gateway\. The post-install script ensures that existing systemd user managers detect the new unit file without requiring a session restart.
deploy/deb · high confidence
Introduce Gator Gate Agent for automated PR review and monitoring
Adds a new manifest-driven Gator agent that runs a headless sandbox to validate and monitor OpenShell GitHub issues and pull requests. The agent uses a custom Dockerfile to provision a sandbox with Node.js 22, GitHub CLI, and the Codex harness, enforcing strict filesystem and process policies via a provided policy.yaml. It introduces a suite of shell utilities to manage the review lifecycle: a \gh\ wrapper that prevents duplicate review dispositions and enforces versioned payloads, a \review-feedback-ledger\ to aggregate and scope review threads, a \validate-review-findings\ tool to normalize security findings and blockers, and a \resolve-gator-review-threads\ script to automatically close Gator-owned threads when findings are fixed. The agent is configured via \agent.yaml\ to run in watch mode, polling PRs and coordinating with a principal-engineer-reviewer sub-agent. Also in this area: Updated gator agent tests to validate PR-owned security regression handling.
scripts/agents/gator/bin · high confidence
Introduce Go SDK for OpenShell v1 API
This change adds the initial Go SDK foundation for the OpenShell v1 API, providing the generated protobuf types and gRPC client stubs necessary to interact with the gateway. The new \openshellv1\ package exposes the complete public API surface, including methods for managing sandbox lifecycles (create, start, stop, delete), handling provider attachments and credentials, executing commands, and managing workspaces and policies. Users can now programmatically control OpenShell resources using the standard Go gRPC client interface.
sdk/go/proto/openshellv1 · high confidence
Introduce Go SDK foundation with typed workspace selectors and authorization rules
This change adds the initial Go SDK foundation in the \sdk/go/proto\ directory, introducing generated protobuf types that define core API capabilities. Specifically, it adds \WorkspaceSelector\ and \WorkspacePhase\ types to \datamodelv1\, enabling typed selection of single or all workspaces for API requests. It also introduces \AuthorizationRule\ and extension fields in \optionsv1\, which define per-method authorization metadata (including auth mode, roles, and scopes) consumed by the gateway's descriptor-pool-based auth table. These types form the structural basis for the Go SDK's sandbox client and API interactions.
sdk/go/proto/datamodelv1 · high confidence
Introduce Kubernetes Secrets credential driver
Added a new credential driver that stores and resolves credentials as Kubernetes Secret objects. The driver exposes a gRPC service over a Unix socket, allowing the system to store credentials in a specified namespace and resolve them via handles that reference the target Secret and key. It enforces namespace restrictions to ensure credentials are only resolved within the configured scope and manages Secret metadata with labels and annotations for tracking.
crates/openshell-driver-kubernetes-secrets · high confidence
Introduce OCSF v1.8.0 event types and serialization for OpenShell Sandbox
The \openshell-ocsf\ crate now provides a complete set of Open Cybersecurity Schema Framework (OCSF) v1.8.0 event definitions, enabling structured, standardized logging across the platform. This change adds Rust structs and serialization logic for nine core event classes: Network Activity, HTTP Activity, SSH Activity, Process Activity, Authentication, Detection Finding, Application Lifecycle, Device Config State Change, and API Activity. Each event type includes a common base structure (timestamps, severity, metadata) and specific fields tailored to its domain, such as AI model details for API Activity or firewall rules for network events. The implementation ensures that all events can be serialized to and deserialized from JSON using a unified \OcsfEvent\ enum, laying the groundwork for consistent observability and security telemetry.
crates/openshell-ocsf/src/events · high confidence
Introduce OpenShell Python SDK with structured error handling and provider credential management
The \python/openshell\ package is now available as a standalone Python SDK, exposing core capabilities such as \SandboxClient\, \SandboxTemplateClient\, \WorkspaceClient\, and \ProviderClient\. The SDK introduces structured error decoding via \GatewayError\ that preserves gRPC status details, field violations, and retry information, while \ProviderClient\ enables curated retrieval of provider credentials with expiration handling. The package also includes a gateway configuration migrator to handle schema v2 upgrades and provides comprehensive test coverage for these new components.
python/openshell · high confidence
Introduce OpenShell-to-MXC policy mapping module
The \policy\_map\ module in the MXC driver now maps OpenShell sandbox policies to Microsoft MXC \ContainerConfig\ files. It provides two mapping strategies: a coarse standalone mapper that flattens network policies into host allowlists, and a governed-egress split that delegates network enforcement to an OpenShell CONNECT proxy while MXC handles filesystem and containment. The module generates structured loss reports and human-readable summaries to highlight semantic gaps, unsupported features, and backend-specific behaviors (such as filesystem default-deny differences or network proxy limitations) between OpenShell and MXC.
_crates/openshell-driver-mxc/src/policy\map · high confidence
Introduce Podman compute driver for sandbox workloads
This change adds the \openshell-driver-podman\ crate, implementing the compute driver interface for managing sandbox containers via the Podman REST API. It introduces support for creating, starting, and stopping sandboxes, with configuration for user namespaces, SELinux labels, and corporate HTTPS proxy egress. The driver also handles sandbox authentication via JWT secrets, exposes OpenTelemetry tracing, and includes platform-specific socket discovery for both native Linux and macOS Podman Machine environments.
crates/openshell-driver-podman/src · high confidence
Introduce VFIO PCIe passthrough lifecycle management
The \openshell-vfio\ crate now provides the core infrastructure for managing VFIO PCIe passthrough for OpenShell VM sandboxes. It includes device discovery (scanning sysfs for eligible devices, with specific NVIDIA GPU probing), binding devices to the \vfio-pci\ driver (handling driver overrides, ID registration, and companion device binding within IOMMU groups), and crash-recovery (reconciling stale bindings left over from previous crashes). The module exposes RAII guards to ensure devices are restored to their host drivers on cleanup and provides a testable abstraction over sysfs.
crates/openshell-vfio · high confidence
Introduce VM driver runtime configuration and documentation
The \openshell-driver-vm\ runtime location now includes a README and a \pins.env\ file that define the pinned versions for guest-side dependencies (umoci v0.6.0, libkrunfw v5.6.1, libkrun v1.19.4) and document the build and provenance workflows for the VM sandbox runtime.
crates/openshell-driver-vm/runtime · high confidence
Introduce built-in regex middleware and HTTP response pre-return inspection
The supervisor middleware now includes a first-party built-in implementation (openshell/regex) that applies fixed regular-expression replacements to HTTP request bodies and WebSocket text messages, and adds a new HTTP response pre-return interface that allows middleware to inspect and mutate response headers, trailers, and body streams before they are sent to the client.
crates/openshell-supervisor-middleware · high confidence
Introduce canonical policy schema crate with strict YAML validation and MCP version pinning
The new \openshell-policy-schema\ crate establishes the canonical representation for authored policies, replacing ad-hoc parsing with strict schema validation. It enforces bounded YAML parsing, rejects null values at declared object paths, and prevents duplicate mapping keys during load. The crate pins supported MCP protocol revisions (2025-03-26 through 2026-07-28) with a default of 2025-11-25, ensuring consistent protocol handling. Additionally, YAML exports now quote strings and keys that legacy readers might misinterpret as dates, numbers, or booleans, preserving data integrity without altering actual numeric or boolean values.
crates/openshell-policy-schema · high confidence
Introduce capability-free sandbox boundary with secure exec and lifecycle management
The sandbox runtime has been refactored into a capability-free boundary model that isolates the workload from the gateway and policy authority. This change introduces a new boundary server and exec implementation that manages workload lifecycle, including graceful freeze/resume during supervisor reconnection and strict termination on enforcement loss. It adds secure process execution via \LocalBoundaryExec\ with proper environment handling (including TLS CA injection and shell detection), and implements a cancellation mechanism for blocking network accepts using \SIGUSR2\ to prevent resource leaks. Additionally, it introduces anonymous activity and denial aggregators to periodically flush network usage and policy violation summaries to the gateway, improving observability without exposing sensitive details.
crates/openshell-sandbox · high confidence
Introduce declarative provider profiles for credential discovery
The \openshell-providers\ crate now supports declarative provider profiles (YAML/JSON) that define credential requirements and discovery logic. Operators can import these profiles to configure providers, and the system automatically discovers credentials by scanning environment variables specified in the profile. This replaces ad-hoc configuration with a structured, profile-driven approach, including specific handling for providers like Google Vertex AI.
crates/openshell-providers/src · high confidence
Introduce disposable Linux VM test guest harness
Developers can now boot and configure disposable Linux VMs for testing OpenShell packages using Nix, QEMU, and Ansible. The new \nix/test-guest\ module supports Ubuntu 24.04/26.04, CentOS Stream 10, Fedora 44, and Rocky Linux 9, with configurations for Docker, rootful and rootless Podman, SELinux, and snapd. It provides a \test-guest\ app for interactive sessions and a \test-guest-cache\ app for managing prepared disk images via local storage or OCI registries, enabling reproducible, isolated testing environments.
nix/test-guest · high confidence
Introduce extension credential management and Kubernetes secrets driver
The server now includes a new \openshell-extension-core\ library that provides protocol-neutral primitives for extension mechanisms, including JWT-based bearer token rotation, identity/audience validation, and transport configuration (HTTPS/Unix sockets). This enables extensions to authenticate outbound requests with short-lived, refreshable credentials. Additionally, a new standalone \openshell-driver-kubernetes-secrets\ binary is introduced to act as a credential driver, binding to a Unix socket and using Kubernetes Secrets to store and serve credentials to the gateway. Also in this area: Gateway enforces user authentication and adds sandbox suspend/resume lifecycle; Operators can enforce specific supervisor middleware bindings; Fixes for sandbox stop reliability and stable credential placeholders; Public gateway now exposes gRPC reflection for service discovery; Confined unsafe code and replaced raw libc calls with safe Rustix abstractions.
(repo-wide) · medium confidence
Introduce formal policy prover with Z3-based containment and risk analysis
The \openshell-prover\ crate now provides a formal verification engine for OpenShell sandbox policies, using the Z3 SMT solver to model and analyze policy constraints. It introduces a standalone containment API that checks whether a candidate policy stays within an operator-defined boundary, covering process identity, Landlock compatibility, filesystem access, and network reachability (including L4 and REST endpoints). The prover also performs risk analysis by detecting credential reach expansion, L7 bypass risks, and capability expansions against a built-in binary and API capability registry (e.g., GitHub, Claude, curl). Findings are structured and categorized, allowing the gateway to gate auto-approval of agent-authored policy proposals based on these formal checks.
crates/openshell-prover · high confidence
Introduce gateway interceptor framework for request validation and modification
The new \openshell-gateway-interceptors\ crate provides a framework to intercept, validate, and modify gRPC requests at the gateway boundary. It supports three execution phases—ModifyOperation, Validate, and PostCommit—allowing interceptors to inspect and patch request bodies using JSON Patch operations before they reach handlers. The system enforces security by automatically omitting fields marked with the \openshell.options.v1.secret\ protobuf option and rejecting any patch paths that target these secrets. Interceptors are configured via \GatewayInterceptorConfig\ and can be authenticated using rotating bearer-token slots, with configurable timeouts and failure policies (FailClosed or FailOpen) to control behavior when interceptor services are unavailable.
crates/openshell-gateway-interceptors · high confidence
Introduce manifest-driven agent launcher with sandboxed runtime
Added a new generic launcher (\scripts/agents/run.sh\) and documentation (\README.md\) for running agents defined by YAML manifests. This system allows users to launch agents in isolated sandboxes where prompts, skills, and subagent definitions are baked into an immutable image payload. The launcher supports \once\ and \watch\ execution modes, handles provider credential injection, and manages the lifecycle of sandboxed harnesses (such as Codex) via a shared runtime supervisor.
scripts/agents · high confidence
Introduce modular Dockerfiles and docker-compose quickstart for OpenShell gateway, supervisor, and sandbox
The deployment structure has been reorganized into the deploy/docker directory, introducing separate, specialized Dockerfiles for the CI runner (Dockerfile.ci), gateway (Dockerfile.gateway), sandbox (Dockerfile.sandbox), and supervisor (Dockerfile.supervisor). The gateway and supervisor images now use distroless Debian 13 base images, while the sandbox image is built from scratch with a static musl binary. A new docker-compose.yml and gateway.toml provide a local quick-start setup using the Docker compute driver, featuring a one-shot init service for JWT key generation, bind-mounted data directories, and explicit configuration for the Docker socket and database URL. A shared cross-build helper script (cross-build.sh) supports multi-architecture Rust builds with sccache integration.
deploy/docker · high confidence
Introduce native Windows MXC compute driver with ETW audit and governed egress
This change adds the \openshell-driver-mxc\ crate, providing a native Windows compute driver that manages sandboxes via Microsoft MXC (\wxc-exec\). The driver supports two backends: \IsolationSession\ for persistent, attachable sessions and \ProcessContainer\ (default) for one-shot AppContainer workloads. It introduces a real-time ETW-to-OCSF audit consumer that captures OS Sandboxing provider events and emits them into the gateway's tracing sink. Additionally, it implements Pattern-C governed egress, allowing MXC to handle filesystem grants while redirecting network traffic through a host CONNECT proxy. The driver is Windows-only and compiles to a stub on other platforms.
crates/openshell-driver-mxc/src · high confidence
Introduce sandbox VM init script for guest rootfs preparation
A new init script (openshell-vm-sandbox-init.sh) is added to handle the minimal initialization of sandbox VMs. It runs as PID 1 inside the guest, mounts essential filesystems, and prepares the rootfs by extracting local Docker or OCI images. The script also normalizes the sandbox user/group ownership within the guest image to ensure consistent permissions.
crates/openshell-driver-vm/scripts · high confidence
Introduce shared supervisor host for Kubernetes gateway topology
The supervisor now supports a shared mode (\--mode=shared\) that hosts multiple sandbox instances within a single process, designed for the Kubernetes gateway supervisor topology. This host connects to the gateway via a secure stream, receives assignment snapshots, and manages the lifecycle of hosted sandboxes—including admission, suspension, and removal—while maintaining separate Tokio runtimes and isolated state for each instance. It also introduces a new \SandboxInstanceHost\ registry to manage concurrent instances, ensuring that instance removal is atomic and that gateway credentials are revoked before directory cleanup.
crates/openshell-supervisor · high confidence
Introduce standalone OCSF event types and formatters
The new \openshell-ocsf\ crate provides the core OCSF v1.8.0 event types, builders, and formatters for OpenShell sandbox logging. It introduces eight OCSF event classes (including Network, HTTP, SSH, Process, and Detection Finding activities) along with typed enums and objects. The crate includes a context management system (\EventContext\) that allows events to be attributed to specific sandbox instances or the supervisor, and provides sanitization utilities to ensure audit strings are safe. It also ships with dual formatters for human-readable shorthand and OCSF-compliant JSONL output, as well as tracing layers for integration.
crates/openshell-ocsf/src · high confidence
Introduce standalone libkrun VM compute driver
The VM compute driver now supports a standalone libkrun backend, enabling VM execution on macOS ARM64 and Linux (ARM64/x86\_64) without requiring QEMU. This change embeds the necessary libkrun and libkrunfw runtime libraries directly into the driver binary, automatically extracting and caching them at runtime. It also introduces a lifecycle extension framework that allows features like GPU passthrough and custom guest init drop-ins to be registered and activated via sandbox labels, while providing cross-platform process supervision to ensure VM helper processes are terminated if their parent dies.
crates/openshell-driver-vm/src · high confidence
Introduce standalone libkrun-backed VM compute driver
The \openshell-driver-vm\ crate is added as a new standalone compute driver that uses libkrun to boot microVMs. It embeds the necessary runtime artifacts (libkrun, guest sandbox, supervisor, and init scripts) and communicates with the gateway over a Unix-domain gRPC socket. The driver supports booting sandboxes from ext4 root disks with per-sandbox writable overlays, handles corporate HTTP proxy egress for image pulls, and exports traces via OTLP. It also includes a minimal guest init binary (\openshell-vm-init\) to prepare the network environment inside the VM.
crates/openshell-driver-vm · high confidence
Introduce standalone policy boundary checker CLI
The \openshell-prover\ command-line tool is now available to verify that a candidate policy remains within an operator-defined boundary. It accepts a candidate policy file and a boundary policy file, then checks containment across process, Landlock, and network (including destination IP) domains. The tool returns exit code 0 if the candidate is within the boundary, 1 if it exceeds it (providing a counterexample), and 2 or 3 for usage/internal errors or unsupported semantics. Output is available in text or JSON formats, with JSON including schema version, coverage domains, and detailed counterexample structures for process, Landlock, filesystem, and network violations.
crates/openshell-prover-cli · high confidence
Introduce the OpenShell SDK for programmatic gateway interaction
This change adds the \openshell-sdk\ crate, providing a shared async Rust client for OpenShell gateways. It exposes a high-level \OpenShellClient\ for sandbox lifecycle management (create, list, delete, exec, templates) and a raw gRPC escape hatch for other services. The SDK handles authentication via OIDC bearer tokens (with automatic refresh) and Cloudflare Access edge tokens (via a local WebSocket tunnel proxy), manages connection transport, and implements lazy pagination for list operations.
crates/openshell-sdk/src · high confidence
Introduces core primitives for extension identity, authentication, and transport
The \openshell-extension-core\ crate now provides the shared protocol-neutral primitives that underpin OpenShell extensions. It introduces \ExtensionIdentity\ and \ExtensionAudience\ to define service registrations and their expected JWT audiences, along with \ExtensionJwtClaims\ and a strict 1-hour TTL for short-lived bearer tokens. Authentication is handled by \BearerTokenSlot\ and \BearerTokenInterceptor\, which manage credential rotation and inject tokens into gRPC requests. The crate also includes \ExtensionCredentialStore\ for centralized credential management and \ExtensionChannelConfig\ with \ExtensionServerTrust\ to support outbound gRPC transport over HTTP, HTTPS (with platform or custom CA verification), and Unix sockets.
crates/openshell-extension-core · high confidence
Introduces ergonomic builders for OCSF event construction
The \openshell-ocsf\ crate now provides a set of builder structs for constructing Open Cybersecurity Schema Framework (OCSF) events, replacing manual struct initialization with a chainable API. This location introduces builders for API Activity, Base Events, Device Config State Changes, Detection Findings, HTTP Activity, Application Lifecycle, Network Activity, Process Activity, and SSH Activity. Each builder accepts a shared \EventContext\ to populate common metadata (such as sandbox ID, container image, and proxy endpoint) and exposes specific setters for event fields like severity, status, and activity type. The implementation includes compile-time enforcement for required fields (e.g., HTTP and Network builders require endpoints or request/response data before building) and sanitization logic for AI model names in API Activity events.
crates/openshell-ocsf/src/builders · high confidence
Introduces manifest-driven agent runtime with Codex harness and supervised lifecycle
The agent runtime now supports a manifest-driven architecture where the \OPENSHELL\_AGENT\_HARNESS\ environment variable selects the execution backend, starting with a new Codex harness. This harness manages authentication by preserving literal Codex account routing identities (rejecting opaque placeholders) and configuring the Codex CLI with specific model and reasoning settings. The runtime includes a supervisor script that enforces a sandbox-native lifecycle, supporting 'once' and 'watch' modes with retry logic for transient failures and state persistence. Sub-agent capabilities are also introduced, allowing the main agent to invoke specific sub-agents via dedicated prompts.
scripts/agents/runtime · high confidence
Introduces shared executable-identity resolution for RFC 0012 isolation backends
The new \openshell-binary-identity\ crate provides a shared mechanism for resolving executable identities on Linux, allowing isolation backends to bind resolved identities to active connections. It opens and hashes live executable objects for a given process and its bounded ancestors (either within a PID namespace or a specific process tree), returning path-and-digest evidence. The resolver also collects diagnostic command-line paths (which do not authorize network access) and fails entirely if any executable in the chain cannot be opened, hashed, or validated, ensuring that partial identities are never returned for denied connections.
crates/openshell-binary-identity · high confidence
Introduces the openshell-gateway crate for modular compute driver composition
The gateway binary is now structured around a new \openshell-gateway\ crate that acts as the composition boundary for linking first-party compute drivers. This change enables selective builds via feature flags (e.g., \compute-driver-vm\, \compute-driver-docker\, \compute-driver-kubernetes\, \compute-driver-podman\, \compute-driver-mxc\), allowing users to include only the drivers relevant to their target OS and environment. The crate handles the registration of these drivers into the gateway's compute driver registry, with specific logic for Windows (MXC, unsupported drivers) and Unix systems (Docker, Kubernetes, Podman, VM). The VM driver module specifically introduces configuration for sandbox state, image defaults, resource limits (vCPU, memory, disk), and corporate proxy support, ensuring the gateway can spawn and manage the VM driver subprocess securely.
crates/openshell-gateway/src · high confidence
New 'Bring Your Own Container' example with port forwarding support
Added a new example demonstrating how to run a custom container image inside an OpenShell sandbox. The example includes a Python REST API, a Dockerfile, and documentation showing how to build the image and launch the sandbox using the \--from\ flag. It highlights the new port forwarding capability (\--forward 8080\) which allows users to access services running inside the sandbox from their local machine via an SSH tunnel.
examples/bring-your-own-container · high confidence
New CLI authentication and output formatting modules
The CLI now includes dedicated modules for browser-based Cloudflare Access authentication (auth.rs), OIDC authentication with Keycloak (oidc\_auth.rs), and edge-authenticated WebSocket tunneling for gRPC traffic (edge\_tunnel.rs). It also introduces a generic output formatting system (output.rs) that standardizes JSON, YAML, and table rendering across commands, and adds shell completion helpers (completers.rs) for gateways, sandboxes, providers, and workspaces.
crates/openshell-cli/src · high confidence
New Helm chart for namespace-scoped workspace prerequisites
A new \openshell-workspace\ Helm chart has been added to \deploy/helm/\ to manage namespace-scoped resources required for OpenShell Kubernetes sandboxes. This chart installs the ServiceAccount, Role, RoleBinding, and NetworkPolicy needed in each workspace namespace, allowing the gateway and workspace releases to be upgraded and removed independently. It supports shared-gateway deployments by binding to a shared gateway ServiceAccount and includes a NetworkPolicy that restricts sandbox SSH ingress to gateway pods. The chart also conditionally grants PVC metadata read permissions when caller driver config is enabled.
deploy/helm · high confidence
New Jupyter sandbox example for running notebooks in OpenShell
Added an example in \examples/jupyter-sandbox\ that demonstrates how to run a Jupyter notebook inside an OpenShell sandbox. The entry includes a README with instructions to launch a sandboxed Jupyter server using the \openshell\ CLI, a sample Python notebook (\demo.ipynb\), and a security policy (\policy.yaml\) that restricts filesystem and network access while exposing the Jupyter service locally.
examples/jupyter-sandbox · high confidence
New MCP conformance end-to-end test harness
Added a new end-to-end test suite in \e2e/mcp-conformance\ that validates OpenShell's MCP proxy behavior against the upstream \modelcontextprotocol/conformance\ runner. The harness runs the untrusted upstream test runner in an isolated Docker container and bridges its requests to a host-side bridge service, which executes the actual MCP client inside an OpenShell-managed sandbox. This setup ensures that MCP traffic crosses the policy-enforced proxy, allowing verification of protocol version handling, JSON-RPC structure, and method parameter validation against pinned Tower profiles (0.22.2) and supported MCP revisions (2025-03-26 through 2026-07-28).
e2e/mcp-conformance · high confidence
New OCSF object types for structured event data
The \openshell-ocsf\ crate now includes a comprehensive set of OCSF v1.8.0 object definitions in \src/objects\, enabling structured serialization of audit and activity events. This addition introduces data models for AI inference (\AiModel\), API activity (\Api\), security findings (\FindingInfo\, \Evidence\, \Remediation\), and network context (\Endpoint\, \ConnectionInfo\, \HttpRequest\, \HttpResponse\, \Url\). It also adds objects for identity and access (\User\, \Actor\, \Service\), system context (\Device\, \OsInfo\, \Container\, \Image\), process tracking (\Process\), and security policy (\Attack\, \Technique\, \Tactic\, \FirewallRule\). These types provide the foundational schema for emitting standardized OpenTelemetry-compatible events across the platform.
crates/openshell-ocsf/src/objects · high confidence
New OIDC authentication flows and browser integration in Go SDK
The Go SDK now includes a comprehensive \oidc\ package supporting four authentication flows: Authorization Code with PKCE (interactive browser login), Keyboard flow (manual code entry for headless environments), Device Code flow (RFC 8628 for input-constrained devices), and Client Credentials grant (non-interactive service account authentication). The package also introduces platform-specific browser launching logic (using \open\, \xdg-open\, or \rundll32\) to handle interactive logins securely, along with OIDC discovery caching and gateway-aware configuration loading from \metadata.json\.
sdk/go/openshell/v1/oidc · high confidence
New Policy Advisor CTF example for testing policy recommendations
Added a new capture-the-flag example in the policy-advisor directory that demonstrates the policy recommendation pipeline. The example includes a restrictive sandbox policy, a Python script with seven network gates, and documentation explaining how to use the TUI or CLI to approve mechanistic policy recommendations generated by the sandbox proxy.
examples/policy-advisor · high confidence
New SPIFFE-backed token exchange demo for Kubernetes and Podman
Added a new example demonstrating dynamic token exchange using SPIFFE JWT-SVIDs. The demo includes Kubernetes manifests (deploying a token issuer, alpha/beta services, and SPIRE helper) and a Podman variant for local testing, along with provider profiles and automation scripts to validate the gateway's token exchange grant type.
examples/spiffe-token-exchange-demo · high confidence
New TUI interface for managing providers, sandboxes, and global settings
The terminal UI now includes dedicated modals and dashboard views for creating and configuring providers and sandboxes, alongside a new Global Settings tab. Users can create providers through a multi-step wizard (select type, choose method, enter key) and create sandboxes by specifying name, image, command, providers, and ports. The dashboard displays gateways, providers, and sandboxes in a structured layout, while the sandbox detail view shows metadata, restart policies, and pending policy drafts. Global settings can be viewed, edited, and confirmed via overlay dialogs, with access control messages for non-admin users.
crates/openshell-tui/src/ui · high confidence
New Vault and Database-backed credential storage drivers
Users can now persist credentials using two new driver implementations: a Vault-compatible HTTP API driver (openshell-driver-vault) and an encrypted database-backed driver (openshell-driver-db-credstore). The Vault driver supports Kubernetes and token-based authentication, configurable mount paths, KV version selection, and custom CA bundles, while the database driver encrypts credential envelopes using AES-256-GCM and stores them via a pluggable object store interface. Both drivers expose standard credential management operations (store, resolve, delete, list) and are designed to integrate with the existing credential provider framework.
crates/openshell-driver-vault · high confidence
New agent-driven policy management demo
Added an example demonstrating an end-to-end policy approval loop where a coding agent requests access changes. The demo shows how an agent inside a sandbox can propose narrow network rules when denied, how the gateway validates and holds proposals for human review (or auto-approves safe changes), and how the sandbox hot-reloads policies upon approval.
examples/agent-driven-policy-management · high confidence
New conformance test runner infrastructure for OpenShell CLI
The \openshell-conformance\ crate now provides a reusable framework for verifying OpenShell CLI behavior against a suite of portable scenarios. This includes a process execution boundary (\ProcessCli\) that runs the CLI binary with configurable timeouts and environment variables, and a scenario runner that manages test execution, result collection, and diagnostic reporting. The crate bundles specific conformance scenarios such as smoke tests, sandbox lifecycle, file transfer, and policy proposals, allowing users to verify CLI correctness across different environments.
crates/openshell-conformance/src · high confidence
New core infrastructure for authentication, network activity tracking, and configuration defaults
The \openshell-core\ crate now includes foundational modules that support gateway and sandbox operations. A new \auth\ module provides an \EdgeAuthInterceptor\ for gRPC requests, supporting both OIDC Bearer tokens and Cloudflare Access edge tokens. Network observability is enhanced with \activity.rs\ and \denial.rs\, which define shared event types (\ActivityEvent\ and \DenialEvent\) for tracking allowed/denied connections and policy violations across supervisor components. Configuration management is standardized in \config.rs\ with canonical default constants (e.g., ports, image repositories) and a new \PolicyValidationFailureMode\ to control gateway behavior when policy validation fails. Additionally, \container\_paths.rs\ and \driver\_mounts.rs\ establish reserved control paths and validation logic for bind mounts, ensuring workspace isolation and preventing collisions with OpenShell's internal state.
crates/openshell-core/src · high confidence
New developer tooling scripts for OpenShell
This change introduces a suite of new scripts in the \scripts/\ directory to support development, compliance, and testing workflows. A new \docker-cleanup.sh\ script allows users to safely remove stale Docker images, volumes, and build cache while preserving current cluster images and running containers, with options for dry-run and force modes. A \keycloak-dev.sh\ script and its associated \keycloak-realm.json\ configuration provide an automated way to spin up a local Keycloak instance for OIDC testing, including predefined roles and users. Compliance is supported by \generate\_third\_party\_notices.py\ and \update\_license\_headers.py\, which automate the collection of third-party license information and the addition of SPDX headers to source files. Additionally, \lint-mermaid/lint-mermaid.mjs\ adds pre-commit validation for Mermaid diagrams in Markdown files, \junit-to-html.xsl\ converts test reports to HTML, and \smoke-test-network-policy.sh\ provides an end-to-end test for sandbox network policies and credential injection. Finally, \test-release-tag.sh\ aids in verifying the automated release workflow.
scripts · high confidence
New development task definitions for CI, Docker, Helm, and SDKs
The \tasks/\ directory now includes a comprehensive set of TOML-based task definitions that standardize local development and CI workflows. New tasks cover CI pipelines (\ci.toml\), Docker image builds (\docker.toml\), documentation validation (\docs.toml\), gateway execution (\gateway.toml\), Go SDK operations (\go.toml\), Helm chart management (\helm.toml\), Keycloak integration (\keycloak.toml\), license compliance (\license.toml\), markdown linting (\markdown.toml\), third-party notices (\notices.toml\), Debian packaging (\package.toml\), Python SDK workflows (\python.toml\), Rust tooling (\rust.toml\), sandbox management (\sandbox.toml\), and SBOM generation (\sbom.toml\). These files provide structured commands for building, testing, and deploying OpenShell components, replacing ad-hoc scripts with a unified task interface.
tasks · high confidence
New e2e support utilities for capability probing, conformance, and schema-aware configuration
The e2e/support area now includes several new helper tools and scripts to improve test reliability and configuration management. A new C utility (capbset-probe.c) verifies the capability-bounding-set behavior inside rootless Podman containers, while musl-dns-probe.c tests DNS resolution and TCP connectivity for musl-based environments. A new conformance runner (conformance.sh) allows standalone CLI conformance suites to execute against a configured gateway. Additionally, the Podman gateway configuration logic has been updated to support schema v2, introducing new options like 'if\_not\_present' image pull policies and gateway-owned guest TLS, alongside a Python script (debian-package-manifest.py) to parse installed package metadata without invoking container tools.
e2e/support · high confidence
New example demonstrating private IP routing via allowed\_ips policy
Added a new example in \examples/private-ip-routing\ that demonstrates how to use the \allowed\_ips\ sandbox policy field to allow sandboxed processes to reach services on private IP space (such as cluster-internal pods) that are normally blocked by the proxy's SSRF protection. The example includes a simple Python HTTP server, a Dockerfile to build it, and a README with step-by-step instructions for deploying the pod and creating a sandbox with a policy that whitelists specific CIDR ranges (e.g., \10.42.0.0/16\).
examples/private-ip-routing · high confidence
New example for running the Codex app server in an OpenShell sandbox
Adds a new example in \examples/codex-app-server\ that demonstrates how to build a Docker image with the Codex CLI, configure an OpenShell provider profile for OAuth token management, and launch a sandboxed Codex app server. The example includes a startup script that injects provider credentials into the Codex auth configuration and exposes the server's WebSocket endpoint through the local OpenShell gateway for host-side client connections.
examples/codex-app-server · high confidence
New governance interceptor example for sandbox and provider policy enforcement
This change introduces a standalone reference example (\examples/governance-interceptor\) that implements the \openshell.gateway\_interceptor.v1.GatewayInterceptor\ service. The example demonstrates how to vend provider profiles (GitHub and Slack) and make them the gateway's authoritative profile source, restricting provider creation to only those matching vended profiles. It enforces governance by signing sandbox policies with EdDSA JWTs, verifying signatures during sandbox creation, and blocking unsigned or modified policies. The interceptor also denies sandbox-authored policy proposals and unauthorized provider profile imports or deletions, providing a complete pattern for policy-first governance.
examples/governance-interceptor · high confidence
New per-gateway authentication and identity management infrastructure
The openshell-bootstrap crate now provides the core storage and generation logic for gateway authentication, enabling distinct auth modes (mTLS, OIDC, and edge proxy) and per-sandbox identity. It introduces secure, owner-only storage for edge tokens (with migration from legacy cf\_token), OIDC token bundles with expiry and login-prompt tracking, and mTLS PKI bundles with atomic file updates. Additionally, it generates Ed25519 JWT signing keys for minting per-sandbox identity tokens and manages gateway metadata (including OIDC issuer/client details and SSH host resolution) to support the CLI's endpoint resolution and authentication flows.
crates/openshell-bootstrap · high confidence
New sandbox network policy engine and host-side proxy infrastructure
The \openshell-supervisor-network\ crate now includes a comprehensive network policy engine and host-side proxy implementation. A new Rego-based policy file (\sandbox-policy.rego\) defines the logic for allowing or denying network connections based on endpoint and binary identity matching, providing detailed deny reasons for debugging. The Rust source introduces a \HostProxyConfig\ and \start\_host\_proxy\ function to manage a CONNECT proxy for compute drivers (such as Windows MXC) that do not run the Linux supervisor, handling TLS termination with an ephemeral CA. Binary identity is enforced via a \BinaryIdentityCache\ using SHA256 trust-on-first-use (TOFU) and a \ProcfsIdentityResolver\ to resolve executable identities from procfs on Linux. Additionally, new L7 inspection modules for GraphQL, JSON-RPC, and MCP protocols have been added to parse and inspect request bodies, while HTTP helpers handle chunked body normalization for inspection.
crates/openshell-supervisor-network · high confidence
New sandbox policy quickstart example
Added a new \examples/sandbox-policy-quickstart\ directory containing a README walkthrough, an automated \demo.sh\ script, and a \policy.yaml\ file. This example demonstrates OpenShell's network policy system by showing how to create a sandbox with default-deny networking, apply a fine-grained L7 rule to allow read-only access to the GitHub API, and verify that write operations are blocked without restarting the sandbox.
examples/sandbox-policy-quickstart · high confidence
New supervisor-process crate for sandbox access-plane management
The \openshell-supervisor-process\ crate has been introduced to manage the supervisor's access plane, including an embedded SSH server, gateway session relay, and canonical process I/O multiplexing. It provides a \debug-rpc\ CLI for inspecting sandbox configuration and tokens, pushes sandbox logs to the server via gRPC, and installs static policy-advisor skills into the sandbox environment. Also in this area: Confined unsafe code and replaced raw libc calls with safe Rustix abstractions; Improved SSH session stability and resource management; Fixes sandbox shell detection and hardens Landlock policy validation.
crates/openshell-supervisor-process · high confidence
New transparent TCP Redis example demonstrating policy-enforced network isolation
Added a new example in \examples/transparent-tcp-redis\ that demonstrates connecting a Docker-backed OpenShell sandbox to a Redis instance using native TCP instead of an HTTP forward proxy. The example includes a demo script, a Python client, and a policy configuration that authorizes specific hostnames and ports while blocking unapproved hosts, wrong ports, and direct IP connections via policy DNS and transparent TCP mapping.
examples/transparent-tcp-redis · high confidence
OCSF event formatting and schema downgrade support
The \openshell-ocsf\ crate now provides formatters for OCSF events, including a human-readable shorthand log format and JSON/JSONL serialization. To support backward compatibility with older SIEM systems, the crate includes a downgrade mechanism that strips fields and profiles (such as \ai\_model\, \container\, and \ai\_operation\) when converting events to schema versions like 1.3.0 or earlier, while recording the original version in an \unmapped\ field.
crates/openshell-ocsf/src/format · high confidence
Operator-only credential export and shared supervisor pool for sandbox lifecycle
The gateway server now supports exporting provider credentials exclusively for operators (requiring a specific TLS certificate OU), enabling secure credential retrieval for administrative tasks. Additionally, it introduces a shared supervisor pool that coordinates sandbox lifecycle, membership, and instance placement across multiple gateway replicas using hash-based consistency and durable state reconciliation, ensuring high availability and consistent instance ownership during restarts or failures.
crates/openshell-server · high confidence
Sandbox suspend/resume and supervisor takeover capabilities
The sandbox backend now supports optional suspend and resume lifecycle operations, allowing workloads to be frozen and restored via new \SuspendBoundary\ and \ResumeBoundary\ RPCs and a \ResumeLaunch\ API. Additionally, the system introduces a supervisor takeover mechanism where a gateway-signed JWT grant allows a new supervisor process to replace the current owner of a runtime generation, ensuring continuity during supervisor failures or upgrades. These features are exposed through new protocol capabilities (\openshell.sandbox.suspend-resume\ and \openshell.sandbox.supervisor-takeover\) and are supported by updated telemetry enums and JWT session handling.
examples/isolation-backend-v8 · high confidence
Structured OCSF logging with dual output and schema downgrade support
The \openshell-ocsf\ crate now provides a dedicated tracing infrastructure that bridges internal OCSF event structs to the tracing system, enabling structured logging in two formats: human-readable shorthand and machine-parseable JSONL. The JSONL layer supports runtime toggling via an enabled flag and allows downgrading events to specific older schema versions for backward compatibility with SIEM systems. Additionally, a routed emit path is available for multi-sandbox environments to stamp per-event identifiers like \sandbox\_id\ while feeding both the JSONL audit file and the routing bus.
_crates/openshell-ocsf/src/tracing\layers · high confidence
Unified OpenTelemetry tracing for compute drivers and gRPC boundaries
The \openshell-otel\ crate now provides a shared, unified setup for OpenTelemetry trace export across all compute drivers (Docker, Podman, Kubernetes, VM) and sandbox supervisors. This change introduces standardized OTLP trace provider configuration, ensuring consistent service naming and resource attributes for gateway and driver interactions. It also adds comprehensive gRPC tracing adapters that automatically instrument the \ComputeDriver\ RPC boundary, capturing span context for operations like sandbox creation and status updates, and enables W3C trace-context propagation across HTTP and tonic transports to maintain distributed trace continuity. Also in this area: Sandbox suspend and resume lifecycle support.
crates/openshell-otel · high confidence
Windows MXC example suite for e2e testing and OCSF audit trails
The examples directory now includes a comprehensive set of Windows-specific artifacts for the MXC driver, including PowerShell orchestrators (run-mxc-e2e.ps1, run-ocsf-audit.ps1, probe-mxc-host.ps1) and configuration files (TOML/YAML). These enable end-to-end testing of filesystem policies (read-only, read-write, default-deny) and network policy rejection, as well as a dedicated audit trail example that captures Windows ETW events and maps them to the OCSF schema for durable JSONL logging.
crates/openshell-driver-mxc/examples · high confidence
Removals
Removal of Docker factory build infrastructure
The Docker-based factory build system has been removed. The \Dockerfile.factory\ file, which defined a multi-stage Python build environment for the supervisor container, has been deleted, along with the \mise.toml\ configuration that previously managed the \build:factory\ and \build:all\ Docker build tasks. Users can no longer build or utilize the factory Docker image through these specific files.
docker · high confidence
Removal of gRPC/HTTP multiplexed server implementation
The \navigator-server\ crate no longer includes the code for the gRPC service, HTTP health endpoints, protocol multiplexing, or TLS support. The files \grpc.rs\, \http.rs\, \multiplex.rs\, and \tls.rs\ have been deleted, removing the server's ability to listen on a TCP port and serve health checks or gRPC requests via the multiplexed architecture previously defined in \lib.rs\ and \main.rs\.
crates/navigator-server · high confidence
Removal of navigator-core configuration module
The \config.rs\ file and its associated \Config\ struct (including TLS and bind address settings) have been removed from the \navigator-core\ crate. This eliminates the shared configuration management previously exposed via \lib.rs\, meaning users can no longer rely on this central module for server connection or TLS setup parameters.
crates/navigator-core/src · high confidence
Removal of the legacy Navigator CLI
The \navigator-cli\ crate has been deleted, removing the standalone command-line interface that previously provided \health\ and \status\ commands for connecting to the Navigator server. Users will no longer be able to run the \navigator\ binary to check server health or view version and uptime information via this specific CLI tool.
crates/navigator-cli · high confidence
Removal of the legacy Navigator Python package
The legacy \python/navigator\ package, which previously provided the agent execution and management SDK (version 0.1.0), has been removed from the codebase. This deletion eliminates the associated module initialization and its unit tests, reflecting the project's transition away from the Navigator identity.
python/navigator · high confidence
Removal of the legacy Navigator Sandbox process isolation crate
The \navigator-sandbox\ crate, which previously provided a standalone CLI and library for spawning and monitoring sandboxed processes (including timeout handling, signal management, and process group isolation), has been completely removed. This eliminates the legacy process-level sandboxing mechanism in favor of the newer, more comprehensive sandboxing infrastructure (such as network namespaces, policy engines, and container-based isolation) that has been developed across the codebase.
crates/navigator-sandbox · high confidence
Architecture
Introduce standalone Kubernetes compute driver
The Kubernetes compute driver is now a standalone crate (\openshell-driver-kubernetes\) with its own configuration, gRPC service implementation, and resource provisioning logic. This change decouples the driver from the core server, allowing it to run as an independent process that exposes a \ComputeDriver\ RPC surface. Users benefit from improved modularity, clearer separation of concerns between the gateway and the runtime driver, and the ability to configure Kubernetes-specific settings (such as namespace modes, image pull policies, and network policies) independently.
crates/openshell-driver-kubernetes/src · high confidence
Behavioural changes
Automated git-derived versioning and centralized protobuf build configuration
The openshell-core crate now automatically derives the application version from git tags and commit history for local builds, following a 'guess-next-dev' convention that bumps the patch version for development builds (e.g., 0.0.4-dev.3+g2bf9969ab) while preserving exact stable or prerelease tags. Additionally, the crate's build script now centrally discovers and compiles all protobuf files from the proto directory, generating both Rust code and a binary FileDescriptorSet used by the server to enumerate RPCs at runtime, ensuring consistent protocol definitions across the gateway, sandbox, and router.
crates/openshell-core · high confidence
Backward-compatible protobuf aliases for sandbox types
The openshell protobuf module now exposes sandbox-related messages and phase enums via backward-compatible aliases in the datamodel module. Existing Python callers and E2E tests that import from datamodel\_pb2 will continue to work without changes, as the new openshell\_pb2 definitions are mirrored onto datamodel\_pb2 for Sandbox, SandboxSpec, SandboxTemplate, and SANDBOX\PHASE\\* enums.
_python/openshell/\proto · high confidence
CLI command structure reorganized into modular subcommands
The CLI command implementation has been refactored to extract shared helpers into a new \common\ module and split command groups into dedicated modules (\gateway\, \provider\, \provider\_readiness\). This restructuring improves code maintainability and separation of concerns without changing user-facing functionality.
crates/openshell-cli/src/commands · high confidence
CLI wrapper script renamed from 'nav' to 'openshell' with optimized rebuild detection
The development wrapper script in scripts/bin has been renamed from 'nav' to 'openshell' to reflect the project rebranding. This new script introduces a fingerprint-based rebuild check that monitors specific crates (openshell-cli, openshell-core, openshell-prover, etc.) and configuration files for changes, skipping compilation if the source state is unchanged. It also respects the CARGO\_TARGET\_DIR environment variable and automatically locates the local Z3 library for the build process.
scripts/bin · high confidence
Canonical policy schema and provider-layer composition
The \openshell-policy\ crate now owns the canonical authored policy representation (YAML/JSON serde, bounded parsing, and validation) in a new \openshell-policy-schema\ dependency, while adapting it to the runtime protobuf model. This introduces a reserved \\provider\\*\ namespace for provider policy layers, allowing provider endpoints to be composed into the effective sandbox policy without overwriting user-authored rules. The change also adds strict validation for L7 endpoint semantics (including transport choices like explicit TCP and TLS skip) and endpoint ambiguity detection to ensure deterministic policy behavior when multiple endpoints overlap.
crates/openshell-policy · high confidence
Clarifies agent skills location and adds Claude Code-specific configuration directory
The project now explicitly documents that agent skills are canonical in \.agents/skills/\ and shared across all tools, while \.claude/\ is reserved for Claude Code-specific configuration. A new \.claude/\ directory has been added, containing a README that explains this separation, a symlink \skills\ pointing to the shared skills directory, and subdirectories for agent persona definitions and persistent memory files that are specific to the Claude Code runtime.
.claude · high confidence
Introduce versioned Sandbox Protocol and concrete RPC backend
The sandbox backend now uses a versioned control protocol (v1.1) over gRPC instead of previous Rust traits, introducing a concrete supervisor-side client that manages boundary lifecycle, exec, and mediation via typed protobuf messages. This change adds support for supervisor takeover via gateway-signed grants, optional suspend and resume capabilities negotiated per backend, and exec recovery with 30-second admission deadlines. It also enforces loopback-only port forwarding, validates native Linux audit evidence, and requires synchronized updates between the supervisor and sandbox runtime to prevent fallback paths.
crates/openshell-sandbox-backend · high confidence
Migrate documentation site to Fern
The documentation site has been migrated to Fern, introducing a new configuration structure (fern/docs.yml, fern/fern.config.json) and a custom NVIDIA theme with specific light and dark mode styling. This change establishes a versioned publishing workflow that supports immutable release snapshots, a mutable dev channel, and a mutable latest channel, along with automated redirect synchronization to ensure legacy URLs resolve correctly.
fern · high confidence
RPM deployment introduces schema v2 configuration with automatic migration and Podman defaults
The RPM package now ships with a new schema v2 configuration format (gateway.toml) that pins the compute driver to Podman and defaults the bind address to 127.0.0.1. To support existing users, the package includes a migration script that automatically upgrades legacy schema v1 configurations to v2 during installation or upgrade, preserving any user-edited settings. This change is accompanied by new documentation (CONFIGURATION.md, QUICKSTART.md, TROUBLESHOOTING.md) detailing the new setup process, TLS certificate generation, and troubleshooting steps for rootless Podman environments.
deploy/rpm · high confidence
Removal of custom protobuf build script
The custom build script (build.rs) that previously handled protobuf compilation using tonic-build and a bundled protoc has been removed. This change indicates that the crate no longer manages proto file generation at build time, likely shifting to a pre-generated source approach or relying on a different build mechanism.
crates/navigator-core · high confidence
Removal of generated protocol buffer module
The generated protocol buffer code module (\navigator.v1.rs\) has been removed from the \navigator-core\ crate. This eliminates the local re-export of the generated types and service definitions, indicating a shift in how these protocol definitions are managed or consumed within the application.
crates/navigator-core/src/proto · high confidence
Removed NetworkBinary.harness field with backward-compatible wire decoding
The \NetworkBinary.harness\ field has been removed from the sandbox policy protocol buffer schema. To ensure backward compatibility, the system now ignores this field when decoding legacy wire formats, allowing existing stored policies to be read without error. The field's tag (2) and name are reserved in the schema to prevent future reuse, and tests confirm that legacy payloads decode correctly while the removed field is effectively dropped during round-trip serialization.
crates/openshell-core/src/proto · high confidence
Structured gateway errors and typed deletion outcomes in the Python SDK
The Python SDK now provides structured error handling and explicit mutation results. Gateway gRPC failures are wrapped in a typed \GatewayError\ that decodes standard details (field violations, error reasons, retry delays) while preserving the original transport exception, and a gRPC interceptor automatically applies this mapping to all client calls. Additionally, deletion operations now return a \DeletionResult\ with a \DeletionOutcome\ enum (COMPLETED, ACCEPTED, ALREADY\_ABSENT), allowing users to distinguish between successful deletion, accepted asynchronous processing, and cases where the target was already absent, rather than relying on generic success/failure semantics.
openshell · high confidence
Unified Linux cross-compilation toolchains via Nix
The Nix build system now provides a unified, platform-specific toolchain for Linux cross-compilation. This change introduces a new \nix/toolchain\ module that automatically selects the appropriate compiler environment (glibc 2.28 or musl) based on the target platform, constructs a proper sysroot for glibc targets, and configures environment variables (CC, CXX, LINKER) to use the custom driver. Users benefit from consistent cross-compilation setups across different Linux architectures without manual configuration.
nix, nix/toolchain · high confidence
VM provisioning now binds immutable boundary claims and resource assertions
The VM isolation module now provides a \provision\ method that takes driver-owned inputs (such as generation, image identity, and GPU requests) and produces a synchronized \VmBoundarySpec\ and \VmBoundaryProvisioning\. This ensures that the guest VM configuration and the host-side boundary descriptor share identical resource claims and identity evidence, preventing drift between the two sides of the authenticated boundary.
crates/openshell-driver-vm/src/isolation · high confidence
Vendored OCSF schemas updated to v1.8.0
The vendored Open Cybersecurity Schema Framework (OCSF) schemas in \crates/openshell-ocsf/schemas\ have been updated from version 1.7.0 to 1.8.0. This update includes new schema definitions for the \ai\_operation\ profile and refreshes the JSON definitions for core classes such as \base\_event\, \network\_activity\, \http\_activity\, \ssh\_activity\, \process\_activity\, \detection\_finding\, \application\_lifecycle\, \device\_config\_state\_change\, \api\_activity\, and \authentication\, along with their associated objects. These changes ensure that event validation and formatting logic aligns with the latest OCSF specification.
crates/openshell-ocsf/schemas · high confidence
Fixes
Fixes sandbox upload backpressure handling
The SSH upload implementation now correctly manages backpressure when sending archives to the sandbox supervisor. By enforcing a bounded chunk size (64 KB) that respects the credit window and acknowledgment intervals, the system prevents the producer from buffering excessive data in memory or waiting indefinitely for credits that may never arrive, ensuring stable and reliable uploads even under constrained network conditions.
crates/openshell-cli/src/ssh · high confidence
Simplified snap hooks and added terminal desktop entry
The snap packaging now uses simplified shell hooks (install, post-refresh, configure) to manage the gateway service mode, defaulting to a per-user gateway for fresh installations while migrating existing system-gateway setups. The post-refresh hook also removes insecure gateway configurations that allow plaintext or anonymous access to enforce mTLS defaults. Additionally, a new desktop entry file (term.desktop) is included to register the OpenShell terminal UI application in the system menu.
snap · high confidence
Test coverage
Added OCI image identity and workspace tests; Added Windows-specific policy mapping and MXC integration tests; Added conformance and driver-specific test suites; Added end-to-end tests for OIDC authentication and authorization; Added integration tests for CLI colorization, help output, gateway registration, and structured output; Added integration tests for Podman driver unavailability handling; Added integration tests for image preparation worker behavior; Added integration tests for the OpenShell SDK client; Added test support for OTLP gzip and TLS export scenarios; Added test to verify token service errors are not logged; Added testkit library for end-to-end test suites; Added tests for Keycloak provider refresh recovery; Added tests for OCSF event identity and JSON round-trip fidelity; Added tests for VM host tools preflight checks; Added tests for release versioning and wheel verification logic; Added tmachine test harness for VM-based integration testing; Migrate e2e test infrastructure from Bash to Rust; New E2E test infrastructure and harness scripts; New Rust-based E2E test suite for sandbox security and configuration; New end-to-end tests for agent-driven policy management; New portable conformance scenarios for file transfer, policy, lifecycle, and smoke tests; Python e2e test suite for sandbox security, policy, and exec admission.
Dependencies
OpenShell Rust workspace restructured with new crates and dependency updates
The Rust dependency manifests have been reorganized into a comprehensive workspace structure, introducing several new crates including \openshell-binary-identity\, \openshell-bootstrap\, \openshell-conformance\, \openshell-driver-db-credstore\, \openshell-driver-vault\, \openshell-extension-core\, \openshell-gateway-interceptors\, \openshell-ocsf\, \openshell-prover\, and \openshell-prover-cli\. The update also incorporates specific library version bumps, such as \hyper-rustls\ to 0.27, \bollard\ to 0.20, \oci-client\ to 0.16, and \regorus\ to 0.9, while standardizing common dependencies like \serde\, \tokio\, and \tonic\ across the new and existing components.
(dependencies) · high confidence
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 73 → 71 (-2.6)
Lenses
- Code Health 73 → 73 (+0.0)
- Architecture 96 → 94 (-1.3)
- Maturity 89 → 89 (-0.5)
- Readiness 69 → 64 (-5.5)
- Security 77 → 76 (-0.6)
- Event-Driven 80 → 80 (+0.0)
- Event Sourcing 100 → 100 (+0.0)
- Accessibility 80 → 80 (+0.0)
- Performance 82 → 81 (-0.4)
Resolved (174)
- Ambiguous naming for similar retrieval operations. Both methods return a String (gateway name) and appear to retrieve the 'active' gateway. The distinction between 'active' and 'user active' is not immediately clear from the signatures alone, suggesting potential duplication or confusing scope (e.g., global vs user-specific config).
- BoundaryRuntime::dispatch (cyclomatic 18) (crates/openshell-sandbox/src/boundary_server.rs)
- ComputeRuntime::create_sandbox_authenticated_with_guards (cognitive 23) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::create_sandbox_authenticated_with_guards (cyclomatic 21) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::start_sandbox_authenticated (cognitive 31) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::start_sandbox_authenticated (cyclomatic 22) (crates/openshell-server/src/compute/mod.rs)
- Confusingly similar boolean checks. is_token_expired and is_token_actually_expired have nearly identical names and signatures. The prefix 'actually' suggests the first method might be a cached or less precise check, but this is not obvious from the API surface and invites misuse.
- ControlReadiness::start (cyclomatic 16) (crates/openshell-supervisor/src/lib.rs)
- Duplicated block (10 lines × 2) (crates/openshell-driver-kubernetes/src/driver.rs)
- Duplicated block (10 lines × 2) (crates/openshell-driver-kubernetes/src/driver.rs)
- Duplicated block (10 lines × 2) (crates/openshell-sandbox/src/main_session.rs)
- Duplicated block (10 lines × 2) (crates/openshell-server/src/compute/mod.rs)
- Duplicated block (10 lines × 2) (crates/openshell-supervisor/src/lib.rs)
- Duplicated block (10 lines × 2) (crates/openshell-supervisor/src/lib.rs)
- Duplicated block (10 lines × 5) (crates/openshell-server/src/grpc/policy.rs)
- Duplicated block (10 lines × 6) (crates/openshell-server/src/grpc/sandbox.rs)
- Duplicated block (10 lines × 8) (crates/openshell-server/src/grpc/provider.rs)
- Duplicated block (11 lines × 2) (crates/openshell-driver-kubernetes/src/driver.rs)
- Duplicated block (11 lines × 2) (crates/openshell-sandbox/src/boundary_server.rs)
- Duplicated block (11 lines × 2) (crates/openshell-server/src/grpc/auth_rpc.rs)
- …and 154 more
New (240)
- ClassTooLong: ConfigRuntime (crates/openshell-supervisor/src/config_runtime.rs)
- ClassTooLong: SupervisorHostController (crates/openshell-supervisor-control/src/controller.rs)
- Classify ADR enforcement: Appendix: Deployment Options (rfc/0009-supervisor-middleware/appendices/deployment-options.md)
- Classify ADR enforcement: Appendix: Extension Authentication (Alpha) (rfc/0009-supervisor-middleware/appendices/extension-authentication.md)
- Classify ADR enforcement: Appendix: Protocol Extensions (rfc/0009-supervisor-middleware/appendices/protocol-extensions.md)
- Classify ADR enforcement: Current Shape Appendix (rfc/0005-sandbox-proxy-egress-adapter/current-shape.md)
- Classify ADR enforcement: Implementation Plan (rfc/0005-sandbox-proxy-egress-adapter/implementation-plan.md)
- Classify ADR enforcement: RFC 0014 Supplement - Build Matrix (rfc/0014-release-stability/build-matrix.md)
- Classify ADR enforcement: RFC 0014 Supplement - Release Qualification (rfc/0014-release-stability/release-qualification.md)
- Classify ADR enforcement: RFC 0014 Supplement - Release Version Selection (rfc/0014-release-stability/release-version-selection.md)
- Classify ADR enforcement: Technical Design Appendix (rfc/0005-sandbox-proxy-egress-adapter/technical-design.md)
- ComputeRuntime::create_sandbox_with_runtime_inputs_and_guards (cognitive 26) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::create_sandbox_with_runtime_inputs_and_guards (cyclomatic 24) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::recover_failed_lifecycle (cognitive 20) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::start_sandbox_with_intent (cognitive 42) (crates/openshell-server/src/compute/mod.rs)
- ComputeRuntime::start_sandbox_with_intent (cyclomatic 27) (crates/openshell-server/src/compute/mod.rs)
- ConfigRuntime::apply_delivered_sandbox (cognitive 26) (crates/openshell-supervisor/src/config_runtime.rs)
- ConfigRuntime::apply_delivered_sandbox (cyclomatic 18) (crates/openshell-supervisor/src/config_runtime.rs)
- ConfigRuntime::reconcile (cognitive 83) (crates/openshell-supervisor/src/config_runtime.rs)
- ConfigRuntime::reconcile (cyclomatic 51) (crates/openshell-supervisor/src/config_runtime.rs)
- …and 220 more
Changes since last survey
- 158 commits — 98 feature/other, 60 fixes
By area
- (root) — 26 commits
- crates/openshell-server — 19 commits
- .github/workflows — 17 commits
- crates/openshell-cli — 7 commits
- .github/actions — 6 commits
- crates/openshell-driver-vm — 6 commits
- deploy/helm — 6 commits
- crates/openshell-driver-kubernetes — 5 commits
- crates/openshell-ocsf — 5 commits
- tasks/scripts — 5 commits
- crates/openshell-sandbox — 4 commits
- crates/openshell-supervisor-network — 4 commits
- .agents/skills — 3 commits
- crates/openshell-core — 3 commits
- crates/openshell-prover — 3 commits
- sdk/go — 3 commits
- sdk/typescript — 3 commits
- .github/prompts — 2 commits
- crates/openshell-driver-docker — 2 commits
- crates/openshell-driver-podman — 2 commits
Notable commits
- fix: chore(ci): update rust-cache to include upstream fixes (#4748)
- fix: fix(agents): validate sandbox names before Gator launch setup (#4660)
- fix: fix(build): honor PROTOC when generating protobuf code (#4441)
- fix: fix(build): raise file limit for native gateway builds (#3122)
- fix: fix(ci): exempt Dependabot PRs from issue acceptance (#4928)
- fix: fix(ci): grant prerelease publish pull request read permission (#4747)
- fix: fix(ci): paginate required gate job lookups (#4663)
- fix: fix(ci): restore default e2e coverage with a Kubernetes recovery waiver (#4424)
- fix: fix(ci): skip maintainer approval in merge queue (#4496)
- fix: fix(ci): wait for controller reconciliation before Kubernetes conformance (#4676)
- fix: fix(cli): backpressure sandbox uploads (#4448)
- fix: fix(compute): allow stopping errored sandboxes for recovery (#4231)
- fix: fix(core): retry transiently busy e2fsprogs probes (#4315)
- fix: fix(deps): bump rustls to 0.23.46 for RUSTSEC-2026-0346..0349 (#4568)
- fix: fix(deps): patch TypeScript test dependencies (#4712)
- fix: fix(deps): scope rcgen's x509-parser feature to the supervisor (#4468)
- fix: fix(deps): update ctutils to resolve timing advisory (#4867)
- fix: fix(deps): update pytest to 9.0.3 (#4713)
- fix: fix(deps): update russh to 0.64.1 (#4742)
- fix: fix(deps): update setuptools to 83.0.0 (#4711)
- …and 138 more
Architecture
- Unchanged — 0 containers · 2 contexts · 0 edges
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
NVIDIA/OpenShell was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 27 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit e5adf6f484d6b7d3f3d21d5a864f95d3350194fd — the exact code this score is about.
- Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
- Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.34+preprod-c12eef3a1477.