OpenShell explained: where an AI agent is allowed to act
OpenShell explained: where an AI agent is allowed to act
Trace the sandbox, trusted supervisor and gateway before adopting the project’s security claims
What you will learn
- Start with the boundary
- Separate policy from credentials
- Read the claims at the right level
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 supervisor makes policy decisions outside the workload.
- Providers keep real credentials outside the agent process.
- Security claims remain unverified until tested in your environment.
Start with the boundary
OpenShell runs an autonomous agent inside a sandbox and puts a trusted supervisor outside that workload. The gateway manages sandbox state and access. The architecture document describes an outer network fence that permits the workload to reach only its supervisor.
This matters when an agent can read files, install packages or call APIs. A prompt that asks it to stay safe is not an enforcement boundary. OpenShell’s documented controls operate at file, process and network paths, although this source review has not tested their effectiveness on a live host.
Separate policy from credentials
A policy describes accessible files, processes, destinations and API methods. Providers keep service credentials outside the untrusted workload; the supervisor adds them only to approved outbound requests.
An agent still needs a useful task and a restricted starting policy. The default policy has no outbound network rules, but an image, global policy or attached provider can change the effective result. Inspect the selected policy rather than assuming that no command-line flag means no access.
Read the claims at the right level
The README describes kernel controls and formal checks of proposed policy changes. Those are upstream architecture claims. The pinned source and docs show their intended flow; they do not constitute an independent penetration test or formal proof of a particular deployment.
The rest of this series covers a minimal first run, deployment prerequisites, source paths, cost, operational risks and a bounded adoption decision. A useful pilot begins with one disposable workload and records every permission it receives.
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
Identify the gateway, supervisor and untrusted workload.
- 2
Inspect the active policy before letting an agent call external services.
- 3
Choose a disposable first task with a verifiable final state.
Copy-ready example
agent workload -> sandbox mediation -> trusted supervisor -> approved endpoint
gateway -> policy, identity and lifecycle
provider credential -> supervisor onlyFrequently asked questions
Does an agent see the provider API key?
The pinned architecture says the supervisor stores and injects credentials at approved endpoints rather than exposing them to the agent.
Is an empty network policy guaranteed on first run?
No. Image policy, a global policy or provider rules can affect the effective policy.
Sources
- OpenShell / README.mdSource checked 2026-10-04
- OpenShell / docs/about/architecture.mdxSource checked 2026-10-04
- OpenShell / docs/how-it-works/policies/default-policy.mdxSource checked 2026-10-04
- OpenShell / docs/how-it-works/providers/overview.mdxSource checked 2026-10-04