Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions .agents/skills/helm-dev-environment/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,8 +447,19 @@ Use `mise run e2e:kubernetes` for the standard Helm-backed Kubernetes suite.
Set `OPENSHELL_E2E_KUBE_TEST=kubernetes_image_update` to scope the Rust suite to
combined image, command, environment, and metadata updates with retained sandbox,
SSH, and PVC identities. The next start verifies the new argv and environment. This target is
included in both existing Agent Sandbox API-version lanes; unlike the Python
Docker suite, it exercises the driver that supports image updates.
included in both existing Agent Sandbox API-version lanes. Docker separately
supports image-only updates on stopped, opt-in persistent `/sandbox` workspaces;
this Kubernetes lane does not qualify that path. Docker requires locally cached
images, a matching numeric target `USER UID:GID`, and no image-declared volumes.
Do not treat a skipped Docker lane as live image-replacement coverage.

The separate `docker-updates` testkit suite qualifies the full Docker path
through an owned mTLS gateway, including SSH exec, image replacement, restart,
credential-publication repair and deletion. Follow
`tests/suites/features/docker-updates/README.md`; the wrapper's
`OPENSHELL_E2E_DOCKER_IMAGE_UPDATES=1` opts in only its fresh gateway and refuses
an existing endpoint. On Docker Desktop without host networking, select the
documented bridge override rather than changing engine settings.

Image updates default to disabled outside test fixtures. The e2e wrapper opts
in only for a fresh gateway fixture that it owns; set
Expand Down
83 changes: 82 additions & 1 deletion crates/openshell-driver-docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,89 @@ New generations require matching supervisor and sandbox runtime binaries.

## Stop, Start, and Delete

Set `persist_workspace = true` in `[openshell.drivers.docker]` to give newly
created default `/sandbox` workspaces a driver-owned local volume. The setting
defaults to false and does not migrate existing writable-layer workspaces.
Custom working directories and image-declared volumes overlapping `/sandbox`
are rejected when enabled. Initialization prepares the workspace ownership;
it does not copy the image's workspace contents into the volume.

The driver records and rechecks the volume identity and workload UID/GID before
restart, including when external resource admission is disabled. Stop retains
the data. Explicit sandbox deletion removes the owned workspace volume and
reports removal failures. Startup orphan cleanup retains workspace volumes
without a workload; an interrupted create requires explicit recovery/removal.
This option advertises the optional workload update capability. The gateway's
separate `enable_sandbox_updates` setting must also be enabled to accept updates.

Persistence ownership comes from `workspace-storage.json` in the protected
per-sandbox driver directory, bound into the private bootstrap and runtime
descriptor. It records the namespace, sandbox, workload UID/GID and exact volume
identity. Container labels do not select persistent storage or authorize volume
admission, updates or removal. All caller template labels retain their existing
meaning, including generic and Docker-specific workspace label names.

### Stopped Workload Image Updates

The Docker updater implements the existing configuration-update RPC for
image-only changes on stopped, persistent `/sandbox` workspaces. Source and
target images must already be cached locally and declare no image volumes. The
target must declare an explicit numeric `USER UID:GID` matching the recorded
non-root workload identity. Symbolic users/groups, UID-only users, and an absent
`USER` are rejected before replacement; update preflight does not resolve image
accounts. Command and environment changes are unsupported.

The update replaces the stopped workload container while preserving the native
sandbox ID and owned workspace volume. It refreshes the private runtime evidence
for the replacement; it does not change the trusted sandbox or supervisor images.
A private operation record lets the same accepted operation resume after an
interruption. Start refuses an unfinished update. Stop and startup reconciliation
retain its data and runtime resources; explicit Delete removes its owned storage.
Retry through the gateway to finish the accepted update before starting it.
The operation never starts the workload or rolls back workspace data implicitly.

#### Live Driver Integration Test

The opt-in test below uses a real Docker daemon and isolated, uniquely labeled
stopped containers and a workspace volume. It checks numeric/symbolic identity
refusal, A-to-B replacement, retained file bytes, replay, and recovery after an
accepted update loses its source container. Cleanup verifies ownership and never
forces removal. This is driver integration coverage; gateway authorization,
supervisor startup, and authenticated workload operations still require E2E.

From the repository root, prepare the four local test images:

```shell
for version in A B BAD SYMBOLIC; do
case "$version" in
BAD) fixture_user=2000:2000 ;;
SYMBOLIC) fixture_user=other:other ;;
*) fixture_user=1234:1235 ;;
esac
docker build --network=none --build-arg VERSION="$version" \
--build-arg WORKLOAD_USER="$fixture_user" -t "openshell-image-update-test:$version" \
crates/openshell-driver-docker/tests/fixtures/image-update
done

OPENSHELL_DOCKER_UPDATE_IMAGE_A=openshell-image-update-test:A \
OPENSHELL_DOCKER_UPDATE_IMAGE_B=openshell-image-update-test:B \
OPENSHELL_DOCKER_UPDATE_IMAGE_BAD=openshell-image-update-test:BAD \
OPENSHELL_DOCKER_UPDATE_IMAGE_SYMBOLIC=openshell-image-update-test:SYMBOLIC \
cargo test --locked -p openshell-driver-docker --lib \
live_stopped_image_replacement -- --ignored --nocapture
```

The Docker CLI must be on `PATH` and use the same daemon as the SDK. On Docker
Desktop, set `DOCKER_HOST` to the socket reported by `docker context inspect`.

For authenticated gateway/supervisor qualification, including SSH exec,
replacement, gateway restart, interrupted credential-publication repair and
complete API deletion, run the separate
[Docker update testkit suite](../../tests/suites/features/docker-updates/README.md).

Stop terminates the supervisor companion, allowing it 10 seconds to stop the
workload, and stops the workload container without removing it. Docker retains the workload writable layer and attached
workload, and stops the workload container without removing it. Docker retains
the workload writable layer and attached
volumes. Start stages a fresh sandbox bootstrap bundle, restarts that workload,
and creates a new supervisor companion. A durably stopped sandbox stays stopped
across gateway restarts.
Expand Down
Loading
Loading