Stonewall Policy Schema

policy object

Metadata describing the policy to users and to the policy index at https://stonewall.sh/policies/_index.yml. It does not affect sandbox behavior and is discarded when policies are merged.

policy.name required · string · minLength: 1

Human-readable policy name shown on the policy site and by stonewall policy pick.

policy:
  name: Base

policy.url string · format: uri · pattern: ^https://

The canonical URL where this policy is published. Projects use this exact value in their include list. Stonewall only fetches policies over HTTPS.

policy:
  url: https://stonewall.sh/policies/base.yml

policy.tier integer

Orders official policies on https://stonewall.sh/policies from low to high: 0 operating system and environment, 1 basic tools, 2 programming languages and frameworks, 3 agents. Policies without a tier sort last, as if they had tier 99.

policy:
  tier: 2

policy.tags array · uniqueItems

Free-form keywords describing the policy, for content and search on the policy site.

policy:
  tags:
    - language
    - go

policy.description string · minLength: 1

A short explanation of what the policy allows and which capabilities it intentionally does not grant.

policy:
  description: Allows access to the minimum binaries and locations needed by Claude Code.

include array of include · uniqueItems

Policies to apply before this file, in order. Remote policies are reviewed once, pinned by content hash in .stonewall/lock.yml, and cached. They are not fetched again until stonewall policy update is run. Remote policies cannot include other policies.

include:
  - https://stonewall.sh/policies/base.yml
  - policies/project.yml

bin object

Controls which programs are available on PATH inside the sandbox. Programs not listed here cannot be executed by name. Allowing a shell or interpreter such as bash or python effectively allows arbitrary commands, so official policies do not grant them.

bin.allowed array of programName · uniqueItems

Programs to make available on PATH inside the sandbox, specified by bare name. Each name is resolved against the host PATH when the sandbox starts; programs that are not installed are skipped. The agent being launched must also be listed here.

bin:
  allowed:
    - claude
    - node
    - make

bin.denied array of programName · uniqueItems

Programs to remove from an allowed list inherited from an earlier policy. This is mainly useful when including other policies. The same program cannot appear in both allowed and denied in one file.

bin:
  denied:
    - git

project object

Controls access to paths inside the project, relative to the project root containing .stonewall.yml. By default, the entire project is readable and writable. Paths that do not exist when the sandbox starts are ignored.

project.hidden array of projectPath · uniqueItems

Paths the agent cannot read. Use this for secrets such as .env files, private keys, and credential directories.

project:
  hidden:
    - .env

project.readonly array of projectPath · uniqueItems

Paths the agent can read but cannot modify. For example, making .git read-only keeps repository history available while preventing destructive Git operations.

project:
  readonly:
    - .git

project.writable array of projectPath · uniqueItems

Paths to make writable again when an earlier policy marked them hidden or read-only. This is mainly useful when including other policies. A path can appear in only one of hidden, readonly, or writable in the same file.

project:
  writable:
    - src/generated

expose object

Controls access to host paths outside the project. The home directory appears empty inside the sandbox unless paths are explicitly exposed here. System directories remain readable.

expose.read array of hostPath · uniqueItems

Host paths the agent can read but cannot modify, such as ~/.gitconfig. Tools that need to rewrite or replace these files will fail.

expose:
  read:
    - ~/.gitconfig

expose.write array of hostPath · uniqueItems

Host paths the agent can read and modify, such as ~/.claude or ~/.npm. On Linux, exposing a single file creates a mount point, so tools that replace the file using rename may fail with EBUSY.

expose:
  write:
    - ~/.claude
    - ~/.npm

expose.none array of hostPath · uniqueItems

Host paths whose exposure from an earlier policy should be removed. This is mainly useful when including other policies. A path can appear in only one of read, write, or none in the same file.

expose:
  none:
    - ~/.aws

include string

A policy to include. Accepted values are an HTTPS URL, a path under the home directory (~/…), an absolute path, or a path relative to the directory containing this file that does not escape that directory. Other URL schemes, including http://, are rejected. URL fragments are also rejected because remote content is pinned in .stonewall/lock.yml rather than in the URL.

anyOf

• Remote policy: ^https://[^\s#]+$
• Home or absolute path: ^~?/
• Path relative to this file: projectPath

examples: https://stonewall.sh/policies/base.yml ~/.stonewall/policy.yml /etc/stonewall/policy.yml policies/project.yml

programName string

A program specified by bare command name, such as claude, node, or make. Directory paths and whitespace are not allowed.

pattern: ^[^/\s]+$

examples: claude node make

projectPath string

A path relative to the project root, such as .git, .env, or src/generated. It cannot start with / or ~/, contain a .. component, or contain empty path components. A trailing slash is allowed.

pattern: ^([^/~]|\.[^./]|[^./][^/]|[^/]{3,})(/([^/]|\.[^./]|[^./][^/]|[^/]{3,}))*/?$

examples: .git .env src/generated

The pattern expresses these constraints positively so validators can report the invalid value directly: the first component must be non-empty and cannot be ~ or ..; following components must be non-empty and cannot be ..; an optional trailing slash is allowed. Rejecting empty components also prevents values such as http://x from matching the relative-path branch of include.

hostPath string

A host path outside the project, either relative to the home directory using ~/… or an absolute path such as /tmp.

pattern: ^~?/

examples: ~/.gitconfig /tmp