docs(podman): document the openshell.* sandbox container labels as a stable interface

[btrzupek]

Request

Please document the openshell.* labels that the Podman driver puts on sandbox containers as a stable, versioned interface, so that passive inventory and posture tools can list sandboxes without running the CLI or holding gateway credentials.

Context

I maintain a small local tool that inventories the AI software on a workstation and reports how each agent is confined. It lists OpenShell sandboxes read-only from the rootless Podman container listing (GET /libpod/containers/json?all=true, or podman ps -a --format json). It never runs an OpenShell binary, never contacts the gateway and never inspects containers. The documented interfaces (openshell sandbox list -o json and gRPC ListSandboxes) need a binary run or the mTLS client key, so labels are the only passive signal.

Today such a tool has to rely on keys that are not documented, so any release could silently break it.

What I observed (v0.1.1, Podman driver)

These are on both containers of one sandbox (the workload and its supervisor):

• openshell.managed=true
• openshell.ai/sandbox-id
• openshell.ai/sandbox-name
• openshell.ai/sandbox-workspace
• openshell.ai/sandbox-namespace (empty)
• openshell.ai/isolation-role (sandbox or supervisor)
• openshell.ai/caller-driver-config-used
• openshell.ai/runtime-binary-source (a host path)

The workload container also carries openshell.ai/resource-admission-identities.

As far as I can tell, only openshell.ai/managed-by, openshell.ai/gateway-id and openshell.ai/sandbox-workspace are documented, as reserved driver metadata, and the RFC 0011 draft adds sandbox-id, sandbox-name and managed-by. On Podman, openshell.ai/managed-by and openshell.ai/gateway-id are not set; openshell.managed=true is used instead. #2804 discussed aligning that label with Docker and Kubernetes, and was closed as stale.

What would help

1. A short documented list of the labels that identify a sandbox and its containers, with their meaning and stability. A small set would be enough: managed marker, sandbox id, name, workspace, and the container's role (workload or supervisor).
2. The same managed marker on every driver (openshell.ai/managed-by=openshell, as feat(podman): align managed-container labels with Docker and Kubernetes #2804 proposed), or the Podman label documented as an alias.
3. A note in the release notes when any of these change.

Keys such as runtime-binary-source do not need to be part of the contract. Inventory tools only need to find and pair a sandbox's containers.

Thank you for OpenShell. It has been easy to install and study at user level with the Podman driver.

---

Written with Claude Code.