feat(drivers): inject local sandbox identity

[matthewgrossman]

🏗️ build-from-issue-agent

Summary

Make the Docker and Podman compute drivers choose and inject a validated numeric agent identity at runtime, so OpenShell-managed sandboxes no longer require a baked-in sandbox user or group. The supervisor now presents the same numeric identity and /sandbox home consistently for primary and SSH-launched agent processes.

Related Issue

Closes #2331

Changes

• Docker and Podman default to UID/GID 10001:10001, support operator overrides, validate both values against the policy identity range, and override image/user-supplied identity environment variables.
• The process supervisor sets HOME, USER, and LOGNAME consistently when dropping to a numeric identity.
• Added a shared userless image fixture and Docker/Podman E2E coverage proving the agent identity and workspace remain usable without passwd/group entries.
• Documented the new driver configuration and clarified that image USER is not authoritative for an OpenShell-managed agent.

Deviations from Plan

Local Docker validation completed. Podman is not installed on this development host, so the new Podman E2E target was compiled locally and is left to the repository's rootless Podman CI lane for runtime validation.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated

Tests added:

• Unit: Docker and Podman defaulting, partial overrides, invalid ranges, and protected environment precedence; supervisor numeric identity environment behavior.
• Integration: Docker and Podman feature variants of custom_image compile.
• E2E: docker_sandbox_from_userless_dockerfile passes locally; podman_sandbox_from_userless_image is covered by rootless Podman CI.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

Documentation updated:

• architecture/compute-runtimes.md and architecture/sandbox.md: runtime identity ownership and flow.
• Driver READMEs, gateway configuration reference/sample, and BYOC example: operator configuration and userless image expectations.

[github-actions]

Thank you for your interest in contributing to OpenShell, @matthewgrossman.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words — do not have an AI generate the request.
4. A maintainer will comment /vouch if approved.
5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

[matthewgrossman]

🏗️ build-from-issue-agent

E2E Test Attestation

The local Docker E2E test passed against the committed implementation. Podman is not installed on this development host; the PR adds the equivalent test to the repository's rootless Podman E2E lane.

Field	Value
Commit	98ef34f6
Command	OPENSHELL_E2E_DOCKER_TEST=custom_image mise run e2e:docker
Gateway mode	Docker
Result	✅ All passed

Test Summary

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Tests Executed

• e2e/rust/tests/custom_image.rs::docker_sandbox_from_userless_dockerfile — PASSED

The fixture asserts that the image contains neither a named sandbox account nor UID/GID 10001, then verifies that the managed agent runs as 10001:10001, receives HOME=/sandbox, and can write to that directory.

[github-actions]

Thank you for your interest in contributing to OpenShell, @matthewgrossman.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words — do not have an AI generate the request.
4. A maintainer will comment /vouch if approved.
5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

[elezar]

QUestion: Why is the default not DEFAULT_SANDBOX_UID?

[matthewgrossman]

the idea was to keep all of the resolution within resolve_sandbox_entity, versus defaulting in multiple locations. But I do think that's a bit confusing, I think it's worth updating here IMO

[matthewgrossman]

Updated this so the Docker and Podman configs now use DEFAULT_SANDBOX_UID as a concrete UID default. We keep sandbox_gid optional so that, when it is omitted, it follows the selected UID (for example, a UID-only override of 12345 resolves to 12345:12345). That matches the effective UID/GID fallback behavior in the Kubernetes and VM drivers.

[elezar]

Out of scope for this change, but is annonymous struct embedding possible in rust so that one could group common driver options like these?

[matthewgrossman]

so it looks like to be a non-native feature, but serde has their flatten https://serde.rs/attr-flatten.html

• Clap: #[command(flatten)]
• Serde: #[serde(flatten)]

For example:

struct SandboxIdentityArgs {
    #[arg(long)]
    sandbox_uid: Option<u32>,
    #[arg(long)]
    sandbox_gid: Option<u32>,
}

struct Args {
    #[command(flatten)]
    sandbox_identity: SandboxIdentityArgs,
}

Looks like we do use it in some places:

OpenShell/crates/openshell-ocsf/src/events/base_event.rs

Line 206 in 98ef34f

#[serde(flatten)]

[matthewgrossman]

(thanks for giving an excuse to do an learning-dive on how derive macros work)

so yes this is something we could do, but I wonder if we wait until some amount of these common attributes stabilized in beta+? I mean they're all new to me, so maybe they are stable and I just don't know

[elezar]

Question: Why not something even smaller? Do we need python?

[matthewgrossman]

nope we don't, swapped this to debian bookwork slim

[elezar]

Do these strictly need Docker or Podman drivers? (not for image build).

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2335.docs.buildwithfern.com/openshell