> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/openshell/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server.

# Sandbox Policies

> Understand what sandbox policies control and where a sandbox's policy comes from.

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](/tutorials/first-network-policy). To
create and change policies, refer to [Manage Sandbox Policies](/how-it-works/policies/manage-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:

| Section               | Controls                                                                                         | Enforced by                                      | Takes effect            |
| --------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ----------------------- |
| `filesystem_policy`   | Paths that sandbox processes can read, or read and write.                                        | Landlock LSM in the kernel.                      | At sandbox startup.     |
| `landlock`            | Whether the sandbox still starts, without your filesystem rules, if OpenShell cannot apply them. | Sandbox runtime.                                 | At sandbox startup.     |
| `process`             | User and group that sandbox processes run as.                                                    | Docker and Podman, when they create the sandbox. | At sandbox creation.    |
| `network_policies`    | Destinations each binary can reach, and the requests it can send.                                | Sandbox network proxy.                           | While the sandbox runs. |
| `network_middlewares` | Additional inspection, transformation, or blocking of traffic that network rules allow.          | Sandbox network proxy.                           | While the sandbox runs. |

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](/how-it-works/policies/manage-policies#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](/how-it-works/policies/network-rules) explains how OpenShell evaluates
rules and gives examples you can adapt.

The [Policy Schema Reference](/how-it-works/policies/schema) describes every
field in each section, and [Supervisor Middleware](/extensibility/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](/how-it-works/policies/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](/how-it-works/policies/manage-policies#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](/how-it-works/policies/manage-policies#apply-a-global-policy) for the
commands.

## Next Steps

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