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:

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`

version

integer

required

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.

filesystem_policy.include_workdir

boolean

When true, automatically adds the agent’s working directory to read_write.

filesystem_policy.read_only

string[]

Paths the agent can read but not modify. Typically system directories like /usr, /lib, /etc.

filesystem_policy.read_write

string[]

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 — / 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.

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 enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow.

landlock.compatibility

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.

landlock:
  compatibility: best_effort

`process`

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

process.run_as_user

string

default:"sandbox"

The user name or UID the agent process runs as.

process.run_as_group

string

default:"sandbox"

The group name or GID the agent process runs as.

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.

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

network_policies.<key>.name

string

Display name for the policy entry. Used in log output. Defaults to the map key.

network_policies.<key>.endpoints

object[]

required

Hosts and ports this entry permits.

Show Endpoint object fields

host

string

required

Hostname or IP address. Supports wildcards: *.example.com matches any subdomain.

port

integer

required

TCP port number.

protocol

string

Set to rest to enable HTTP request inspection. Omit for TCP passthrough.

tls

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.

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

Value	Behavior
`enforce`	Actively blocks disallowed requests.
`audit`	Logs violations but allows traffic through.

access

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`.

rules

object[]

Fine-grained per-method, per-path allow rules. Mutually exclusive with access.

Show Rule object fields

allow.method

string

required

HTTP method to allow (for example, GET, POST).

allow.path

string

required

URL path pattern. Supports * and ** glob syntax.

network_policies.<key>.binaries

object[]

required

Executables allowed to connect to the associated endpoints.

Show Binary object fields

path

string

required

Filesystem path to the executable. Supports glob patterns with * and **. For example, /sandbox/.vscode-server/** matches any executable under that directory tree.

Complete example

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

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

Default policy

The built-in policy applied when no custom policy is provided.

Gateway authentication

How the CLI resolves and authenticates with a gateway.

CLI Reference

Configuration

Policy Schema Reference

Policy schema reference

Top-level structure

`version`

`filesystem_policy`

Validation constraints

`landlock`

`process`

`network_policies`

Network policy entry

Complete example

Default policy

Gateway authentication

Build docs developers (and LLMs) love

CLI Reference

Configuration

Documentation Index

​Policy schema reference

​Top-level structure

​version

​filesystem_policy

​Validation constraints

​landlock

​process

​network_policies

​Network policy entry

​Complete example

Default policy

Gateway authentication

Build docs developers (and LLMs) love

Policy schema reference

Top-level structure

`version`

`filesystem_policy`

Validation constraints

`landlock`

`process`

`network_policies`

Network policy entry

Complete example