chore: merge main into approval loop

Signed-off-by: Alexander Watson <zredlined@gmail.com>

Author: zredlined

.agents/skills/build-from-issue/SKILL.md

@@ -148,7 +148,8 @@ In the prompt, instruct the reviewer to:
    - **Medium**: Multiple files/components, some design decisions, but well-scoped
    - **High**: Cross-cutting changes, architectural decisions needed, significant unknowns
 8. Call out risks, unknowns, and decisions that need stakeholder input.
-9. Assess **LSM compatibility** — if the change touches process identity, `/proc` filesystem access, binary execution, or inter-process visibility, flag whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. In particular, tests that fork+exec into system binaries will fail on SELinux-enforcing hosts due to cross-label `/proc/<pid>/exe` access restrictions.
+9. Assess **gateway config documentation impact** — if the change adds, removes, renames, or changes defaults for gateway TOML keys or driver-specific config options, the plan must include an update to `docs/reference/gateway-config.mdx`. If the change is surfaced through Helm or a compute-driver overview, also include `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment docs.
+10. Assess **LSM compatibility** — if the change touches process identity, `/proc` filesystem access, binary execution, or inter-process visibility, flag whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. In particular, tests that fork+exec into system binaries will fail on SELinux-enforcing hosts due to cross-label `/proc/<pid>/exe` access restrictions.
 
 ### A2: Post the Plan Comment
 
@@ -436,6 +437,13 @@ Review the documentation requirements in `AGENTS.md` and update any affected
 docs as part of the implementation. Keep documentation changes scoped to the
 behavior or subsystem that changed.
 
+If the implementation changes gateway TOML parsing, `[openshell.gateway]`
+fields, `[openshell.drivers.<name>]` fields, driver config defaults, or Helm
+rendering of `gateway.toml`, update `docs/reference/gateway-config.mdx` in the
+same branch. If the change affects user-facing compute-driver setup, also
+update `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment
+page.
+
 ### Step 12: Commit and Push
 
 Commit all changes using conventional commit format. The `<type>` comes from the issue type in the plan:

.agents/skills/create-github-pr/SKILL.md

@@ -15,6 +15,15 @@ Create pull requests on GitHub using the `gh` CLI.
 
 ## Before Creating a PR
 
+### Check Config Documentation
+
+If the branch changes gateway TOML parsing, `[openshell.gateway]` fields,
+`[openshell.drivers.<name>]` fields, driver config defaults, or Helm rendering
+of `gateway.toml`, verify that `docs/reference/gateway-config.mdx` is updated
+in the same branch. If the change affects user-facing compute-driver setup,
+also update `docs/reference/sandbox-compute-drivers.mdx` or the relevant
+deployment docs.
+
 ### Run Pre-commit Checks
 
 Run the local pre-commit task before opening a PR:

.agents/skills/create-spike/SKILL.md

@@ -91,9 +91,11 @@ The prompt to the reviewer **must** instruct it to:
 
 9. **Check architecture docs** in the `architecture/` directory for relevant documentation about the affected subsystems.
 
-10. **Assess Linux Security Module (LSM) impact.** If the change involves process identity, `/proc` filesystem access, file labeling, binary execution, or inter-process visibility, call out whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. For example: reading `/proc/<pid>/exe` across an SELinux domain boundary returns ENOENT, not EACCES. Tests that fork+exec into system binaries (different SELinux label) will fail on enforcing hosts. Flag any LSM-sensitive code paths and recommend mitigations.
+10. **Assess gateway config documentation impact.** If the change would add, remove, rename, or change defaults for gateway TOML keys or driver-specific config options, call out that `docs/reference/gateway-config.mdx` must be updated. If the change is surfaced through Helm or compute-driver setup docs, call out the relevant deployment or compute-driver docs too.
 
-11. **Determine the issue type:** `feat`, `fix`, `refactor`, `chore`, `perf`, or `docs`.
+11. **Assess Linux Security Module (LSM) impact.** If the change involves process identity, `/proc` filesystem access, file labeling, binary execution, or inter-process visibility, call out whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. For example: reading `/proc/<pid>/exe` across an SELinux domain boundary returns ENOENT, not EACCES. Tests that fork+exec into system binaries (different SELinux label) will fail on enforcing hosts. Flag any LSM-sensitive code paths and recommend mitigations.
+
+12. **Determine the issue type:** `feat`, `fix`, `refactor`, `chore`, `perf`, or `docs`.
 
 ### What makes a good investigation prompt
 

.agents/skills/update-docs/SKILL.md

@@ -34,7 +34,7 @@ git log -50 --oneline --no-merges
 Filter to commits that are likely to affect docs. Look for these signals:
 
 1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates.
-2. **Files changed**: Changes to `crates/openshell-cli/`, `python/`, `proto/`, `deploy/`, or policy-related code are high-signal.
+2. **Files changed**: Changes to `crates/openshell-cli/`, `python/`, `proto/`, `deploy/`, gateway config parsing, driver config structs, or policy-related code are high-signal.
 3. **Ignore**: Changes limited to `tests/`, `e2e/`, `.github/`, `tasks/`, or internal-only modules.
 
 ```bash
@@ -52,6 +52,10 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi
 | `crates/openshell-cli/` (sandbox commands) | `docs/sandboxes/manage-sandboxes.mdx` |
 | `crates/openshell-cli/` (provider commands) | `docs/sandboxes/manage-providers.mdx` |
 | `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry |
+| `crates/openshell-server/src/config_file.rs` or gateway TOML parsing | `docs/reference/gateway-config.mdx` |
+| `crates/openshell-server/src/cli.rs` gateway config merge/default behavior | `docs/reference/gateway-config.mdx` |
+| `crates/openshell-driver-*/` config structs or driver defaults | `docs/reference/gateway-config.mdx`, `docs/reference/sandbox-compute-drivers.mdx` |
+| `deploy/helm/openshell/templates/gateway-config.yaml` | `docs/reference/gateway-config.mdx`, `docs/reference/sandbox-compute-drivers.mdx`, Helm docs if values change |
 | Proxy or policy code | `docs/sandboxes/policies.mdx`, `docs/reference/policy-schema.mdx` |
 | Inference code | `docs/inference/configure.mdx` |
 | `python/` (SDK changes) | `docs/reference/` or `docs/get-started/quickstart.mdx` |

.github/actions/release-helm-oci/action.yml

@@ -71,6 +71,14 @@ runs:
           exit 1
         fi
 
+    - name: Build chart dependencies
+      env:
+        CHART_DIR: ${{ steps.prep.outputs.chart_dir }}
+      shell: bash
+      run: |
+        set -euo pipefail
+        helm dependency build "${CHART_DIR}"
+
     - name: Package Helm chart
       env:
         CHART_DIR: ${{ steps.prep.outputs.chart_dir }}

.github/workflows/e2e-test.yml

@@ -40,6 +40,10 @@ jobs:
           - suite: rust-podman
             cmd: "mise run --no-deps --skip-deps e2e:podman"
             apt_packages: "openssh-client podman"
+          - suite: rust-podman-rootless
+            cmd: "mise run --no-deps --skip-deps e2e:podman:rootless"
+            apt_packages: "openssh-client podman uidmap"
+            rootless: true
     container:
       image: ghcr.io/nvidia/openshell/ci:latest
       credentials:
@@ -72,14 +76,48 @@ jobs:
         run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
 
       - name: Log in to GHCR with Podman
-        if: matrix.suite == 'rust-podman'
+        if: startsWith(matrix.suite, 'rust-podman')
         run: echo "${{ secrets.GITHUB_TOKEN }}" | podman login ghcr.io -u "${{ github.actor }}" --password-stdin
 
+      - name: Set up rootless Podman user
+        if: matrix.rootless
+        run: |
+          useradd -m openshell-test
+          echo "openshell-test:100000:65536" >> /etc/subuid
+          echo "openshell-test:100000:65536" >> /etc/subgid
+          mkdir -p "/run/user/$(id -u openshell-test)"
+          chown openshell-test: "/run/user/$(id -u openshell-test)"
+          chmod 700 "/run/user/$(id -u openshell-test)"
+          chown -R openshell-test: .
+          for dir in /root/.cargo /root/.rustup /root/.local/share/mise /opt/mise; do
+            [ -d "$dir" ] && chmod -R a+rX "$dir"
+          done
+
       - name: Install Python dependencies and generate protobuf stubs
         if: matrix.suite == 'python'
         run: uv sync --frozen && mise run --no-deps python:proto
 
       - name: Run tests
         env:
           OPENSHELL_SUPERVISOR_IMAGE: ${{ format('ghcr.io/nvidia/openshell/supervisor:{0}', inputs.image-tag) }}
-        run: ${{ matrix.cmd }}
+          E2E_CMD: ${{ matrix.cmd }}
+        run: |
+          if [ "${{ matrix.rootless }}" = "true" ]; then
+            TESTUID="$(id -u openshell-test)"
+            runuser -u openshell-test -- env \
+              XDG_RUNTIME_DIR="/run/user/${TESTUID}" \
+              HOME="/home/openshell-test" \
+              PATH="/root/.cargo/bin:/opt/mise/shims:/opt/mise/bin:${PATH}" \
+              CARGO_HOME="/root/.cargo" \
+              RUSTUP_HOME="/root/.rustup" \
+              OPENSHELL_SUPERVISOR_IMAGE="${OPENSHELL_SUPERVISOR_IMAGE}" \
+              OPENSHELL_REGISTRY="${OPENSHELL_REGISTRY}" \
+              OPENSHELL_REGISTRY_HOST="${OPENSHELL_REGISTRY_HOST}" \
+              OPENSHELL_REGISTRY_USERNAME="${OPENSHELL_REGISTRY_USERNAME}" \
+              OPENSHELL_REGISTRY_PASSWORD="${OPENSHELL_REGISTRY_PASSWORD}" \
+              IMAGE_TAG="${IMAGE_TAG}" \
+              MISE_GITHUB_TOKEN="${MISE_GITHUB_TOKEN}" \
+              bash -c "${E2E_CMD}"
+          else
+            ${E2E_CMD}
+          fi

.gitignore

@@ -187,6 +187,9 @@ rootfs/
 # Docker build artifacts (image tarballs, packaged helm charts)
 deploy/docker/.build/
 
+# Helm subchart tarballs (regenerated by `helm dependency build`)
+deploy/helm/openshell/charts/
+
 # SBOM generated output (JSON, CSV) — release artifacts, not committed
 deploy/sbom/output/
 

.python-version

@@ -1 +1 @@
-3.13.12
+3.14.5

AGENTS.md

@@ -190,6 +190,7 @@ ocsf_emit!(event);
 
 - When making changes, update the relevant documentation in the `architecture/` directory.
 - When changes affect user-facing behavior, update the relevant published docs pages under `docs/` and navigation in `docs/index.yml`.
+- When changing gateway TOML fields, driver-specific config options, config defaults, or Helm rendering of `gateway.toml`, update `docs/reference/gateway-config.mdx` in the same branch.
 - `fern/` contains the Fern site config, components, preview workflow inputs, and publish settings.
 - Follow the docs style guide in [docs/CONTRIBUTING.mdx](docs/CONTRIBUTING.mdx): active voice, minimal formatting, no filler introductions, `shell` fences for copyable commands, and no duplicate body H1.
 - Fern PR previews run through `.github/workflows/branch-docs.yml`, and production publish runs through the `publish-fern-docs` job in `.github/workflows/release-tag.yml`.

crates/openshell-cli/src/run.rs

@@ -1888,11 +1888,11 @@ pub async fn sandbox_create(
         .into_diagnostic()?
         .into_inner();
 
-    let mut last_phase = sandbox.phase;
+    let mut last_phase = sandbox.phase();
     let mut last_error_reason = String::new();
     let mut last_condition_message = ready_false_condition_message(sandbox.status.as_ref());
     // Track whether we have seen a non-Ready phase during the watch.
-    let mut saw_non_ready = SandboxPhase::try_from(sandbox.phase) != Ok(SandboxPhase::Ready);
+    let mut saw_non_ready = SandboxPhase::try_from(sandbox.phase()) != Ok(SandboxPhase::Ready);
     let provision_timeout = Duration::from_secs(
         std::env::var("OPENSHELL_PROVISION_TIMEOUT")
             .ok()
@@ -1945,8 +1945,8 @@ pub async fn sandbox_create(
         let evt = item.into_diagnostic()?;
         match evt.payload {
             Some(openshell_core::proto::sandbox_stream_event::Payload::Sandbox(s)) => {
-                let phase = SandboxPhase::try_from(s.phase).unwrap_or(SandboxPhase::Unknown);
-                last_phase = s.phase;
+                let phase = SandboxPhase::try_from(s.phase()).unwrap_or(SandboxPhase::Unknown);
+                last_phase = s.phase();
                 if let Some(message) = ready_false_condition_message(s.status.as_ref()) {
                     last_condition_message = Some(message);
                 }
@@ -2507,7 +2507,7 @@ pub async fn sandbox_get(
     };
     println!("  {} {}", "Id:".dimmed(), id);
     println!("  {} {}", "Name:".dimmed(), name);
-    println!("  {} {}", "Phase:".dimmed(), phase_name(sandbox.phase));
+    println!("  {} {}", "Phase:".dimmed(), phase_name(sandbox.phase()));
     println!(
         "  {} {}",
         "Resource version:".dimmed(),
@@ -2591,11 +2591,11 @@ pub async fn sandbox_exec_grpc(
         .ok_or_else(|| miette::miette!("sandbox not found"))?;
 
     // Verify the sandbox is ready before issuing the exec.
-    if SandboxPhase::try_from(sandbox.phase) != Ok(SandboxPhase::Ready) {
+    if SandboxPhase::try_from(sandbox.phase()) != Ok(SandboxPhase::Ready) {
         return Err(miette::miette!(
             "sandbox '{}' is not ready (phase: {}); wait for it to reach Ready state",
             name,
-            phase_name(sandbox.phase)
+            phase_name(sandbox.phase())
         ));
     }
 
@@ -2803,11 +2803,11 @@ async fn fetch_ready_sandbox_for_forward(
         .sandbox
         .ok_or_else(|| miette::miette!("sandbox '{name}' not found"))?;
 
-    if SandboxPhase::try_from(sandbox.phase) != Ok(SandboxPhase::Ready) {
+    if SandboxPhase::try_from(sandbox.phase()) != Ok(SandboxPhase::Ready) {
         return Err(miette::miette!(
             "sandbox '{}' is no longer ready (phase: {}); stopping service forward",
             name,
-            phase_name(sandbox.phase)
+            phase_name(sandbox.phase())
         ));
     }
 
@@ -3251,8 +3251,8 @@ pub async fn sandbox_list(
 
     // Print rows
     for sandbox in sandboxes {
-        let phase = phase_name(sandbox.phase);
-        let phase_colored = match SandboxPhase::try_from(sandbox.phase) {
+        let phase = phase_name(sandbox.phase());
+        let phase_colored = match SandboxPhase::try_from(sandbox.phase()) {
             Ok(SandboxPhase::Ready) => phase.green().to_string(),
             Ok(SandboxPhase::Error) => phase.red().to_string(),
             Ok(SandboxPhase::Provisioning) => phase.yellow().to_string(),
@@ -3280,8 +3280,8 @@ fn sandbox_to_json(sandbox: &Sandbox) -> serde_json::Value {
         "labels": labels,
         "resource_version": meta.map_or(0, |m| m.resource_version),
         "created_at": format_epoch_ms(meta.map_or(0, |m| m.created_at_ms)),
-        "phase": phase_name(sandbox.phase),
-        "current_policy_version": sandbox.current_policy_version,
+        "phase": phase_name(sandbox.phase()),
+        "current_policy_version": sandbox.current_policy_version(),
     })
 }
 
@@ -7727,15 +7727,14 @@ mod tests {
         let status = SandboxStatus {
             sandbox_name: "gpu".to_string(),
             agent_pod: "gpu-pod".to_string(),
-            agent_fd: String::new(),
-            sandbox_fd: String::new(),
             conditions: vec![SandboxCondition {
                 r#type: "Ready".to_string(),
                 status: "False".to_string(),
                 reason: "Unschedulable".to_string(),
                 message: "Another GPU sandbox may already be using the available GPU.".to_string(),
                 last_transition_time: String::new(),
             }],
+            ..Default::default()
         };
 
         assert_eq!(
@@ -7749,15 +7748,14 @@ mod tests {
         let status = SandboxStatus {
             sandbox_name: "gpu".to_string(),
             agent_pod: "gpu-pod".to_string(),
-            agent_fd: String::new(),
-            sandbox_fd: String::new(),
             conditions: vec![SandboxCondition {
                 r#type: "Scheduled".to_string(),
                 status: "True".to_string(),
                 reason: "Scheduled".to_string(),
                 message: "Sandbox scheduled".to_string(),
                 last_transition_time: String::new(),
             }],
+            ..Default::default()
         };
 
         assert!(ready_false_condition_message(Some(&status)).is_none());