Customize Sandbox Policies

Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.

Policy Structure

A policy has static sections filesystem_policy, landlock, and process that are locked at sandbox creation, and a dynamic section network_policies that is hot-reloadable on a running sandbox.

version: 1
# Static: locked at sandbox creation. Paths the agent can read vs read/write.
filesystem_policy:
  read_only: [/usr, /lib, /etc]
  read_write: [/sandbox, /tmp]
# Static: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports.
landlock:
  compatibility: best_effort
# Static: Unprivileged user/group the agent process runs as.
process:
  run_as_user: sandbox
  run_as_group: sandbox
# Dynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them.
network_policies:
  my_api:
    name: my-api
    endpoints:
      - host: api.example.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: full
    binaries:
      - path: /usr/bin/curl

Static sections are locked at sandbox creation. Changing them requires destroying and recreating the sandbox. Dynamic sections can be updated on a running sandbox with openshell policy update for incremental merges or openshell policy set for full replacement, and take effect without restarting. When a hot reload changes rules on an active HTTP L7 endpoint, existing keep-alive tunnels are closed before forwarding another parsed request. Credential-injection-only HTTP passthrough tunnels use the same reload boundary. Most HTTP clients reconnect automatically, and the next request is evaluated against the current policy. Raw streams are connection-scoped and outside L7 live-reload guarantees. This includes tls: skip, non-HTTP TCP payloads, HTTP upgrades such as WebSocket, and long-lived response streams such as SSE. A reload applies to the next connection or next parsed HTTP request; it does not interrupt an already-forwarded raw stream. Use protocol: websocket when policy should stay attached to the RFC 6455 upgrade and client text messages after the allowed upgrade. Add websocket_credential_rewrite: true only when the relay should rewrite credential placeholders in client-to-server WebSocket text messages. Add request_body_credential_rewrite: true only on inspected REST endpoints that need OpenShell to rewrite placeholders in supported text request bodies.

Baseline Filesystem Paths

When a sandbox runs in proxy mode (the default), OpenShell automatically adds baseline filesystem paths required for the sandbox child process to function: /usr, /lib, /etc, /var/log (read-only) and /sandbox, /tmp (read-write). Paths like /app are included in the baseline set but are only added if they exist in the container image.

This filtering prevents a missing baseline path from degrading Landlock enforcement. Without it, a single missing path could cause the entire Landlock ruleset to fail, leaving the sandbox with no filesystem restrictions at all.

User-specified paths in your policy YAML are not pre-filtered. If you list a path that does not exist:

• In best_effort mode, the path is skipped with a warning and remaining rules are still applied.
• In hard_requirement mode, sandbox startup fails immediately.

This distinction means baseline system paths degrade gracefully while user-specified paths surface configuration errors.

Apply a Custom Policy

Pass a policy YAML file when creating the sandbox:

$
openshell sandbox create --policy ./my-policy.yaml -- claude

openshell sandbox create keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. Add --no-keep if you want the sandbox deleted automatically instead.

To avoid passing --policy every time, set a default policy with an environment variable:

$
export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml
$
openshell sandbox create -- claude

The CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided.

Iterate on a Running Sandbox

To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify.

The following steps outline the hot-reload policy update workflow.

1. Create the sandbox with your initial policy by following Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY).

2. Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard.

   $
   openshell logs <name> --tail --source sandbox

3. For additive network changes, use openshell policy update. This is the fastest path for adding endpoints, binaries, or REST and WebSocket allow/deny rules without replacing the full policy. The full option and format reference is in Incremental Policy Updates.

   $
   openshell policy update <name> \
   >
     --add-endpoint api.github.com:443:read-only:rest:enforce \
   >
     --binary /usr/bin/gh \
   >
     --wait
   $
   $
   openshell policy update <name> \
   >
     --add-allow 'api.github.com:443:POST:/repos/*/issues' \
   >
     --wait

   --add-allow and --add-deny target existing protocol: rest or protocol: websocket endpoints. If you pass multiple update flags in one command, OpenShell applies them as one atomic merge batch and persists at most one new revision.

4. For larger edits, pull the current policy and edit the YAML directly. Strip the metadata header (Version, Hash, Status) before reusing the file.

   $
   openshell policy get <name> --full > current-policy.yaml

5. Edit the YAML: add or adjust network_policies entries, binaries, access, or rules.

6. Push the updated policy when you need a full replacement. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout.

   $
   openshell policy set <name> --policy current-policy.yaml --wait

7. Verify the new revision. If status is loaded, repeat from step 2 as needed; if failed, fix the policy and repeat from step 4.

   $
   openshell policy list <name>

Incremental Policy Updates

Use openshell policy update when you want to merge network policy changes into the current live policy instead of replacing the whole YAML document. This command only updates the dynamic network_policies section.

openshell policy update is useful when you want to:

• add a new endpoint for an existing binary without touching other policy sections.
• add a few REST or WebSocket allow/deny rules after you see a blocked request in the logs.
• remove one endpoint or one named rule without rewriting the rest of the file.
• preview a merged result locally with --dry-run before you send it to the gateway.

Use openshell policy set instead when you want to replace the full policy, update static sections, or make broader edits that are easier to express in YAML.

Update Commands

The incremental update surface is split into endpoint-level operations and method/path rule-level operations for REST and WebSocket endpoints.

--wait and --dry-run cannot be used together.

Add Endpoint Compared to Allow and Deny

--add-endpoint works at the endpoint and rule level. It creates a new network_policies entry when needed, or merges into an existing rule that already covers the same host and port. Use it when you define where traffic can go and which binaries can send it.

--add-allow and --add-deny work at the method/path rule level. They do not create binaries, and they do not create a new endpoint. They modify an existing endpoint that already has protocol: rest or protocol: websocket.

This is the practical difference:

• Use --add-endpoint to say “allow this binary to reach api.github.com:443.”
• Use --add-allow to say “for that existing REST endpoint, also allow POST /repos/*/issues.”
• Use --add-deny to say “for that existing REST endpoint, explicitly deny POST /admin/**.”
• Use --add-allow to say “for that existing WebSocket endpoint, also allow client text messages on /v1/realtime/**.”

Current constraints:

• --add-allow and --add-deny work on protocol: rest and protocol: websocket endpoints.
• --add-deny requires the endpoint to already have an allow base, either an access preset or explicit allow rules.
• protocol: sql is not a practical incremental workflow today. OpenShell does not do full SQL parsing, and SQL enforcement is not meaningfully supported yet.

Endpoint Specs

--add-endpoint uses this format:

host:port[:access[:protocol[:enforcement[:options]]]]

Each segment has a fixed meaning:

Examples:

If you set protocol: rest or protocol: websocket, you also need an allow shape. With incremental updates, that means you should provide an access preset on --add-endpoint, then use --add-allow or --add-deny to refine method/path rules later.

Use the websocket-credential-rewrite endpoint option with protocol: websocket when the sandbox should send credential placeholders in client text frames and have OpenShell resolve them after the allowed upgrade. The option can also be used with protocol: rest compatibility endpoints that perform a WebSocket upgrade. It is rejected for plain L4 or protocol: sql endpoints.

Use the request-body-credential-rewrite endpoint option with protocol: rest when an API expects OpenShell-managed credentials in UTF-8 JSON, form, or text request bodies. OpenShell buffers up to 256 KiB, rewrites recognized credential placeholders, updates Content-Length, and rejects unresolved placeholders instead of forwarding them. The option is rejected for WebSocket, GraphQL, SQL, and plain L4 endpoints.

Credential rewrite recognizes the canonical openshell:resolve:env:KEY placeholder form and whole-token provider-shaped aliases such as provider-OPENSHELL-RESOLVE-ENV-API_TOKEN when the referenced environment key exists in the configured provider credentials.

For example:

• api.github.com:443:read-only:rest is valid.
• realtime.example.com:443:read-write:websocket is valid.
• api.github.com:443::rest is invalid. It does not mean “allow all traffic.” An L7 endpoint with protocol but no access or rules is rejected when the policy loads.

Endpoint options belong to the individual --add-endpoint spec. When you pass multiple --add-endpoint flags in one command, every --binary value applies to every added endpoint in that command. If different endpoints need different binaries, use separate policy update commands.

If you do not pass --rule-name, OpenShell generates one from the host and port, such as allow_api_github_com_443.

Method/Path Rule Specs

--add-allow and --add-deny use this format:

host:port:METHOD:path_glob

This string identifies an existing REST or WebSocket endpoint and the request pattern you want to add.

In shell commands, quote the full SPEC when it contains * or ** so your shell passes it literally instead of expanding it as a local file glob.

This example:

api.github.com:443:POST:/repos/*/issues

means:

• match the endpoint api.github.com:443.
• match HTTP method POST.
• match paths like /repos/acme/issues.
• do not match deeper paths like /repos/acme/project/issues/123 because * matches one path segment.

Path globs follow the same semantics as YAML allow and deny rules:

• * matches one path segment.
• ** matches any number of segments.
• /repos/*/issues matches one repository owner or name segment in the middle.
• /repos/** matches everything under /repos/.

The rule-level commands only modify method and path constraints. They do not change binaries, hostnames, ports, protocol settings, or WebSocket message payload matching.

Common Workflows

Use these patterns as starting points when you decide whether to update an endpoint or append REST/WebSocket rules.

Add a new L4 endpoint

Use --add-endpoint when you need a new host and port and do not need REST inspection.

$
openshell policy update demo \
>
  --add-endpoint pypi.org:443 \
>
  --add-endpoint files.pythonhosted.org:443 \
>
  --binary /usr/bin/pip \
>
  --binary /usr/local/bin/uv \
>
  --wait

This creates or merges endpoint entries and binds them to the listed binaries. It does not create inspected method/path rules.

Create a REST endpoint with a base allow set

Use --add-endpoint first when the endpoint does not exist yet.

$
openshell policy update demo \
>
  --add-endpoint api.github.com:443:read-only:rest:enforce \
>
  --binary /usr/bin/gh \
>
  --wait

This creates a REST endpoint and sets its base allow behavior through the read-only access preset.

Add one more REST allow rule

Use --add-allow after the REST endpoint already exists.

$
openshell policy update demo \
>
  --add-allow 'api.github.com:443:POST:/repos/*/issues' \
>
  --wait

This keeps the existing endpoint definition and appends one new allow rule. It does not add binaries or change the endpoint host and port.

Add a REST deny rule under an allowed endpoint

Use --add-deny when you want to carve out a blocked subtree under an existing REST endpoint.

$
openshell policy update demo \
>
  --add-deny 'api.github.com:443:POST:/admin/**' \
>
  --wait

This adds a deny rule to the existing REST endpoint. The endpoint must already have an allow base.

Create a WebSocket endpoint with a base allow set

Use --add-endpoint with protocol: websocket when the destination is an RFC 6455 WebSocket API.

$
openshell policy update demo \
>
  --add-endpoint realtime.example.com:443:read-write:websocket:enforce:websocket-credential-rewrite \
>
  --binary /usr/bin/node \
>
  --wait

This creates a WebSocket endpoint and sets its base allow behavior through the read-write access preset. For WebSocket endpoints, read-write expands to the upgrade GET and client WEBSOCKET_TEXT messages on the upgraded request path. The rewrite option lets the sandbox send openshell:resolve:env:* placeholders in client text frames; OpenShell resolves them before forwarding to the upstream service.

Add a WebSocket text-message deny rule

Use WEBSOCKET_TEXT when you want to refine client-to-server text-frame policy without matching message payload content.

$
openshell policy update demo \
>
  --add-deny 'realtime.example.com:443:WEBSOCKET_TEXT:/v1/admin/**' \
>
  --wait

This adds a deny rule to the existing WebSocket endpoint. The path glob matches the WebSocket upgrade path.

Remove one endpoint or rule

Use --remove-endpoint to remove one host and port pair, or --remove-rule to delete the whole named rule.

$
openshell policy update demo --remove-endpoint pypi.org:443 --wait
$
openshell policy update demo --remove-rule github_repos --wait

If the target endpoint is part of a multi-port endpoint, --remove-endpoint removes only the specified port and keeps the rest.

Merge Semantics

OpenShell applies all update flags from one openshell policy update command as one merge batch. The gateway validates the full merged result and persists at most one new policy revision.

This means:

• one command is atomic at the revision level.
• multiple flags in one command succeed or fail together.
• concurrent writers do not partially interleave one batch with another.

When two updates race, the gateway uses optimistic retry. It fetches the latest revision, reapplies the full batch, validates the result again, and retries the write. This preserves the intent of each individual command while still allowing concurrent sandbox policy updates.

Preview and Validation

Use --dry-run when you want to inspect the merged YAML before you send it to the gateway.

$
openshell policy update demo \
>
  --add-allow 'api.github.com:443:GET:/repos/**' \
>
  --dry-run

The CLI validates the argument shapes before it sends the request. The gateway then validates the merged policy against the current live policy and returns clear errors when:

• a required segment is missing.
• a port is outside 1 through 65535.
• --add-allow or --add-deny points at an endpoint that does not exist.
• --add-allow or --add-deny targets an endpoint that is neither REST nor WebSocket.
• --add-deny targets an endpoint that has no base allow set.

Global Policy Override

Use a global policy when you want one policy payload to apply to every sandbox.

$
openshell policy set --global --policy ./global-policy.yaml

When a global policy is configured:

• The global payload is applied in full for all sandboxes.
• Sandbox-level policy updates are rejected until the global policy is removed.

To restore sandbox-level policy control, delete the global policy setting:

$
openshell policy delete --global

You can inspect a sandbox’s effective settings and policy source with:

$
openshell settings get <name>

Debug Denied Requests

Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary.

When triaging denied requests, check:

• Destination host and port to confirm which endpoint is missing.
• Calling binary path to confirm which binaries entry needs to be added or adjusted.
• HTTP method and path for REST endpoints, or GET / WEBSOCKET_TEXT and the upgraded request path for WebSocket endpoints, to confirm which rules entry needs to be added or adjusted.

Then push the updated policy as described above.

For small changes, prefer openshell policy update over rewriting the full YAML:

$
openshell policy update <name> --add-allow 'api.github.com:443:GET:/repos/**' --wait

Examples

Add these blocks to the network_policies section of your sandbox policy. Apply simple endpoints and REST/WebSocket rule additions with openshell policy update, or apply any complete YAML block with openshell policy set <name> --policy <file> --wait. Use Simple endpoint for host-level allowlists and Granular rules for method/path control.

  pypi:
    name: pypi
    endpoints:
      - host: pypi.org
        port: 443
      - host: files.pythonhosted.org
        port: 443
    binaries:
      - { path: /usr/bin/pip }
      - { path: /usr/local/bin/uv }

Query parameter matching

REST rules can also constrain query parameter values:

  download_api:
    name: download_api
    endpoints:
      - host: api.example.com
        port: 443
        protocol: rest
        enforcement: enforce
        rules:
          - allow:
              method: GET
              path: "/api/v1/download"
              query:
                slug: "skill-*"
                version:
                  any: ["1.*", "2.*"]
    binaries:
      - { path: /usr/bin/curl }

query matchers are case-sensitive and run on decoded values. If a request has duplicate keys (for example, tag=a&tag=b), every value for that key must match the configured glob(s).

GraphQL matching

GraphQL endpoints use protocol: graphql. The proxy parses GraphQL-over-HTTP GET and POST requests, classifies each operation, and evaluates rules against the operation type, optional operation name, and selected root fields.

GraphQL endpoint policies currently require full policy YAML applied with openshell policy set; the incremental openshell policy update --add-endpoint parser does not accept graphql as a protocol.

  github_graphql:
    name: github_graphql
    endpoints:
      - host: api.github.com
        port: 443
        path: "/graphql"
        protocol: graphql
        enforcement: enforce
        rules:
          - allow:
              operation_type: query
              fields: [viewer, repository]
          - allow:
              operation_type: mutation
              operation_name: Issue*
              fields: [createIssue]
        deny_rules:
          - operation_type: mutation
            fields: [deleteRepository]
    binaries:
      - { path: /usr/bin/gh }

For allow rules, every selected root field in an operation must match one of the configured fields globs. For deny rules, one matching root field blocks the request. Batched GraphQL requests are fail-closed: if any operation is malformed, denied, or unregistered, the whole HTTP request is denied.

Hash-only persisted queries cannot be classified from the request alone. OpenShell denies them unless the endpoint uses persisted_queries: allow_registered and provides a trusted graphql_persisted_queries entry keyed by hash or saved-query ID.

GraphQL-over-WebSocket matching

Some APIs carry GraphQL operations over RFC 6455 WebSockets, commonly for subscriptions and realtime updates. Configure these as protocol: websocket, allow the upgrade with a normal GET rule, then add GraphQL operation rules for client operation messages. OpenShell recognizes modern graphql-transport-ws subscribe messages and legacy graphql-ws start messages.

  realtime_graphql:
    name: realtime_graphql
    endpoints:
      - host: realtime.example.com
        port: 443
        path: "/graphql"
        protocol: websocket
        enforcement: enforce
        rules:
          - allow:
              method: GET
              path: "/graphql"
          - allow:
              operation_type: subscription
              fields: [messageAdded]
          - allow:
              operation_type: query
              fields: [viewer]
        websocket_credential_rewrite: true
    binaries:
      - { path: /usr/bin/node }

When a WebSocket endpoint has GraphQL operation policy, client operation messages are fail-closed on malformed JSON, unsupported message types, parse errors, unregistered hash-only persisted queries, or unallowed operations. Use GraphQL operation rules for client messages rather than a raw WEBSOCKET_TEXT allow rule. Protocol lifecycle messages such as connection_init, ping, pong, and complete are allowed without payload logging; if websocket_credential_rewrite: true is set, placeholders inside those text messages are resolved before forwarding.

GraphQL service policy shapes

GraphQL field names are application-specific, so treat these as starting shapes to review against the actual app schema:

Next Steps

Explore related topics:

• To learn about the built-in sandbox policy, refer to Default Policy.
• To view the full field-by-field YAML definition, refer to the Policy Schema Reference.
• To review the default policy breakdown, refer to Default Policy.