> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Schema Reference

> Complete field reference for the sandbox policy YAML, including static and dynamic sections.

# Policy schema reference

Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is **static** (locked at sandbox creation) or **dynamic** (hot-reloadable on a running sandbox).

## Top-level structure

A policy YAML file contains the following top-level fields:

```yaml theme={null}
version: 1
filesystem_policy: { ... }
landlock: { ... }
process: { ... }
network_policies: { ... }
```

| Field               | Type    | Required | Category | Description                                                |
| ------------------- | ------- | -------- | -------- | ---------------------------------------------------------- |
| `version`           | integer | Yes      | —        | Policy schema version. Must be `1`.                        |
| `filesystem_policy` | object  | No       | Static   | Controls which directories the agent can read and write.   |
| `landlock`          | object  | No       | Static   | Configures Landlock LSM enforcement behavior.              |
| `process`           | object  | No       | Static   | Sets the user and group the agent process runs as.         |
| `network_policies`  | map     | No       | Dynamic  | Declares which binaries can reach which network endpoints. |

**Static** fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. **Dynamic** fields can be updated on a running sandbox with `openshell policy set` and take effect without restarting.

## `version`

<ParamField body="version" type="integer" required>
  Schema version number. Currently must be `1`.
</ParamField>

## `filesystem_policy`

**Category:** Static

Controls filesystem access inside the sandbox. Paths not listed in either `read_only` or `read_write` are inaccessible.

<ParamField body="filesystem_policy.include_workdir" type="boolean">
  When `true`, automatically adds the agent's working directory to `read_write`.
</ParamField>

<ParamField body="filesystem_policy.read_only" type="string[]">
  Paths the agent can read but not modify. Typically system directories like `/usr`, `/lib`, `/etc`.
</ParamField>

<ParamField body="filesystem_policy.read_write" type="string[]">
  Paths the agent can read and write. Typically `/sandbox` (working directory) and `/tmp`.
</ParamField>

### Validation constraints

* Every path must be absolute (start with `/`).
* Paths must not contain `..` traversal components. The server normalizes paths before storage but rejects policies where traversal would escape the intended scope.
* Read-write paths must not be overly broad — `/` alone is rejected.
* Each individual path must not exceed 4096 characters.
* The combined total of `read_only` and `read_write` paths must not exceed 256.

<Warning>
  Policies that violate these constraints are rejected with `INVALID_ARGUMENT` at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default.
</Warning>

```yaml theme={null}
filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /etc
  read_write:
    - /sandbox
    - /tmp
    - /dev/null
```

## `landlock`

**Category:** Static

Configures [Landlock LSM](https://docs.kernel.org/security/landlock.html) enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow.

<ParamField body="landlock.compatibility" type="string" default="best_effort">
  How OpenShell handles kernel ABI differences.

  | Value              | Behavior                                                   |
  | ------------------ | ---------------------------------------------------------- |
  | `best_effort`      | Uses the highest Landlock ABI the host kernel supports.    |
  | `hard_requirement` | Fails sandbox creation if the required ABI is unavailable. |
</ParamField>

```yaml theme={null}
landlock:
  compatibility: best_effort
```

## `process`

**Category:** Static

Sets the OS-level identity for the agent process inside the sandbox.

<ParamField body="process.run_as_user" type="string" default="sandbox">
  The user name or UID the agent process runs as.
</ParamField>

<ParamField body="process.run_as_group" type="string" default="sandbox">
  The group name or GID the agent process runs as.
</ParamField>

<Warning>
  Neither `run_as_user` nor `run_as_group` may be set to `root` or `0`. Policies that request root process identity are rejected at creation or update time.
</Warning>

```yaml theme={null}
process:
  run_as_user: sandbox
  run_as_group: sandbox
```

## `network_policies`

**Category:** Dynamic

A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier; the `name` field inside the entry is the display name used in logs.

### Network policy entry

<ParamField body="network_policies.<key>.name" type="string">
  Display name for the policy entry. Used in log output. Defaults to the map key.
</ParamField>

<ParamField body="network_policies.<key>.endpoints" type="object[]" required>
  Hosts and ports this entry permits.

  <Expandable title="Endpoint object fields">
    <ParamField body="host" type="string" required>
      Hostname or IP address. Supports wildcards: `*.example.com` matches any subdomain.
    </ParamField>

    <ParamField body="port" type="integer" required>
      TCP port number.
    </ParamField>

    <ParamField body="protocol" type="string">
      Set to `rest` to enable HTTP request inspection. Omit for TCP passthrough.
    </ParamField>

    <ParamField body="tls" type="string">
      TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it when `protocol` is `rest`, so this field is optional in most cases.

      Set to `skip` to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols.

      <Note>
        The values `terminate` and `passthrough` are deprecated and log a warning. They are still accepted for backward compatibility but have no effect on behavior.
      </Note>
    </ParamField>

    <ParamField body="enforcement" type="string">
      | Value     | Behavior                                    |
      | --------- | ------------------------------------------- |
      | `enforce` | Actively blocks disallowed requests.        |
      | `audit`   | Logs violations but allows traffic through. |
    </ParamField>

    <ParamField body="access" type="string">
      HTTP access level. Mutually exclusive with `rules`.

      | Value        | Allowed HTTP methods                              |
      | ------------ | ------------------------------------------------- |
      | `full`       | All methods and paths.                            |
      | `read-only`  | `GET`, `HEAD`, `OPTIONS`.                         |
      | `read-write` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT`, `PATCH`. |
    </ParamField>

    <ParamField body="rules" type="object[]">
      Fine-grained per-method, per-path allow rules. Mutually exclusive with `access`.

      <Expandable title="Rule object fields">
        <ParamField body="allow.method" type="string" required>
          HTTP method to allow (for example, `GET`, `POST`).
        </ParamField>

        <ParamField body="allow.path" type="string" required>
          URL path pattern. Supports `*` and `**` glob syntax.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="network_policies.<key>.binaries" type="object[]" required>
  Executables allowed to connect to the associated endpoints.

  <Expandable title="Binary object fields">
    <ParamField body="path" type="string" required>
      Filesystem path to the executable. Supports glob patterns with `*` and `**`.
      For example, `/sandbox/.vscode-server/**` matches any executable under that directory tree.
    </ParamField>
  </Expandable>
</ParamField>

## Complete example

The following policy grants read-only GitHub API access and npm registry access:

```yaml theme={null}
version: 1

filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /etc
  read_write:
    - /sandbox
    - /tmp
    - /dev/null

landlock:
  compatibility: best_effort

process:
  run_as_user: sandbox
  run_as_group: sandbox

network_policies:
  github_rest_api:
    name: github-rest-api
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/local/bin/claude
      - path: /usr/bin/node
      - path: /usr/bin/gh
  npm_registry:
    name: npm-registry
    endpoints:
      - host: registry.npmjs.org
        port: 443
    binaries:
      - path: /usr/bin/npm
      - path: /usr/bin/node
```

<CardGroup cols={2}>
  <Card title="Default policy" icon="file-check" href="/reference/default-policy">
    The built-in policy applied when no custom policy is provided.
  </Card>

  <Card title="Gateway authentication" icon="lock" href="/reference/gateway-auth">
    How the CLI resolves and authenticates with a gateway.
  </Card>
</CardGroup>