Policy packs and admin controls
Pick the open, balanced, or strict OpenShell sandbox policy pack, write a custom pack, and set organization-wide limits with openshell.admin.
Pick the sandbox pack that fits your project, add your own hosts, and lock a project to the sites its sandbox reached. A pack is one YAML file that sets web access, how connection requests are approved, live mount or copy, hidden secret files and skip-permissions mode.
Keys, defaults and rules for sandbox policy packs and the openshell.admin limits. For tasks see Choose a pack. defenseclaw sandbox policy explain shows the policy a run would get and where each setting comes from.
The built-in packs at a glance
| Pack | Web access | Your project | Skip-permissions |
|---|---|---|---|
open (default) | Any site by name, except the blocklist, private networks and this machine | Mounted live | On |
balanced | A curated developer allowlist | Mounted live | On |
strict | None, only the model provider | Copied | Off |
Every setting of each pack is in Built-in packs. Sandboxes must be set up first.
Built-in packs
The pack files are embedded in the binary (source: policies/sandbox/<name>/pack.yaml). A custom file can never replace them.
| Setting | open (default) | balanced | strict |
|---|---|---|---|
| Web access | Any site by name, except the blocklist, private networks and this machine | Only the curated developer allowlist | None; only the harness's model provider |
Connection requests (approvals.mode) | auto | triage | manual |
| Proxy ports | 80, 443 | 80, 443 | 443, for approved connections only (the proxy is off) |
| Large-upload alert | 25 MiB | 10 MiB | 5 MiB |
| Your project | Mounted live | Mounted live | Copied; changes come back as a patch or branch |
| Copy size limit | 500 MiB | 500 MiB | 200 MiB |
| Skip-permissions mode | On | On | Off |
| MCP servers | Brought along | Brought along | Left behind |
| The repository's own MCP servers | Stay stopped | Stay stopped | Stay stopped |
| Host ports for MCP servers | Can be opened | Can be opened | Never |
| Hook failure | Tool call denied | Tool call denied | Tool call denied |
| Hook tamper, silent hooks | Reported, sandbox keeps running | Sandbox stopped | Sandbox stopped |
All three use the built-in blocklist feed, hide the same list of secret files and flag the same list of files that can run code. The balanced allowlist covers package registries (npm and Yarn, PyPI, the Go module proxy, crates.io, RubyGems, Maven Central, Gradle, NuGet, Packagist, Hex, pub.dev, conda), source hosts (github.com, api.github.com, codeload.github.com, *.githubusercontent.com, ghcr.io, gitlab.com, bitbucket.org), toolchains (Node.js, Rust, www.python.org, uv) and common documentation. defenseclaw sandbox pack show balanced prints the exact list, which is also the egress proxy's allowlist feed.
In 1.0.4 the list is these 50 hosts, on ports 80 and 443:
registry.npmjs.org, registry.yarnpkg.com, repo.yarnpkg.com, pypi.org, files.pythonhosted.org,
proxy.golang.org, sum.golang.org, index.golang.org, crates.io, index.crates.io, static.crates.io,
rubygems.org, index.rubygems.org, repo.maven.apache.org, repo1.maven.org, plugins.gradle.org,
services.gradle.org, downloads.gradle.org, api.nuget.org, packagist.org, repo.packagist.org,
hex.pm, repo.hex.pm, builds.hex.pm, pub.dev, conda.anaconda.org, github.com, api.github.com,
codeload.github.com, *.githubusercontent.com, ghcr.io, gitlab.com, bitbucket.org, nodejs.org,
static.rust-lang.org, sh.rustup.rs, www.python.org, astral.sh, releases.astral.sh, docs.python.org,
developer.mozilla.org, go.dev, pkg.go.dev, docs.rs, doc.rust-lang.org, docs.github.com,
docs.npmjs.com, www.typescriptlang.org, learn.microsoft.com, stackoverflow.comAn allowlist limits where, not what. The proxy sees HTTPS as encrypted tunnels, so every allowed host can receive data as well as serve it.
Choose a pack
For one run:
defenseclaw sandbox run claude --pack balancedFor every run, set openshell.pack: balanced in ~/.defenseclaw/config.yaml. defenseclaw sandbox pack list lists the packs with their digests.
Add one host at a time
defenseclaw sandbox policy allow artifacts.example.com
defenseclaw sandbox policy test --host artifacts.example.com pack balanced · profile balanced · network allowlist
DESTINATION DECISION RULE SOURCE
registry.npmjs.org:443 allowed allow registry.npmjs.org DefenseClaw's curated allowlist (pack balanced)policy block HOST does the opposite. policy test says which rule decides and why.
Return to the default pack
Remove --pack, or delete openshell.pack from config.yaml, to return to open. Delete the pack directory to remove a custom pack.
Write a custom pack
A custom pack starts from nothing unless it names a parent. Create ~/.defenseclaw/policies/sandbox/team-web/pack.yaml. The directory name must match name.
version: 1
name: team-web
extends: balanced
egress:
allow:
- artifacts.example.com
- docs.example.com
ports: [443]Lists such as egress.allow add to the parent's. Every other key replaces the parent's value (rules). Validate it, then use it:
defenseclaw sandbox pack validate ~/.defenseclaw/policies/sandbox/team-web/pack.yaml
defenseclaw sandbox run claude --pack team-webA bad key stops validation with the file, the key and the reason:
sandbox pack /home/dev/.defenseclaw/policies/sandbox/team-web/pack.yaml: egress.ports[1]: port 70000 must be between 1 and 65535Extend a pack
A pack names one parent with extends:. It then sets only what it changes.
- A key left out has the parent's value.
- These lists add to the parent's:
egress.allow,egress.block,workspace.masks,workspace.unmask,workspace.review,mcp.blocked_tools. A pack cannot remove a parent's entry. - Every other key replaces the parent's value, including
egress.ports,egress.feedsandharness.allowed. - A parent can extend another pack, up to four above the one you run. A chain that returns to a pack it already holds is refused.
- The merged pack is checked as a whole before your
openshellkeys, the run's options andopenshell.adminapply. - Allow entries inherited from a built-in pack stay DefenseClaw's curated entries: they admit their names but open no private network, and
allow_unblock: falsekeeps them. The pack's own entries are yours, which that setting drops.
A custom pack without extends gets only what it lists. Its masks, unmask and review lists replace the built-in ones.
Pack file reference
A pack lives at <openshell.pack_dir>/<name>/pack.yaml. openshell.pack_dir defaults to <data_dir>/policies/sandbox and must be an absolute path or start with ~/. An empty value turns custom pack names off.
openshell.pack value | Loads |
|---|---|
| Empty or omitted | The open pack. |
open, balanced, strict | The embedded pack. |
Another name, such as team-web | <pack_dir>/team-web/pack.yaml. |
An absolute path or ~/ path | That pack.yaml, or the one inside that directory. Relative paths are refused. |
| Key | Required | Default | Rules |
|---|---|---|---|
version | Yes | Must be 1. | |
name | Yes | Lowercase letters, digits and dashes, starting with a letter or digit, at most 63 characters. Must match the directory name. open, balanced and strict are reserved. | |
description | No | Empty | At most 1024 characters. |
extends | No | A built-in pack name or a custom pack name in pack_dir. Paths are refused. | |
network.mode | Yes | open, allowlist or deny. Maps to profile open, balanced, strict. | |
approvals.mode | Yes | auto, triage or manual. | |
observe.process_tree | No | false | true samples the sandbox's processes every 5 seconds (15 on a Mac when sampling its MicroVM is slow). |
egress.feeds | No | [builtin] | Only builtin; [] turns the feed off. At most 16. |
egress.block | No | [] | Host patterns. At most 1024. |
egress.allow | No | [] | Host patterns, never one that covers a whole top-level domain such as *.com, or an address range wider than /8 (IPv4) or /16 (IPv6). At most 1024. |
egress.ports | No | [80, 443] | Ports 1-65535. At least one unless network.mode is deny. At most 64. |
egress.large_upload_mb | No | 25 | 0-1048576. 0 turns the report off. |
egress.block_large_uploads | No | false | true also cuts the upload that crosses large_upload_mb and refuses later requests to the host. |
workspace.mode | Yes | mount or copy. | |
workspace.masks | No | [] | Project globs of secret files to hide. At most 1024. |
workspace.unmask | No | [] | Project globs kept visible anyway, such as .env.example. |
workspace.review | No | [] | Project globs of files that can run code, called out at the end of a session. |
workspace.max_upload_mb | No | 500 | Size limit of the copy in copy mode, 1-1048576. |
harness.yolo | Yes | true or false: skip-permissions mode. | |
harness.allowed | No | [] (any) | Harness names such as claudecode and codex. claude-code is read as claudecode. At most 64. |
mcp.import | Yes | Whether your own MCP servers come along. | |
mcp.host_ports | Yes | Whether host ports may be opened for MCP servers on your machine. | |
mcp.blocked_tools | No | [] | Tool names or globs. At most 1024. |
mcp.project_servers | No | block | block or allow: whether the MCP servers a repository defines may start. |
hooks.fail_mode | Yes | Must be closed. | |
hooks.on_tamper | No | alert when network.mode is open, else stop | stop or alert. |
hooks.on_silence | No | alert when network.mode is open, else stop | stop or alert, for user-tier harnesses. A managed-tier harness only alerts. |
hooks.silence_after | No | 10m | 1m to 24h. |
Host patterns are an exact host name, *.example.com (every subdomain, not example.com itself), an IP address, or a CIDR prefix. A bare *, schemes, ports, paths, wildcards inside a name and names whose last label does not start with a letter are refused. Project globs are relative to the project with forward slashes. Absolute paths, ~, drive letters, backslashes and .. are refused.
The review also flags, in every pack, changes to harness and agent-tool project config (.claude/, .mcp.json, .codex/, .cursor/, .gemini/, AGENTS.md, CLAUDE.md and similar), lock files and pack.yaml files.
Loading rules
A pack is refused when the file is over 64 KiB, empty or holds more than one YAML document; a key is unknown or repeated; a value has the wrong type or is null; it uses YAML anchors, aliases or merge keys; a required key is missing; or a custom pack uses a built-in name. A pack that fails to load stops the run.
File ownership
A custom pack must be a regular file, and neither it nor its directory may be a symbolic link. The file and its directory must belong to you or to root and must not be writable by group or others (a Linux POSIX ACL that grants write counts; macOS ACLs are not inspected). Fix a refused file with chmod go-w.
Pack digest
A pack's digest is sha256: plus the SHA-256 of the file's exact bytes. defenseclaw sandbox pack list and pack show report it. The digest of a pack that extends another covers the chain: the SHA-256 of the parent's digest, a newline and the file's bytes, so read it with pack show. On a managed computer, an administrator reads the digest to pin with the gateway binary:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux sandbox pack-digest /etc/defenseclaw/policies/sandbox/contractors/pack.yamlOn macOS use /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos. A built-in pack's digest can change with each release.
How the effective policy is computed
Five layers. The first three can override the one before; the last two only tighten.
- The pack supplies every default.
- Your
openshellkeys inconfig.yamloverride the pack (Configuration). - Per-run options of
sandbox run:--pack,--profile,--copy,--safe,--unmask,--host-port,--no-mcp,--cpu,--memory. - The repository policy narrows the result. A looser one refuses the run.
openshell.adminclamps the result. A harness it does not allow is refused.
| Setting | How the layers combine |
|---|---|
| Profile | The pack's network mode, then openshell.profile, then --profile. Each replaces the one before. Admin floors raise it. |
| Approvals | The pack's mode, never looser than the profile: balanced triages at least, strict is manual. |
| Skip-permissions | The pack's harness.yolo, then openshell.yolo, then the run. Keeping the prompts for a run always wins. |
| Allowed harnesses | The pack's list and admin.allowed_harnesses. Only harnesses on both run. |
| Process tree | The pack's value, --process-tree, or a repository policy with observe.process_tree: true. Nothing turns a pack's true off. |
| Workspace mode | The pack's mode, then openshell.workdir.mode, then copy mode for a run. |
| Secret masks | The pack's plus openshell.workdir.masks. Masks can be added, not removed. |
| Unmask | The pack's plus openshell.workdir.unmask plus the run's entries. |
| Review list | The pack's plus DefenseClaw's own list, which no pack can drop. |
| Block list | The pack's plus openshell.egress.block. |
| Proxy ports | The pack's, or openshell.egress.ports, which replaces them. |
| MCP import | The pack's, then openshell.mcp.import, then leaving MCP servers behind for a run. |
| Host ports | openshell.mcp.host_ports plus the run's ports. Each port is checked. |
| Resources | openshell.resources, then the run's request, capped by admin.max_resources. |
openshell.workdir.max_upload_mb and openshell.egress.large_upload_mb replace the pack's value when above 0. openshell.workdir.git_depth and openshell.workdir.on_exit are not part of a pack. openshell.profile replaces the pack's profile, so profile: open on the strict pack turns the web on. Only an admin floor (min_profile, egress_allow_only, required_pack) limits that. When the effective profile is balanced and the pack is not in allowlist mode, DefenseClaw adds the balanced pack's curated allowlist.
Large-upload alert threshold
Each sandbox has its own threshold: openshell.egress.large_upload_mb when above 0, else the resolved pack's egress.large_upload_mb, including a run's --pack (--profile changes no pack setting). A change reaches running sandboxes on the next config reload. The report is an activity event and a HIGH finding (SANDBOX_EGRESS_LARGE_UPLOAD in the egress audit record when cut). With the block on, DefenseClaw stops the upload before the chunk that crosses the threshold and refuses later connections to that host, and to other new hosts under the same domain or at the same address. Exempt: hosts you unblocked, hosts on an allow list you or your administrator wrote (openshell.egress.allow, a custom pack's egress.allow, admin.egress_allow_only). The balanced curated list does not exempt a host. The count starts again when the daemon restarts. Under strict nothing passes the proxy, so there is nothing to report. How the user sees a cut: sandbox network.
The allow list
The allow list is built from the entries of a built-in or required pack (always applied); the balanced curated list when the profile is balanced and the pack is not in allowlist mode; and the entries of a custom pack you chose plus your openshell.egress.allow (dropped when allow_unblock is false). Entries covering every host or a top-level domain are ignored.
Repository policy (.defenseclaw/sandbox.yaml)
A .defenseclaw/sandbox.yaml file in the project folder asks for a stricter sandbox. DefenseClaw reads it on your machine when the sandbox is created. It applies to runs started in the folder that holds .defenseclaw/.
version: 1
network:
mode: allowlist
egress:
block: [uploads.example.net]
ports: [443]
large_upload_mb: 5
workspace:
mode: copy
masks: ["config/*.secret"]
review: ["scripts/**"]
harness:
yolo: false| Key | What it does |
|---|---|
version | Required, 1. |
network.mode | allowlist or deny: a floor. |
approvals.mode | triage or manual: a floor. |
egress.block | Host patterns added to the block list. |
egress.ports | The ports the project needs. A list that keeps none refuses the run, unless the network mode is deny. |
egress.large_upload_mb | Lowers the threshold (1 or more). |
egress.block_large_uploads | true turns the block on. |
workspace.mode | copy. |
workspace.masks, workspace.review | Globs added to the masks and the review. |
harness.yolo | false: the harness keeps its prompts. |
mcp.import | false: your MCP servers stay behind. |
mcp.blocked_tools | MCP tools added to the blocked tools. |
hooks.on_tamper, hooks.on_silence | stop. |
observe.process_tree | true. |
A value that loosens the policy refuses the run, one line per key: network.mode: open, approvals.mode: auto, workspace.mode: mount, hooks.on_tamper: alert, hooks.on_silence: alert, harness.yolo: true, mcp.import: true, observe.process_tree: false, egress.block_large_uploads: false, egress.large_upload_mb: 0, and any egress.allow or workspace.unmask entry.
the repository policy .defenseclaw/sandbox.yaml would loosen the sandbox policy: harness.yolo true — skip-permissions mode drops the harness's own prompts; a repository policy can only tighten, so remove harness.yolo from .defenseclaw/sandbox.yamlThe repository may belong to someone else, so the file is untrusted input: a regular file of at most 16 KiB, not a symbolic link, read as strictly as a pack (no unknown or repeated keys, no anchors, aliases, merge keys, includes or extends). The sandbox keeps the copy it was created with. An edit applies to the next new sandbox. The launch banner's Policy row names it, and policy explain lists it with its digest and the source repo.
Record, then lock
Run a few sessions on the default open pack. DefenseClaw keeps every destination a sandbox reached or tried to reach (defenseclaw sandbox destinations NAME). Then preview and write a pack from them:
defenseclaw sandbox policy suggest --sandbox myapp-claude --diff
defenseclaw sandbox policy suggest --sandbox myapp-claude \
--pack-out ~/.defenseclaw/policies/sandbox/myapp/pack.yaml pack myapp-claude-recorded against the policy of sandbox myapp-claude (pack open):
profile open → balanced
network.mode open → allowlist
approvals.mode auto → triage
egress.allow +example.net, registry.npmjs.org, registry.yarnpkg.com (+47 more; -o json lists all)
egress.large_upload_mb 25 → 10
hooks.on_tamper alert → stop
hooks.on_silence alert → stop
⚠ reached now, blocked with the pack:
api.openai.com:443 — network_allowlist (network.mode allowlist (profile balanced))--pack-out PATH writes the pack and never overwrites a file.
✓ wrote /home/user/.defenseclaw/policies/sandbox/myapp/pack.yaml: pack myapp, extends balanced, 1 host to allow| In the written pack | Why |
|---|---|
extends: balanced | The pack starts from the balanced pack. |
| Hosts to allow | Every host the sandbox reached that balanced does not cover, each with a comment naming the programs that reached it. |
| Comments only | Hosts only ever refused, shadow AI hosts, blocklist hosts and the sandbox's model provider are listed, not allowed. |
The pack extends balanced and allows each host the sandbox reached that balanced does not cover, with a comment naming the programs that reached it. Hosts only ever refused, shadow AI hosts and the model provider are listed as comments, not allowed. Review every host, then lock the project:
defenseclaw sandbox run claude --pack myappNothing applies until you run with the pack (defenseclaw sandbox run claude --pack myapp, or openshell.pack: myapp). Review every host first.
A project can also ask for a stricter sandbox with a .defenseclaw/sandbox.yaml.

open pack. Nothing is applied by suggest; you review the file, then run with --pack.Test the policy
To keep it locked in CI, run defenseclaw sandbox policy test --pack FILE --fixture egress-expectations.yaml. It exits 1 when a decision does not match.
To keep a pack from drifting, list expected decisions in a fixture and run policy test:
- {host: registry.npmjs.org, port: 443, expect: allow}
- {host: pastebin.com, port: 443, expect: block, rule: feed}defenseclaw sandbox policy test --pack ~/.defenseclaw/policies/sandbox/myapp/pack.yaml \
--fixture egress-expectations.yaml --output jsonThe command exits 1 when a decision does not match. It needs no config.yaml and no running daemon, but it runs defenseclaw-gateway, which must be on PATH or next to defenseclaw.
defenseclaw sandbox policy explainThe Pack row names your pack, and each setting shows the layer that set it.

policy test resolves a pack without the daemon. The output is identical to the 1.0.3 recording.Admin constraints
The openshell.admin block holds the administrator's limits. Every key is optional. The allow_* switches restrict only when false.
openshell:
admin:
required_pack: "" # a pack every run must use; its posture is a floor
required_pack_digest: "" # sha256:<64 hex> pins the required pack's content
min_profile: "" # open | balanced | strict: the loosest profile allowed
allow_yolo: null # false: harnesses keep their permission prompts
allow_mount: null # false: no live host mounts; every run uses a copy
allow_host_ports: null # false: no host port is ever opened to a sandbox
allow_unblock: null # false: no unblocking, no approve-always, no user allow entries
allow_learn_mode: null # false: learn mode is refused
allowed_harnesses: [claudecode, codex] # only these harnesses may run; leave out for no limit
egress_block: [] # host globs that are always blocked (a name covers its subdomains)
egress_allow_only: [api.example.com] # the only host globs any sandbox may reach; leave out for no limit
block_large_uploads: false # true: every sandbox's large uploads to new hosts are cut
require_copy_for: [] # project path globs that must run in copy mode
max_resources: # ceilings for every sandbox
cpu: "" # "2", "1.5", or "500m"
memory: "" # "512Mi", "4Gi", "2G", or bytes
locked: [] # keys per-run options may not loosenA malformed value, such as an unknown locked key or a bad digest, is a configuration error.
| Key | Effect |
|---|---|
required_pack | Every run uses this pack: a built-in name, a custom name or an absolute path. A different choice is replaced and reported. Its posture is a floor: profile, skip-permissions default, workspace mode, MCP import, the blocklist feed and the proxy ports can be made stricter, never looser. Its allow entries always apply. A new value also reaches running sandboxes: connections DefenseClaw approved on its own that the stricter policy would leave to the user are closed. A sandbox that mounts live while the policy now asks for a copy keeps its mount until it stops, then cannot start again. |
required_pack_digest | sha256: plus 64 lowercase hex digits. Needs required_pack. If the pack's digest differs, no sandbox starts. Pin a custom pack, because a built-in pack's digest can change on upgrade. |
min_profile | The loosest profile any run may use (open < balanced < strict). A looser one is raised. |
allow_yolo: false | Skip-permissions mode is off for every harness. |
allow_mount: false | Every run uses copy mode and no host folder is bind-mounted, including read-only reference folders. |
allow_host_ports: false | No host port is opened, from config, a run or an approval. |
allow_unblock: false | Blocked destinations cannot be unblocked, earlier unblocks stop counting, approvals cannot be kept for future sandboxes, your allow entries and a custom pack's are ignored, the blocklist feed cannot be turned off and allow entries no longer exempt a host from it. A one-time approval cannot reach a feed-listed or private-network destination. |
allow_learn_mode: false | Learn mode (the sandbox API's learn option) is refused. |
allowed_harnesses | Only these harnesses run (claude-code and claudecode are the same). With the pack's harness.allowed, only harnesses on both lists. |
egress_block | Blocked for every sandbox, checked first. A host name also blocks its subdomains. Neither unblock nor approval opens them. |
egress_allow_only | The complete list of hosts any sandbox may reach. Entries match exactly (github.com does not admit *.github.com). A private host entry opens it. Raises the profile to at least balanced. Unblocks and approvals outside the list are refused. Hosts on it are exempt from the large-upload block. |
block_large_uploads | Turns the large-upload block on for every sandbox. A pack with large_upload_mb: 0 gets 25 MiB, and a threshold above 25 MiB is lowered to 25 MiB (or the required pack's own, when higher). Users can lift the block for one host unless allow_unblock is false. |
require_copy_for | Project path globs that must run in copy mode. * and ? match within a segment, ** any number. A pattern without wildcards covers the folder and everything below it. ~/ expands to the home of the account that computes the policy. Mounting a parent of a covered folder counts. Matching ignores case and follows symbolic links. |
max_resources | Ceilings. cpu: cores up to three decimals or millicores ("2", "1.5", "500m"). memory: bytes with a Ki, Mi, Gi, Ti or k, K, M, G, T suffix. A run that asks for nothing gets the ceiling. |
locked | openshell keys per-run options may not loosen. |
locked
| Locked key | What a run can still do |
|---|---|
pack | Choose a pack at least as strict as the configured pack in every setting, or one with the same content. |
profile | Choose a stricter profile. |
yolo | Keep the harness prompts. |
workdir.mode | Switch to copy mode. |
workdir.unmask | Unmask only entries the pack or openshell.workdir.unmask already lists. |
mcp.import | Leave MCP servers behind. |
mcp.host_ports | Open only ports already in openshell.mcp.host_ports. |
resources | Ask for at most the CPU and memory in openshell.resources. |
Locking pack alone keeps no floor: a run could still choose the open profile, turn skip-permissions on, reveal masked files and open host ports. To let users pick any pack at least as strict, set openshell.pack and lock every key a run could loosen:
openshell:
pack: balanced
admin:
locked: [pack, profile, yolo, workdir.unmask, mcp.host_ports, resources]Runtime actions
| Action | Refused by |
|---|---|
| Unblock a destination | allow_unblock: false, egress_block, a host outside egress_allow_only, the strict profile (the proxy is off), and always the block list, private networks and this machine |
| Approve a request once | egress_block, a host outside egress_allow_only, a name that resolves to this machine, and with allow_unblock: false a feed-listed or private-network destination |
| Approve for all future sandboxes | Everything above, plus allow_unblock: false on its own |
| Open a host port | allow_host_ports: false, or a pack with mcp.host_ports: false |
| Mount a host folder | allow_mount: false, or a folder covered by require_copy_for |
| Run in skip-permissions mode | allow_yolo: false |
| Use learn mode | allow_learn_mode: false |
| Run a harness | allowed_harnesses, or the pack's harness.allowed |
A request to connect to this machine is treated as a host-port request.
Limits DefenseClaw always applies
No pack or admin setting changes these:
- Sandbox hooks always fail closed.
- DefenseClaw never opens its own listeners to a sandbox: the API (
gateway.api_port, 18970 by default), the hook ingress and egress proxy (the next two ports), the guardrail proxy, the model router when routing runs on this machine, and the listeners of enabled Prometheus destinations. The OpenShell gateway (port 17670 by default) and the OpenClaw gateway (gateway.port, 18789) are never opened either. - Link-local, cloud metadata, multicast and reserved addresses are never approved.
- Allow entries that cover every host or a whole top-level domain are ignored.
What users see when something is blocked
A refusal by the admin block names the key:
blocked by your organization's DefenseClaw policy: yolo
blocked by your organization's DefenseClaw policy: profile
blocked by your organization's DefenseClaw policy: egress.unblock
blocked by your organization's DefenseClaw policy: harnessThe sandbox API returns the reason as the error's detail and in a violation object. A pack or profile refusal names the pack, such as not allowed by the strict sandbox pack: mcp.host_ports. A clamped setting continues with the allowed value, is reported when the user chose it, and is recorded in the setting's provenance. A refused harness stops the run before a sandbox starts. A refused action leaves the sandbox running. A pack that fails to load or a digest mismatch starts no sandbox:
sandbox policy: openshell.admin.required_pack strict has digest sha256:9af8…, not the pinned openshell.admin.required_pack_digest sha256:3f5c…Authoritative and advisory admin blocks
On a per-user install the user owns config.yaml, so the admin block is enforced but advisory. On a standalone managed_enterprise install the administrator owns it, the block is authoritative, and each guardrail profile can add a tighter sandbox section (Sandboxes on managed computers). Sandboxes do not run on Windows.
When the block is advisory, the doctor's Organization policy row says so and names each constraint:
✓ Organization policy advisory (you own config.yaml and can change it): profile balanced or stricter, harnesses claudecode, codex only, copy mode for ~/customers/**, 1 blocked host, at most 4 CPUs and 8Gi memory, locked: profileOn a standalone managed install the block is authoritative and a guardrail profile's sandbox section can only tighten it. That section takes the keys above plus allowed, required_for, when_unavailable, user_approvals, allowed_credentials, on_silence, max_silence_after, process_tree, foreign_sandboxes, allow_upstream_telemetry, delete_stopped_after and request_access (Sandboxes on managed computers, Sandbox policy pushdown).
Example: a balanced organization
A balanced organization: fast development on the web allowlist, customer code never mounted live, one file-sharing service off limits.
openshell:
enabled: true
pack: balanced
egress:
allow:
- artifacts.example.com # the company package mirror
admin:
min_profile: balanced
allowed_harnesses: [claudecode, codex]
egress_block:
- files.example.net
require_copy_for:
- /Users/*/code/customers
- /home/*/code/customers
max_resources:
cpu: "4"
memory: 8Gi
locked: [pack, profile]Developers get the curated allowlist plus artifacts.example.com, can unblock other hosts one at a time but never files.example.net, run only Claude Code and Codex, get at most 4 CPUs and 8 GiB, and can pick strict but never open.
Example: a strict organization
A strict organization: no web, no host access, every change reviewed.
openshell:
enabled: true
admin:
required_pack: strict
allow_yolo: false
allow_mount: false
allow_host_ports: false
allow_unblock: false
allow_learn_mode: false
allowed_harnesses: [claudecode]
max_resources:
cpu: "2"
memory: 4Gi
locked: [workdir.unmask]Every run uses strict: no web beyond the model provider, manual approval of every request, a copy, prompts kept, no MCP servers. With allow_unblock: false, approvals cannot be kept and a one-time approval cannot reach a blocklisted, feed-listed or private destination. To limit one-time approvals of other hosts, list the permitted hosts in egress_allow_only.
Related
- Sandbox network: how the proxy decides each site.
Network and egress
How DefenseClaw's egress proxy decides every site a sandboxed agent contacts, the open, balanced and strict network profiles, the blocklist, unblocks, asks, large-upload alerts and what the agent is told when it is blocked.
Sandboxes in the TUI and macOS app
Watch and manage OpenShell sandboxes from the DefenseClaw terminal UI's Sandboxes panel or the macOS app's Sandboxes view, menu bar and notifications, and run sandbox setup from either.