OpenShell explained: where an AI agent is allowed to act
Reading OpenShell source: policy updates, prover and mediation
Use three small source entry points instead of treating the whole Rust workspace as one security module
What you will learn
- Start at the CLI request
- Read what the prover models
- Inspect the transport boundary
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
- CLI validation and runtime enforcement are different stages.
- Prover conclusions depend on its policy model.
- Transport framing is not an authorization decision.
Start at the CLI request
`crates/openshell-cli/src/policy_update.rs` builds a policy-update plan and rejects incompatible argument combinations. For example, appending endpoint rules and L7 allow or deny methods in one request is rejected.
That validation is a useful source entry point, but it does not by itself prove the gateway accepted or enforced the result. Trace the submitted policy into the gateway and compare the active effective policy after an update.
Read what the prover models
`crates/openshell-prover/src/policy.rs` represents endpoints, allowed methods, readable paths and binary-to-endpoint pairs. The documented prover asks whether a proposed policy expands sensitive reach.
A model can only reason over conditions represented in it. Check parser errors, ambiguity and runtime-specific paths before relying on an approval result. This review reads code and docs; it does not run the prover against a fixture.
Inspect the transport boundary
`crates/openshell-sandbox-backend/src/mediation.rs` defines JSON frame encoding and bounded reads for mediated requests. The architecture explains the authenticated channel connecting sandbox and supervisor.
Framing code is one layer of the boundary. Review caller identity, channel authentication and the outer fence alongside it; a valid JSON frame alone says nothing about whether an action was authorized.
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
Read CLI validation and note rejected argument pairs.
- 2
Trace the policy model and identify what it can prove.
- 3
Follow mediation frames to the trusted decision point.
Copy-ready example
CLI args -> update plan -> gateway policy
policy -> prover model -> review finding
sandbox frame -> supervisor -> authorizationFrequently asked questions
Does parsing a policy mean it is active?
No. Inspect the gateway response and the effective policy after application.
Did this article execute the prover?
No. It reviewed fixed source and documented behavior only.
Sources
- OpenShell / crates/openshell-cli/src/policy_update.rsSource checked 2026-10-04
- OpenShell / crates/openshell-prover/src/policy.rsSource checked 2026-10-04
- OpenShell / crates/openshell-sandbox-backend/src/mediation.rsSource checked 2026-10-04
- OpenShell / docs/about/architecture.mdxSource checked 2026-10-04