feat(server): conditional compilation of compute drivers

.github/workflows/branch-checks.yml

@@ -125,6 +125,9 @@ jobs:
       - name: Verify telemetry can be compiled out
         run: mise run rust:verify:telemetry-off
 
+      - name: Verify each compute driver can be compiled out
+        run: mise run rust:verify:drivers-off
+
       - name: sccache stats
         if: always()
         run: |

README.md

@@ -252,12 +252,23 @@ OpenShell collects anonymous telemetry to help improve the project for developer
 
 Disable telemetry at runtime by setting `OPENSHELL_TELEMETRY_ENABLED=false` on the gateway deployment. OpenShell propagates this deployment setting into sandbox supervisor environments so sandbox-side telemetry collection is disabled as well.
 
-You can also compile telemetry out entirely. Telemetry support is a default-on `telemetry` Cargo feature; building with `--no-default-features` produces binaries that contain no telemetry endpoint, no telemetry HTTP client, and no emission code. Build telemetry-free artifacts with, for example, `cargo build --release -p openshell-server --no-default-features` (gateway) and the equivalent for `openshell-sandbox` and `openshell-driver-vm`. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to the sandboxes it launches.
+You can also compile telemetry out entirely. Telemetry support is a default-on `telemetry` Cargo feature; building `openshell-server` with `--no-default-features` and selecting only the driver features you need produces a gateway that contains no telemetry endpoint, no telemetry HTTP client, and no emission code. The gateway requires at least one compute driver to link; for example, `cargo build --release -p openshell-server --bin openshell-gateway --no-default-features --features driver-kubernetes,driver-docker,driver-podman,driver-vm` builds a telemetry-free gateway with every driver. Build telemetry-free `openshell-sandbox` and `openshell-driver-vm` binaries with a plain `--no-default-features`. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to the sandboxes it launches.
 
 Telemetry events are limited to anonymous operational categories and counts, such as sandbox lifecycle outcomes, provider profile buckets, policy decision counts, and aggregate network activity denial categories. OpenShell telemetry does not collect sandbox names or IDs, hostnames, file paths, binary paths, prompts, credentials, provider names, model names, or user content.
 
 Opting out applies only to telemetry emitted by OpenShell. Third-party services, model providers, inference endpoints, agents, or tools that you configure and use with OpenShell may have their own terms and privacy practices.
 
+## Choosing Which Compute Drivers Are Compiled In
+
+Each built-in compute driver — Kubernetes, Docker, Podman, VM — is gated by a Cargo feature on `openshell-server` (`driver-kubernetes`, `driver-docker`, `driver-podman`, `driver-vm`), all enabled by default. Operators who only need one driver can produce a slimmer gateway with a reduced supply-chain surface by building with `--no-default-features` and enabling the drivers they want:
+
+```shell
+cargo build --release -p openshell-server --bin openshell-gateway \
+  --no-default-features --features driver-kubernetes,telemetry
+```
+
+Any non-empty driver subset is a valid build, including zero built-in drivers (an extension-only gateway that reaches an out-of-tree driver over `[openshell.drivers.<name>].socket_path`). What the gateway needs at *runtime* is a `compute_drivers` entry it can serve: either a built-in this binary was built with, or an extension driver name with a matching socket_path entry. Naming a built-in that this gateway was not built with fails at startup with a message naming both the driver and the Cargo flag that re-enables it. Extension drivers reached via `--compute-driver-socket` work regardless of the feature set. See the [gateway configuration reference](docs/reference/gateway-config.mdx) for details.
+
 ## Notice and Disclaimer
 
 This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.

architecture/compute-runtimes.md

@@ -117,3 +117,27 @@ them without changing the sandbox architecture.
 
 When runtime infrastructure changes, validate the relevant sandbox e2e path and
 update the matching driver README if a maintainer-facing constraint changes.
+
+## Compile-Time Driver Selection
+
+Each built-in runtime is gated by a Cargo feature on `openshell-server`:
+`driver-kubernetes`, `driver-docker`, `driver-podman`, `driver-vm`. All
+four are on by default, so the default gateway is byte-equivalent to
+before the feature split. Building `--no-default-features` and selecting a
+subset produces a gateway that carries only the requested drivers, along
+with their transitive dependencies and driver-specific plumbing (Docker's
+supervisor readiness impl, the K8s ServiceAccount authenticator, the VM
+subprocess launcher, and so on).
+
+A zero-driver build is a supported extension-only gateway shape. It
+carries no in-tree driver code and speaks `compute_driver.proto` only to
+out-of-tree drivers named in `compute_drivers` with a matching
+`[openshell.drivers.<name>].socket_path`. A driver named in
+`gateway.toml` that this binary was not built with fails at startup with
+a message naming both the driver and the Cargo flag that re-enables it;
+auto-detection skips drivers that were compiled out and falls through to
+a "no suitable driver" error rather than silently picking a
+different backend. Extension drivers reached via
+`--compute-driver-socket` are always available regardless of driver
+features — they run out-of-process and the gateway only needs to speak
+`compute_driver.proto`.

crates/openshell-core/src/config.rs

@@ -49,7 +49,7 @@ pub const CDI_GPU_DEVICE_ALL: &str = "nvidia.com/gpu=all";
 pub const DEFAULT_SANDBOX_PIDS_LIMIT: i64 = 2048;
 
 /// Compute backends the gateway can orchestrate sandboxes through.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ComputeDriverKind {
     Kubernetes,

crates/openshell-driver-docker/src/lib.rs

@@ -5,6 +5,15 @@
 
 #![allow(clippy::result_large_err)]
 
+/// Compile-out guard: greppable proof this crate is linked into a binary.
+///
+/// `tasks/scripts/verify-drivers-compiled-out.sh` asserts this string is
+/// present when `--features driver-docker` is on and absent when it is
+/// off. `#[used]` prevents dead-code elimination; the linker cannot drop it.
+/// Do not remove without updating the verify script.
+#[used]
+static COMPILE_MARKER: &str = "OPENSHELL_DRIVER_MARKER:docker";
+
 use bollard::Docker;
 use bollard::errors::Error as BollardError;
 use bollard::models::{

crates/openshell-driver-kubernetes/src/lib.rs

@@ -11,3 +11,12 @@ pub use config::{
 };
 pub use driver::{KubernetesComputeDriver, KubernetesDriverError};
 pub use grpc::ComputeDriverService;
+
+/// Compile-out guard: greppable proof this crate is linked into a binary.
+///
+/// `tasks/scripts/verify-drivers-compiled-out.sh` asserts this string is
+/// present when `--features driver-kubernetes` is on and absent when it is
+/// off. `#[used]` prevents dead-code elimination; the linker cannot drop it.
+/// Do not remove without updating the verify script.
+#[used]
+static COMPILE_MARKER: &str = "OPENSHELL_DRIVER_MARKER:kubernetes";

crates/openshell-driver-podman/src/lib.rs

@@ -13,3 +13,12 @@ pub(crate) mod watcher;
 pub use config::PodmanComputeConfig;
 pub use driver::PodmanComputeDriver;
 pub use grpc::ComputeDriverService;
+
+/// Compile-out guard: greppable proof this crate is linked into a binary.
+///
+/// `tasks/scripts/verify-drivers-compiled-out.sh` asserts this string is
+/// present when `--features driver-podman` is on and absent when it is
+/// off. `#[used]` prevents dead-code elimination; the linker cannot drop it.
+/// Do not remove without updating the verify script.
+#[used]
+static COMPILE_MARKER: &str = "OPENSHELL_DRIVER_MARKER:podman";

crates/openshell-server/Cargo.toml

@@ -17,9 +17,10 @@ path = "src/main.rs"
 [dependencies]
 openshell-bootstrap = { path = "../openshell-bootstrap" }
 openshell-core = { path = "../openshell-core", default-features = false }
-openshell-driver-docker = { path = "../openshell-driver-docker" }
-openshell-driver-kubernetes = { path = "../openshell-driver-kubernetes" }
-openshell-driver-podman = { path = "../openshell-driver-podman" }
+# Compute driver crates are gated by the `driver-*` features below.
+openshell-driver-docker = { path = "../openshell-driver-docker", optional = true }
+openshell-driver-kubernetes = { path = "../openshell-driver-kubernetes", optional = true }
+openshell-driver-podman = { path = "../openshell-driver-podman", optional = true }
 openshell-ocsf = { path = "../openshell-ocsf" }
 openshell-policy = { path = "../openshell-policy" }
 openshell-prover = { path = "../openshell-prover" }
@@ -99,11 +100,24 @@ arc-swap = "1"
 notify = "8"
 
 [features]
-default = ["telemetry"]
+default = [
+    "telemetry",
+    "driver-kubernetes",
+    "driver-docker",
+    "driver-podman",
+    "driver-vm",
+]
 ## Compile in anonymous telemetry emission (forwards to openshell-core/telemetry).
 ## On by default; build with `--no-default-features` for a telemetry-free gateway
 ## that contains no telemetry endpoint, HTTP client, or emission code.
 telemetry = ["openshell-core/telemetry"]
+## Compile in the in-tree compute drivers.
+driver-kubernetes = ["dep:openshell-driver-kubernetes"]
+driver-docker = ["dep:openshell-driver-docker"]
+driver-podman = ["dep:openshell-driver-podman"]
+## The VM driver itself runs out-of-process;
+## this feature gates the in-server code that spawns and speaks gRPC to it.
+driver-vm = []
 bundled-z3 = ["openshell-prover/bundled-z3"]
 test-support = []
 

crates/openshell-server/src/auth/mod.rs

@@ -13,6 +13,7 @@ pub mod authz;
 pub mod guard;
 mod http;
 pub mod identity;
+#[cfg(feature = "driver-kubernetes")]
 pub mod k8s_sa;
 pub mod method_authz;
 pub mod oidc;

crates/openshell-server/src/cli.rs

@@ -14,6 +14,11 @@ use tracing::{info, warn};
 use tracing_subscriber::EnvFilter;
 
 use crate::certgen;
+#[cfg(any(
+    feature = "driver-docker",
+    feature = "driver-podman",
+    feature = "driver-vm"
+))]
 use crate::compute::driver_config::GuestTlsPaths;
 use crate::config_file::{self, ConfigFile, GatewayFileSection};
 use crate::defaults::{self, LocalTlsPaths};
@@ -247,8 +252,13 @@ fn prepare_server_config(args: &mut RunArgs, matches: &ArgMatches) -> Result<Ser
     }
     normalize_compute_driver_socket_args(args, matches)?;
 
-    let local_tls = apply_runtime_defaults(args)?;
-    let guest_tls = local_tls.as_ref().map(GuestTlsPaths::from);
+    apply_runtime_defaults(args)?;
+    #[cfg(any(
+        feature = "driver-docker",
+        feature = "driver-podman",
+        feature = "driver-vm"
+    ))]
+    let guest_tls = resolved_local_tls(args)?.as_ref().map(GuestTlsPaths::from);
     let local_jwt = defaults::complete_local_jwt_config()?;
 
     let bind = SocketAddr::new(args.bind_address, args.port);
@@ -421,6 +431,11 @@ fn prepare_server_config(args: &mut RunArgs, matches: &ArgMatches) -> Result<Ser
     Ok(ServerStartupConfig {
         config,
         config_file: file,
+        #[cfg(any(
+            feature = "driver-docker",
+            feature = "driver-podman",
+            feature = "driver-vm"
+        ))]
         guest_tls,
     })
 }
@@ -494,12 +509,8 @@ fn resolve_config_path(args: &RunArgs) -> Result<Option<PathBuf>> {
     Ok(default_path.is_file().then_some(default_path))
 }
 
-fn apply_runtime_defaults(args: &mut RunArgs) -> Result<Option<LocalTlsPaths>> {
-    let local_tls = if args.disable_tls {
-        None
-    } else {
-        defaults::complete_local_tls_paths()?
-    };
+fn apply_runtime_defaults(args: &mut RunArgs) -> Result<()> {
+    let local_tls = resolved_local_tls(args)?;
 
     if args.db_url.is_none() {
         args.db_url = Some(defaults::default_database_url()?);
@@ -516,7 +527,17 @@ fn apply_runtime_defaults(args: &mut RunArgs) -> Result<Option<LocalTlsPaths>> {
         args.tls_client_ca = Some(paths.ca.clone());
     }
 
-    Ok(local_tls)
+    Ok(())
+}
+
+/// Read the local TLS bundle if TLS is not disabled and a complete bundle
+/// exists on disk.
+fn resolved_local_tls(args: &RunArgs) -> Result<Option<LocalTlsPaths>> {
+    if args.disable_tls {
+        Ok(None)
+    } else {
+        defaults::complete_local_tls_paths()
+    }
 }
 
 /// Returns `true` when an argument's value came from clap's built-in default
@@ -1156,7 +1177,8 @@ mod tests {
         let _g2 = EnvVarGuard::set("XDG_STATE_HOME", tmp.path().to_str().unwrap());
 
         let (mut args, _) = parse_with_args(&["openshell-gateway", "--disable-tls"]);
-        let local_tls = super::apply_runtime_defaults(&mut args).unwrap();
+        super::apply_runtime_defaults(&mut args).unwrap();
+        let local_tls = super::resolved_local_tls(&args).unwrap();
 
         let expected = format!(
             "sqlite:{}",
@@ -1195,7 +1217,8 @@ mod tests {
         }
 
         let (mut args, _) = parse_with_args(&["openshell-gateway"]);
-        let local_tls = super::apply_runtime_defaults(&mut args)
+        super::apply_runtime_defaults(&mut args).unwrap();
+        let local_tls = super::resolved_local_tls(&args)
             .unwrap()
             .expect("complete bundle should be returned");
 
@@ -1764,6 +1787,7 @@ mem_mib = "not-a-number"
     }
 
     #[test]
+    #[cfg(feature = "driver-kubernetes")]
     fn driver_inherits_shared_image_from_gateway_section() {
         // [openshell.gateway].default_image inherits into the K8s driver
         // table when the driver-specific table does not set it.
@@ -1789,6 +1813,7 @@ namespace = "agents"
     }
 
     #[test]
+    #[cfg(feature = "driver-kubernetes")]
     fn driver_specific_value_overrides_gateway_inheritance() {
         let file = config_file_from_toml(
             r#"