OpenShell explained: where an AI agent is allowed to act
Deploying OpenShell: runtime fences, gateway and release matching
Plan a deployment around the trusted supervisor and the workload’s only network path
What you will learn
- Pick a supported runtime
- Pin the control plane
- Define recovery before exposing agents
Before you start
- One disposable workload and a supported compute runtime
- Authority to inspect policy and provider configuration
Turn the documented controls into a small reviewable operational report
Key takeaways
- The driver builds the fence; the supervisor applies policy.
- Kubernetes needs an enforced NetworkPolicy.
- Matched releases reduce ambiguous compatibility failures.
Pick a supported runtime
The architecture lists Docker, Podman, Kubernetes and VM backends with different channel transports. Docker and Podman use a driver-owned Unix socket; Kubernetes uses a private service with mutual TLS; VM deployments use vsock.
The sandbox workload must not gain direct egress when you move between runtimes. The compute driver constructs the fence, while the supervisor still decides which mediated request is allowed. Test that boundary on the exact runtime you deploy.
Pin the control plane
The gateway manages lifecycle, policy, providers and sessions. Record its image or binary release alongside CLI, sandbox runtime and SDK versions. The support matrix distinguishes stable, prerelease and dev artifacts and recommends stable for production.
For Kubernetes, the README calls out Helm deployment and an enforced NetworkPolicy. A Helm release that starts pods is not proof that the workload can reach only its supervisor; test denied direct egress and allowed mediated egress.
Define recovery before exposing agents
Back up policies and gateway state, write down how to revoke a provider and stop a sandbox, and keep a rollback path for both control plane and runtime images. Check that an interrupted supervisor connection freezes or stops work as the architecture describes.
This is a deployment checklist, not a claim that a particular cluster is secure. No container, VM or Kubernetes installation was run for this series.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose a supported driver and match release artifacts.
- 2
Verify the workload’s direct egress is denied on that runtime.
- 3
Test provider revocation, restart and rollback before shared use.
Copy-ready example
release: pinned-stable
gateway: same-release
sandbox_runtime: same-release
compute_driver: supported-and-tested
direct_egress: denied
provider_revocation: testedFrequently asked questions
Can I rely on a running Kubernetes pod as proof of isolation?
No. Verify NetworkPolicy enforcement and the mediated-only network path.
Does the SDK install the CLI or gateway?
No. The README says SDKs connect to an existing gateway.
Sources
- OpenShell / README.mdSource checked 2026-10-04
- OpenShell / docs/about/architecture.mdxSource checked 2026-10-04
- OpenShell / docs/about/support-matrix.mdxSource checked 2026-10-04
- OpenShell / docs/how-it-works/gateways/overview.mdxSource checked 2026-10-04
- OpenShell / docs/how-it-works/sandboxes/overview.mdxSource checked 2026-10-04