Sandbox Policies

A sandbox policy is a YAML configuration that controls what a sandbox can access. It defines which files processes in the sandbox can read and write, which user they run as, which network destinations each binary can reach, and which requests it can send. OpenShell denies anything the policy does not allow.

This page explains how policies work. To try one in a running sandbox, follow Write Your First Sandbox Network Policy. To create and change policies, refer to Manage Sandbox Policies.

What a Policy Controls

A policy file sets version: 1 and has up to five other top-level sections. Each section controls a different part of the sandbox and takes effect at a specific time:

Filesystem, Landlock, and process settings are fixed once the sandbox starts. Network rules and middleware can change while it runs, as described in How Changes Take Effect.

Network rules make up most of a typical policy. OpenShell denies every outbound connection from a sandbox unless a rule in network_policies allows it. Each rule lists the destinations it allows and the binaries that can reach them, and can also restrict the requests those binaries send, for example to allow reading from an API but not writing to it. Network Rules explains how OpenShell evaluates rules and gives examples you can adapt.

The Policy Schema Reference describes every field in each section, and Supervisor Middleware explains how middleware processes traffic.

Where the Active Policy Comes From

Every sandbox runs under a policy, even when you do not supply one. When more than one policy is available, OpenShell uses the first applicable source in this order:

1. A global policy, which a gateway administrator applies to every sandbox.
2. The sandbox’s saved policy. At creation, --policy takes precedence over OPENSHELL_SANDBOX_POLICY. Later policy changes update the saved policy.
3. A policy included in the sandbox image.
4. OpenShell’s restrictive default policy.

An invalid image policy keeps the workload from starting until you repair it. OpenShell does not skip it and use the default.

Base and Effective Policies

The selected sandbox policy is the base policy. Attached providers can contribute additional network rules, for example so that a GitHub provider can reach the GitHub API. The effective policy combines the base policy with those provider rules, and it is the policy the sandbox enforces.

Start edits from the base policy so you do not copy provider-owned rules into your own configuration. Inspect the effective policy when you need to know what the sandbox can reach. Inspect the Current Policy shows both views.

Global Policy

A gateway administrator can apply one policy to every sandbox on the gateway. The global policy replaces each sandbox’s own policy rather than limiting it. While it is active, OpenShell blocks sandbox policy changes and proposal approvals, and suppresses provider-contributed network rules. Deleting the global policy restores normal policy selection and provider rules. Refer to Apply a Global Policy for the commands.

Next Steps

• Use Network Rules to learn how OpenShell evaluates network rules and to adapt examples for common services.
• Use Manage Sandbox Policies to create, update, verify, and roll back policies.
• Use the Policy Prover to check that a policy grants no more access than a boundary you define.
• Use the Policy Advisor to let an agent propose narrow network rules for your review.
• Use the Policy Schema Reference for every field, default, and validation rule.