OpenShell explained: where an AI agent is allowed to act
OpenShell architecture: a request crosses two trust boundaries
Follow a DNS or TCP request from the agent to an approved external endpoint
What you will learn
- Name the actors
- Follow one connection
- Understand failure behavior
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 sandbox identifies the requester, but the supervisor decides.
- The workload should have no direct external network path.
- Runtime differences require separate tests.
Name the actors
The gateway is the control plane. A compute driver starts the workload and a separate trusted supervisor, establishes their protected channel, and checks the runtime fence. The sandbox process lives with the agent and owns its child processes.
The sandbox side reports attempted actions rather than deciding policy. In the documented Linux backend, Landlock limits file access and seccomp user notification stages network operations before the trusted side decides.
Follow one connection
For TCP or DNS, the sandbox identifies the calling executable and sends the request over an authenticated multiplexed channel. The supervisor checks policy, resolves DNS or opens the connection, and injects a provider credential only where allowed.
The outer fence is what makes the mediated path mandatory. Docker and Podman turn workload networking off; Kubernetes relies on its NetworkPolicy; a VM lacks a guest network device. Those different mechanisms need separate deployment tests.
Understand failure behavior
The architecture says launch waits for supervisor confirmation and the agent freezes when the channel drops, with a reconnect window or stopped workload. Each TCP connection has its own stream and backpressure.
These guarantees come from pinned design documentation and selected source files. A reader evaluating a release should test connection loss, denied DNS and unexpected binaries rather than treating the diagram as a certification.
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
Trace an attempted DNS lookup from agent to supervisor.
- 2
Compare runtime-specific outer fences.
- 3
Test denied egress and channel loss on your chosen driver.
Copy-ready example
agent TCP/DNS -> sandbox seccomp observation
sandbox -> authenticated channel -> supervisor policy check
supervisor -> optional credential -> external destinationFrequently asked questions
Where does policy enforcement happen?
Filesystem and process controls act in the workload; the trusted supervisor checks mediated network and credential use.
What if the supervisor becomes unreachable?
The pinned architecture describes a freeze and reconnect window, followed by a stopped workload if recovery fails.
Sources
- OpenShell / docs/about/architecture.mdxSource checked 2026-10-04
- OpenShell / docs/how-it-works/sandboxes/overview.mdxSource checked 2026-10-04
- OpenShell / crates/openshell-sandbox-backend/src/mediation.rsSource checked 2026-10-04