*** title: Policy Schema Reference sidebar-title: Policy Schema description: Complete field reference for the sandbox policy YAML including static and dynamic sections. keywords: Generative AI, Cybersecurity, Policy, Schema, YAML, Reference, Security position: 3 --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.nvidia.com/openshell/latest/reference/llms.txt. For full documentation content, see https://docs.nvidia.com/openshell/latest/reference/llms-full.txt. 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 showLineNumbers={false} 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 The version field identifies which schema the policy uses: | Field | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------- | | `version` | integer | Yes | Schema version number. Currently must be `1`. | ## Filesystem Policy **Category:** Static Controls filesystem access inside the sandbox. Paths not listed in either `read_only` or `read_write` are inaccessible. | Field | Type | Required | Description | | ----------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- | | `include_workdir` | bool | No | When `true`, automatically adds the agent's working directory to `read_write`. | | `read_only` | list of strings | No | Paths the agent can read but not modify. Typically system directories like `/usr`, `/lib`, `/etc`. | | `read_write` | list of strings | No | Paths the agent can read and write. Typically `/sandbox` (working directory) and `/tmp`. | **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 (for example, `/` 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. 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. Example: ```yaml showLineNumbers={false} 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. | Field | Type | Required | Values | Description | | --------------- | ------ | -------- | --------------------------------- | ------------------------------------------------------------------ | | `compatibility` | string | No | `best_effort`, `hard_requirement` | How OpenShell handles Landlock failures. See behavior table below. | **Compatibility modes:** | Value | Kernel ABI unavailable | Individual path inaccessible | All paths inaccessible | | ------------------ | ------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- | | `best_effort` | Warns and continues without Landlock. | Skips the path, applies remaining rules. | Warns and continues without Landlock (refuses to apply an empty ruleset). | | `hard_requirement` | Aborts sandbox startup. | Aborts sandbox startup. | Aborts sandbox startup. | `best_effort` (the default) is appropriate for most deployments. It handles missing paths gracefully -- for example, `/app` may not exist in every container image but is included in the baseline path set for containers that do have it. Individual missing paths are skipped while the remaining filesystem rules are still enforced. `hard_requirement` is for environments where any gap in filesystem isolation is unacceptable. If a listed path cannot be opened for any reason (missing, permission denied, symlink loop), sandbox startup fails immediately rather than running with reduced protection. When a path is skipped under `best_effort`, the sandbox logs a warning that includes the path, the specific error, and a human-readable reason (for example, "path does not exist" or "permission denied"). Example: ```yaml showLineNumbers={false} landlock: compatibility: best_effort ``` ## Process **Category:** Static Sets the OS-level identity for the agent process inside the sandbox. | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------- | | `run_as_user` | string | No | The user name or UID the agent process runs as. Default: `sandbox`. | | `run_as_group` | string | No | The group name or GID the agent process runs as. Default: `sandbox`. | **Validation constraint:** 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. Example: ```yaml showLineNumbers={false} 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 Each entry in the `network_policies` map has the following fields: | Field | Type | Required | Description | | ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------- | | `name` | string | No | Display name for the policy entry. Used in log output. Defaults to the map key. | | `endpoints` | list of endpoint objects | Yes | Hosts and ports this entry permits. | | `binaries` | list of binary objects | Yes | Executables allowed to connect to these endpoints. | ### Endpoint Object Each endpoint defines a reachable destination and optional inspection rules. | Field | Type | Required | Description | | ------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `host` | string | Yes | Hostname or IP address. Supports wildcards: `*.example.com` matches any subdomain. | | `port` | integer | Yes | TCP port number. | | `protocol` | string | No | Set to `rest` to enable HTTP request inspection. Omit for TCP passthrough. | | `tls` | string | No | 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. The values `terminate` and `passthrough` are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior. | | `enforcement` | string | No | `enforce` actively blocks disallowed requests. `audit` logs violations but allows traffic through. | | `access` | string | No | HTTP access level. One of `read-only`, `read-write`, or `full`. Mutually exclusive with `rules`. | | `rules` | list of rule objects | No | Fine-grained per-method, per-path allow rules. Mutually exclusive with `access`. | #### Access Levels The `access` field accepts one of the following values: | Value | Allowed HTTP Methods | | ------------ | ------------------------------------------------- | | `full` | All methods and paths. | | `read-only` | `GET`, `HEAD`, `OPTIONS`. | | `read-write` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT`, `PATCH`. | #### Rule Object Used when `access` is not set. Each rule explicitly allows a method and path combination. | Field | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allow.method` | string | Yes | HTTP method to allow (for example, `GET`, `POST`). | | `allow.path` | string | Yes | URL path pattern. Supports `*` and `**` glob syntax. | | `allow.query` | map | No | Query parameter matchers keyed by decoded param name. Matcher value can be a glob string (`tag: "foo-*"`) or an object with `any` (`tag: { any: ["foo-*", "bar-*"] }`). | Example with rules: ```yaml showLineNumbers={false} rules: - allow: method: GET path: /**/info/refs* query: service: "git-*" - allow: method: POST path: /**/git-upload-pack query: tag: any: ["v1.*", "v2.*"] ``` ### Binary Object Identifies an executable that is permitted to use the associated endpoints. | Field | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | string | Yes | Filesystem path to the executable. Supports glob patterns with `*` and `**`. For example, `/sandbox/.vscode-server/**` matches any executable under that directory tree. | ### Full Example The following policy grants read-only GitHub API access and npm registry access: ```yaml showLineNumbers={false} 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 ```