Architecture and boundaries
Coordination inside.
Policy around it.
ToolsEnabled Fleet and OpenShell have different jobs. The distinction matters: your agents share a workspace, and OpenShell bounds access beyond it.
Work in progress · BetaWho enforces what
OpenShell applies sandbox policy to the official clients and their workers. Fleet manages the shared work state and cooperative runtime controls inside that sandbox.
| Responsibility | OpenShell | Fleet |
|---|---|---|
| Filesystem access | Enforces the sandbox’s allowed paths. | Coordinates mediated edits against recorded file observations. |
| Network access | Applies rules for programs and endpoints. | Explains observed denials and proposes scoped access. |
| Credentials | Holds provider-managed credentials and resolves placeholders for their bound endpoints. | Uses the provider’s existing mechanisms; never approves new access. |
| Tasks and delegation | Bounds every process in the sandbox. | Shares tasks, memory, asks, and a bounded worker tree. |
Only OpenShell’s limits are a security boundary. Fleet’s permissions, worker limits, and terminal controls are product rules among cooperating agents.
Credentials follow the provider flow.
In the documented Codex provider setup, OpenShell’s gateway holds and refreshes the sign-in. The sandbox receives placeholders; the real credential is inserted on requests to the provider’s bound endpoints.
Claude Code is different in the current build. Its own sign-in is stored inside the sandbox and is readable by processes sharing that user. This setup does not claim that every credential stays outside the sandbox.
Optional model endpoints also use OpenShell providers. Their API keys belong in the provider, on the host.
An agent can ask for access.
Fleet can read a recorded denial, explain it, and submit a narrow network-access proposal. You inspect and approve or reject the proposal with OpenShell on the host. A denial alone does not establish that the requested access is appropriate for your task.
- The sandbox refuses an action outside its policy.
- Fleet explains the observed denial.
- The agent can submit a scoped proposal through OpenShell’s advisor.
- You decide through OpenShell, outside the sandbox.
Fleet cannot approve a proposal or edit the sandbox policy on your behalf. OpenShell determines how any approved rule is applied.
Know the limits of this build.
- Workers share one sandbox and user. They are not isolated from one another.
- Byte coordination covers mediated operations. Native file tools and external writers can bypass it; fresh bytes do not establish semantic correctness.
- The work record, actor labels and the optional signed audit run as the same sandbox user as the agents. They are not tamper-proof against those agents.
- Some filesystem refusals do not appear in the advisor’s denial history. Not every block can be explained by the policy tools.
- If OpenShell drafts its own rule for the same host and port at the same moment, it can replace an agent’s network-access request. If an approval does not take effect, ask the agent to request access again.
- When Codex runs against a custom Responses backend, the model sees no MCP tools. This is an upstream Codex issue (openai/codex#33263).
- Uninstall now works through folder handles it keeps open and refuses changed paths. Like all lifecycle commands, it assumes no other program running as the same user changes those files during the operation.
- Uninstall does not delete state yet; use
--keep-state. A fresh setup refuses a scope whose state was kept: use upgrade, or a new scope. - Changed or unexpected runtime contents, and interrupted install or removal work, are kept with their evidence for review.
- A Claude Code profile that already has settings needs a separately reviewed path; the install expects a fresh Claude profile. Tested versions: OpenShell 0.1.2, Codex 0.158.0 and Claude Code 2.1.284.
- Provider sign-in stays with each provider’s CLI. There is no native Windows runtime installer.
- Uninstall recognizes an already-removed Claude Code registration only for Claude Code 2.1.284. With other versions it keeps the runtime and prints
claude mcp remove --scope user toolsenabledfor you to run. - Two setups have not been tested with real accounts: a second interactive Codex session in the same sandbox, and a signed-in nested worker tree.
- Alternative model endpoints have been tested with local stand-in servers, not every named hosted provider.
- The release archive runs inside a Linux x86-64 OpenShell sandbox. On a Windows host, the OpenShell CLI runs in WSL 2 and the local gateway uses Docker Desktop’s Linux engine; there is no native Windows runtime. On Windows, testing so far covers WSL 2: beta 3’s two-hour soak passed (32 rounds, 0 failures); a Windows-hosted hand-test pair and real-provider sessions are still in progress. Windows 11 has not been tested. See the Windows (WSL 2) setup guide, and the release notes for current results.
For OpenShell’s architecture and current support, consult NVIDIA’s OpenShell documentation.