User Story
As a developer or team administrator using Apple Silicon Macs, I want to install OpenShell and run an agent in a sandbox through a documented setup, so that I can use OpenShell's protections in everyday development and reproduce the setup across my team.
Problem Statement
OpenShell's MicroVM backend already runs Linux workloads on macOS without requiring a separate container runtime. We verified a real agent task, filesystem and network denials, and workspace persistence across stop/start on v0.1.2.
Getting to that working state still required manual repair and configuration investigation. The downloaded VM driver needed local signing. A gateway with working listener TLS but no sandbox launch-token signer prepared images before reporting VM sandbox launch authentication is required; #3949 documents that configuration and reproduction. A slow first setup exhausted the provisioning deadline, and the reported user/group did not match those running the sandbox process. A failed creation attempt left temporary image data that required manual cleanup.
These gaps make a working backend difficult to turn into a repeatable installation and operating workflow. Existing issues and proposed fixes cover parts of the problem; this proposal defines the user experience they should deliver together.
Impact / Why This Matters
Developers must understand runtime packaging and gateway configuration before they can evaluate the sandbox itself. Team administrators must reproduce local workarounds, supply required filesystem tools, and determine which user and group actually run the workload. Failed setup consumes time and can leave large temporary files behind.
Closing these gaps would give users of the MicroVM backend a repeatable setup, useful failure messages, and reliable cleanup after failed or cancelled creation.
Proposed Design
Complete and qualify a macOS workflow around the existing MicroVM backend:
- Install: the documented installation includes its required dependencies and works without repairing downloaded executables.
- Check readiness: unsupported systems, missing dependencies, and incomplete gateway configuration produce errors that explain how to fix the problem before a large image download.
- Prepare: first-time image preparation has its own documented deadline, separate from policy admission and repair.
- Inspect: users can see the identity running the workload. Requests that conflict with the driver's resolved user or group receive clear errors.
- Cancel and retry: failed or cancelled creation reclaims inactive staging without deleting active sandbox data or valid shared image data.
Acceptance Criteria
Alternatives Considered
Fixing each defect independently remains necessary. A shared workflow and acceptance checklist would make it possible to verify that those fixes compose into a usable release.
Existing container-backed deployments serve users who choose those runtimes. This proposal completes the available MicroVM option. Adding another runtime or native macOS process support is a separate backend decision.
Agent Investigation
No response
Checklist
User Story
As a developer or team administrator using Apple Silicon Macs, I want to install OpenShell and run an agent in a sandbox through a documented setup, so that I can use OpenShell's protections in everyday development and reproduce the setup across my team.
Problem Statement
OpenShell's MicroVM backend already runs Linux workloads on macOS without requiring a separate container runtime. We verified a real agent task, filesystem and network denials, and workspace persistence across stop/start on v0.1.2.
Getting to that working state still required manual repair and configuration investigation. The downloaded VM driver needed local signing. A gateway with working listener TLS but no sandbox launch-token signer prepared images before reporting
VM sandbox launch authentication is required; #3949 documents that configuration and reproduction. A slow first setup exhausted the provisioning deadline, and the reported user/group did not match those running the sandbox process. A failed creation attempt left temporary image data that required manual cleanup.These gaps make a working backend difficult to turn into a repeatable installation and operating workflow. Existing issues and proposed fixes cover parts of the problem; this proposal defines the user experience they should deliver together.
Impact / Why This Matters
Developers must understand runtime packaging and gateway configuration before they can evaluate the sandbox itself. Team administrators must reproduce local workarounds, supply required filesystem tools, and determine which user and group actually run the workload. Failed setup consumes time and can leave large temporary files behind.
Closing these gaps would give users of the MicroVM backend a repeatable setup, useful failure messages, and reliable cleanup after failed or cancelled creation.
Proposed Design
Complete and qualify a macOS workflow around the existing MicroVM backend:
Acceptance Criteria
Alternatives Considered
Fixing each defect independently remains necessary. A shared workflow and acceptance checklist would make it possible to verify that those fixes compose into a usable release.
Existing container-backed deployments serve users who choose those runtimes. This proposal completes the available MicroVM option. Adding another runtime or native macOS process support is a separate backend decision.
Agent Investigation
No response
Checklist