feat: add configurable GPU acceleration profiles

CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to Devboxes are documented here. The project follows [Keep a
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-20
+
+### Added
+
+- Added opt-in, operator-approved GPU profiles across Helm, the API, CLI, dashboard, and in-product documentation, including default and explicitly named profile selection.
+- Added portable extended-resource requests for NVIDIA, AMD, Intel, partitioned, shared, device-plugin, and compatible Dynamic Resource Allocation bridge configurations, with optional per-profile workspace images, RuntimeClasses, supplemental groups, node selectors, and tolerations.
+- Added authenticated installation capability discovery, GPU allocation reporting, scheduler diagnostics, strict chart and controller validation, Helm contract tests, and end-to-end controller coverage.
+
+### Changed
+
+- Persist the fully resolved GPU profile on each workspace so stop, start, and Insights reconciliation cannot silently change or remove an existing hardware allocation after Helm configuration changes.
+- Show accelerator allocation in CLI list and status output and in the browser workbench while keeping CPU-only creation as the default.
+
+### Fixed
+
+- Made the Insights HTTP integration fixture use the current observation time so the full controller suite remains deterministic after its original fixture date.
+
+### Security
+
+- Restrict clients to named operator-owned profiles instead of accepting arbitrary images, resource names, RuntimeClasses, supplemental groups, selectors, tolerations, privileged mode, or host mounts.
+
 ## [0.3.0] - 2026-07-14
 
 ### Added
@@ -90,7 +111,8 @@ All notable changes to Devboxes are documented here. The project follows [Keep a
 - Portable Helm chart with values schema, namespace-scoped RBAC, configurable storage, ingress, LoadBalancer or NodePort SSH, ServiceMonitor, and disruption budget.
 - macOS and Linux CLI releases, SHA-256 verification installer, GHCR images, OCI chart publishing, image provenance attestations, and clean Kind install CI.
 
-[Unreleased]: https://github.com/vicotrbb/devboxes/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/vicotrbb/devboxes/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/vicotrbb/devboxes/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/vicotrbb/devboxes/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/vicotrbb/devboxes/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/vicotrbb/devboxes/compare/v0.1.2...v0.2.0

Makefile

@@ -20,6 +20,7 @@ test:
 
 helm:
 	scripts/test-helm-insights.sh
+	scripts/test-helm-gpu.sh
 	helm template devboxes charts/devboxes --namespace devboxes --set workspace.sshService.type=NodePort --set workspace.sshService.host=192.0.2.10 >/dev/null
 
 images:

README.md

@@ -23,6 +23,7 @@ Each workspace includes Rust, Node.js, Python, `uv`, GitHub CLI, Codex CLI, Clau
 - A Rust `devbox` CLI for create, list, inspect, SSH, start, stop, delete, and opt-in Insights workflows.
 - A FastAPI controller with an authenticated API, accessible browser workbench, Insights dashboard, documentation, metrics, health checks, and TTL cleanup.
 - A versioned Helm chart with values schema validation and namespace-scoped RBAC.
+- Optional operator-approved GPU profiles for NVIDIA, AMD, Intel, partitioned, or shared accelerators.
 - Multi-architecture controller and workspace images for `linux/amd64` and `linux/arm64`.
 - Persistent SSH host identity, shell state, tool installs, account state, and source under `/home/dev`.
 - GitHub Releases with macOS and Linux CLI binaries and SHA-256 checksums.
@@ -40,6 +41,8 @@ Devboxes is currently a single-operator system: one shared token controls every
 - An SSH public key.
 - An ingress controller and TLS certificate only if you expose the dashboard through ingress. Port-forwarding works without either.
 
+GPU acceleration additionally requires GPU nodes, a working vendor device plugin or a Dynamic Resource Allocation driver with a compatible extended-resource bridge, and a workspace image containing the user-space libraries needed by the workload. GPU support is opt-in and CPU-only remains the safe default.
+
 The workspace container intentionally supports passwordless `sudo` for the trusted development user. Its pod drops all capabilities and adds back a small set needed by `sudo` and OpenSSH PTY auditing, but it is not compatible with the Kubernetes `restricted` Pod Security profile. Use the `baseline` profile or an equivalent policy in the Devboxes namespace.
 
 ## Install
@@ -84,7 +87,7 @@ kubectl -n devboxes create secret generic devboxes-workspace \
   --from-file=SSH_AUTHORIZED_KEYS="$HOME/.ssh/id_ed25519.pub"
 
 helm install devboxes oci://ghcr.io/vicotrbb/charts/devboxes \
-  --version 0.3.0 \
+  --version 0.4.0 \
   --namespace devboxes
 ```
 
@@ -132,6 +135,40 @@ For clusters without a load balancer, let Kubernetes allocate a distinct NodePor
 
 See [configuration](docs/configuration.md) for every supported value and platform examples.
 
+### Enable GPU acceleration
+
+Operators expose trusted, named profiles instead of allowing clients to inject Kubernetes pod fields. Each profile binds a user-facing name to an extended resource, count, optional GPU-ready workspace image, and optional scheduling policy:
+
+```yaml
+gpu:
+  enabled: true
+  defaultProfile: nvidia-l4
+  profiles:
+    - name: nvidia-l4
+      displayName: NVIDIA L4
+      description: One dedicated L4 for inference and CUDA development
+      resourceName: nvidia.com/gpu
+      count: 1
+      workspaceImage: ghcr.io/example/devboxes-workspace-cuda:12.8
+      runtimeClassName: nvidia
+      nodeSelector:
+        accelerator: nvidia-l4
+      tolerations:
+        - key: nvidia.com/gpu
+          operator: Exists
+          effect: NoSchedule
+```
+
+After upgrading the release with this values file, users can discover and request profiles through every supported interface:
+
+```bash
+devbox gpu profiles
+devbox create inference --gpu --ssh
+devbox create training --gpu-profile nvidia-l4 --preset large --ssh
+```
+
+The dashboard exposes the same profiles in its create form. Devboxes sets the resource in both container requests and limits, preserves the resolved allocation across stop and start, and surfaces scheduler reasons when capacity is unavailable. Read [GPU acceleration](docs/gpu.md) for driver prerequisites, NVIDIA and AMD examples, image contracts, sharing, security, upgrades, and troubleshooting.
+
 ### Enable Insights
 
 Insights is disabled by default. Enable it to collect privacy-bounded local AI metrics and aggregate Git activity into a persistent controller database:
@@ -178,6 +215,7 @@ Authenticate and create a box:
 ```bash
 devbox login --url https://devboxes.example.com
 devbox create atlas --preset medium --ttl 24 --repo owner/project --ssh
+devbox create inference --gpu --ssh
 ```
 
 Login opens the system browser, asks the current Devboxes browser session to approve the
@@ -247,7 +285,7 @@ devbox CLI / browser
 Devboxes controller ─── Kubernetes API
           │                  │
           │                  ├─ Secret (scoped Insights ingest credential)
-          │                  ├─ Deployment (disposable compute)
+          │                  ├─ Deployment (disposable CPU or GPU compute)
           │                  ├─ Service (LoadBalancer or NodePort SSH)
           │                  └─ PVC (persistent /home/dev)
           ├─ TTL cleanup and lifecycle state
@@ -274,14 +312,15 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Security repo
 
 - [Golden path](docs/golden-path.md) for a performance-oriented installation and daily workflow.
 - [CLI reference](docs/cli.md) and [API reference](docs/api.md) for client contracts.
+- [GPU acceleration](docs/gpu.md) for accelerator profiles, images, scheduling, and operations.
 - [Insights](docs/insights.md) for telemetry semantics, privacy, storage, backup, and purge.
 - [Configuration](docs/configuration.md) and [credentials](docs/credentials.md) for installation details.
 - [Operations](docs/operations.md) and [troubleshooting](docs/troubleshooting.md) for production ownership.
 - [Architecture](docs/architecture.md) and [development](docs/development.md) for maintainers.
 
 ## Project status
 
-Devboxes is at `v0.3`: useful and installable, with an intentionally narrow trust model. Compatibility follows semantic versioning after `v1.0`; before then, minor releases may include documented configuration or API changes. PVC data is never automatically deleted, including at TTL expiry.
+Devboxes is at `v0.4`: useful and installable, with an intentionally narrow trust model. Compatibility follows semantic versioning after `v1.0`; before then, minor releases may include documented configuration or API changes. PVC data is never automatically deleted, including at TTL expiry.
 
 ## License
 

SECURITY.md

@@ -28,6 +28,7 @@ Recommended deployment controls:
 - use fine-grained, least-privilege provider tokens;
 - enable Kubernetes Secret encryption at rest and an auditable secret manager;
 - enforce the chart's namespace-scoped RBAC and tokenless workspace service account;
+- expose GPU devices only through reviewed operator-owned profiles and trusted derived images;
 - back up important PVCs and test restore procedures;
 - keep Kubernetes, ingress, CSI, images, chart, and CLI releases current;
 - verify release checksums and image provenance attestations.
@@ -39,6 +40,8 @@ Workspace SSH disables password, keyboard-interactive, and root login and uses p
 Ed25519 host keys. Incoming terminal names are validated against installed terminfo before
 tmux starts.
 
+GPU profiles preserve this trust model. Clients can select only a configured name; they cannot inject an image, extended resource, RuntimeClass, supplemental group, selector, toleration, privileged mode, host path, or device path. The assigned device is fully available to the trusted workspace user, including through passwordless `sudo`, so GPU profiles do not make Devboxes suitable for untrusted workloads. Vendor drivers, device plugins, runtimes, and derived GPU images are part of the operator's trusted supply chain.
+
 ## Dependency and supply-chain policy
 
 Dependabot monitors npm, Cargo, Python, Docker, and GitHub Actions dependencies. Pull requests receive dependency review, and CI audits npm, Python, and Cargo dependencies, builds both images, performs strict JavaScript, documentation, controller, and CLI checks, validates Helm output, and installs into a clean Kind cluster. Release images are published for amd64 and arm64 with GitHub artifact attestations; CLI archives include SHA-256 checksums.

SUPPORT.md

@@ -11,8 +11,11 @@ kubectl get deployment,service,pvc,pod -n devboxes -o wide
 kubectl logs -n devboxes deployment/devboxes --tail=200
 kubectl get events -n devboxes --sort-by=.lastTimestamp
 devbox --version
+devbox gpu profiles
 ```
 
 For SSH problems, state whether the installation uses `LoadBalancer` or `NodePort`, whether the address is reachable from the CLI machine, and the exact OpenSSH error. For storage problems, include the StorageClass name, access mode, expansion support, and PVC events.
 
+For GPU problems, include the selected profile, redacted `devbox status` output, the pod's scheduling events, Kubernetes RuntimeClass presence, and the exact extended resource shown in node allocatable capacity. State whether the vendor plugin uses dedicated, partitioned, or shared devices. Do not include private registry credentials, image pull Secrets, public node addresses, or proprietary workload output.
+
 Security issues must follow [SECURITY.md](SECURITY.md) and must not be posted publicly.

charts/devboxes/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: devboxes
 description: Self-hosted, ephemeral development environments on Kubernetes
 type: application
-version: 0.3.0
-appVersion: "0.3.0"
+version: 0.4.0
+appVersion: "0.4.0"
 kubeVersion: ">=1.29.0-0"
 home: https://github.com/vicotrbb/devboxes
 icon: https://raw.githubusercontent.com/vicotrbb/devboxes/main/docs/assets/devboxes-mark.svg
@@ -17,8 +17,8 @@ annotations:
   artifacthub.io/category: integration-delivery
   artifacthub.io/changes: |
     - kind: added
-      description: Add privacy-bounded Devboxes Insights for AI metrics and aggregate Git activity
+      description: Add operator-approved GPU profiles across Helm, API, CLI, and dashboard workflows
     - kind: added
-      description: Add dashboard and CLI summary, status, activity, export, and purge workflows
+      description: Add accelerator discovery, allocation reporting, and scheduler diagnostics
     - kind: security
-      description: Add dual allowlists and scoped per-workspace ingest credentials
+      description: Restrict users to named operator-owned hardware profiles and pinned workload contracts

charts/devboxes/templates/NOTES.txt

@@ -26,3 +26,11 @@ Devboxes is installed in namespace {{ .Release.Namespace }}.
 Important: every workspace needs an externally reachable SSH service. Configure
 workspace.sshService for your cluster's LoadBalancer implementation or use
 NodePort with workspace.sshService.host.
+{{- if .Values.gpu.enabled }}
+
+GPU acceleration is enabled with {{ len .Values.gpu.profiles }} operator-approved profile(s).
+Confirm the matching node drivers, device resources, runtimes, and workspace images,
+then inspect the user catalog with:
+
+   devbox gpu profiles
+{{- end }}

charts/devboxes/templates/deployment.yaml

@@ -1,6 +1,29 @@
 {{- if and .Values.insights.enabled (ne (int .Values.controller.replicaCount) 1) }}
 {{- fail "controller.replicaCount must be exactly 1 when insights.enabled=true" }}
 {{- end }}
+{{- $gpuProfileNames := dict }}
+{{- $gpuDefaultFound := false }}
+{{- range .Values.gpu.profiles }}
+{{- if hasKey $gpuProfileNames .name }}
+{{- fail (printf "gpu.profiles contains duplicate name %q" .name) }}
+{{- end }}
+{{- if not (trim .displayName) }}
+{{- fail (printf "gpu profile %q displayName must not be blank" .name) }}
+{{- end }}
+{{- if and .workspaceImage (contains "://" .workspaceImage) }}
+{{- fail (printf "gpu profile %q workspaceImage must not contain a URL scheme" .name) }}
+{{- end }}
+{{- $_ := set $gpuProfileNames .name true }}
+{{- if eq .name $.Values.gpu.defaultProfile }}
+{{- $gpuDefaultFound = true }}
+{{- end }}
+{{- end }}
+{{- if and .Values.gpu.defaultProfile (not $gpuDefaultFound) }}
+{{- fail "gpu.defaultProfile must name an entry in gpu.profiles" }}
+{{- end }}
+{{- if and .Values.gpu.enabled (not .Values.gpu.defaultProfile) }}
+{{- fail "gpu.defaultProfile is required when gpu.enabled=true" }}
+{{- end }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -99,6 +122,12 @@ spec:
             {{- end }}
             - name: DEVBOXES_LOG_LEVEL
               value: {{ .Values.controller.logLevel | quote }}
+            - name: DEVBOXES_GPU_ENABLED
+              value: {{ .Values.gpu.enabled | quote }}
+            - name: DEVBOXES_GPU_DEFAULT_PROFILE
+              value: {{ .Values.gpu.defaultProfile | quote }}
+            - name: DEVBOXES_GPU_PROFILES
+              value: {{ .Values.gpu.profiles | toJson | quote }}
             - name: DEVBOXES_INSIGHTS_ENABLED
               value: {{ .Values.insights.enabled | quote }}
             {{- if .Values.insights.enabled }}