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

PackWeb accessYour projectSkip-permissions
open (default)Any site by name, except the blocklist, private networks and this machineMounted liveOn
balancedA curated developer allowlistMounted liveOn
strictNone, only the model providerCopiedOff

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.

Settingopen (default)balancedstrict
Web accessAny site by name, except the blocklist, private networks and this machineOnly the curated developer allowlistNone; only the harness's model provider
Connection requests (approvals.mode)autotriagemanual
Proxy ports80, 44380, 443443, for approved connections only (the proxy is off)
Large-upload alert25 MiB10 MiB5 MiB
Your projectMounted liveMounted liveCopied; changes come back as a patch or branch
Copy size limit500 MiB500 MiB200 MiB
Skip-permissions modeOnOnOff
MCP serversBrought alongBrought alongLeft behind
The repository's own MCP serversStay stoppedStay stoppedStay stopped
Host ports for MCP serversCan be openedCan be openedNever
Hook failureTool call deniedTool call deniedTool call denied
Hook tamper, silent hooksReported, sandbox keeps runningSandbox stoppedSandbox 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.com

An 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 balanced

For 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-web

A 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 65535

Extend 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.feeds and harness.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 openshell keys, the run's options and openshell.admin apply.
  • 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: false keeps 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 valueLoads
Empty or omittedThe open pack.
open, balanced, strictThe embedded pack.
Another name, such as team-web<pack_dir>/team-web/pack.yaml.
An absolute path or ~/ pathThat pack.yaml, or the one inside that directory. Relative paths are refused.
KeyRequiredDefaultRules
versionYesMust be 1.
nameYesLowercase 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.
descriptionNoEmptyAt most 1024 characters.
extendsNoA built-in pack name or a custom pack name in pack_dir. Paths are refused.
network.modeYesopen, allowlist or deny. Maps to profile open, balanced, strict.
approvals.modeYesauto, triage or manual.
observe.process_treeNofalsetrue samples the sandbox's processes every 5 seconds (15 on a Mac when sampling its MicroVM is slow).
egress.feedsNo[builtin]Only builtin; [] turns the feed off. At most 16.
egress.blockNo[]Host patterns. At most 1024.
egress.allowNo[]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.portsNo[80, 443]Ports 1-65535. At least one unless network.mode is deny. At most 64.
egress.large_upload_mbNo250-1048576. 0 turns the report off.
egress.block_large_uploadsNofalsetrue also cuts the upload that crosses large_upload_mb and refuses later requests to the host.
workspace.modeYesmount or copy.
workspace.masksNo[]Project globs of secret files to hide. At most 1024.
workspace.unmaskNo[]Project globs kept visible anyway, such as .env.example.
workspace.reviewNo[]Project globs of files that can run code, called out at the end of a session.
workspace.max_upload_mbNo500Size limit of the copy in copy mode, 1-1048576.
harness.yoloYestrue or false: skip-permissions mode.
harness.allowedNo[] (any)Harness names such as claudecode and codex. claude-code is read as claudecode. At most 64.
mcp.importYesWhether your own MCP servers come along.
mcp.host_portsYesWhether host ports may be opened for MCP servers on your machine.
mcp.blocked_toolsNo[]Tool names or globs. At most 1024.
mcp.project_serversNoblockblock or allow: whether the MCP servers a repository defines may start.
hooks.fail_modeYesMust be closed.
hooks.on_tamperNoalert when network.mode is open, else stopstop or alert.
hooks.on_silenceNoalert when network.mode is open, else stopstop or alert, for user-tier harnesses. A managed-tier harness only alerts.
hooks.silence_afterNo10m1m 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.yaml

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

  1. The pack supplies every default.
  2. Your openshell keys in config.yaml override the pack (Configuration).
  3. Per-run options of sandbox run: --pack, --profile, --copy, --safe, --unmask, --host-port, --no-mcp, --cpu, --memory.
  4. The repository policy narrows the result. A looser one refuses the run.
  5. openshell.admin clamps the result. A harness it does not allow is refused.
SettingHow the layers combine
ProfileThe pack's network mode, then openshell.profile, then --profile. Each replaces the one before. Admin floors raise it.
ApprovalsThe pack's mode, never looser than the profile: balanced triages at least, strict is manual.
Skip-permissionsThe pack's harness.yolo, then openshell.yolo, then the run. Keeping the prompts for a run always wins.
Allowed harnessesThe pack's list and admin.allowed_harnesses. Only harnesses on both run.
Process treeThe pack's value, --process-tree, or a repository policy with observe.process_tree: true. Nothing turns a pack's true off.
Workspace modeThe pack's mode, then openshell.workdir.mode, then copy mode for a run.
Secret masksThe pack's plus openshell.workdir.masks. Masks can be added, not removed.
UnmaskThe pack's plus openshell.workdir.unmask plus the run's entries.
Review listThe pack's plus DefenseClaw's own list, which no pack can drop.
Block listThe pack's plus openshell.egress.block.
Proxy portsThe pack's, or openshell.egress.ports, which replaces them.
MCP importThe pack's, then openshell.mcp.import, then leaving MCP servers behind for a run.
Host portsopenshell.mcp.host_ports plus the run's ports. Each port is checked.
Resourcesopenshell.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
KeyWhat it does
versionRequired, 1.
network.modeallowlist or deny: a floor.
approvals.modetriage or manual: a floor.
egress.blockHost patterns added to the block list.
egress.portsThe ports the project needs. A list that keeps none refuses the run, unless the network mode is deny.
egress.large_upload_mbLowers the threshold (1 or more).
egress.block_large_uploadstrue turns the block on.
workspace.modecopy.
workspace.masks, workspace.reviewGlobs added to the masks and the review.
harness.yolofalse: the harness keeps its prompts.
mcp.importfalse: your MCP servers stay behind.
mcp.blocked_toolsMCP tools added to the blocked tools.
hooks.on_tamper, hooks.on_silencestop.
observe.process_treetrue.

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

The 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 packWhy
extends: balancedThe pack starts from the balanced pack.
Hosts to allowEvery host the sandbox reached that balanced does not cover, each with a comment naming the programs that reached it.
Comments onlyHosts 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 myapp

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

defenseclaw sandbox policy suggest --pack-out: the pack it wrote, extending balanced and allowing one host with the program that reached it, then comments listing the hosts balanced already covers, the host that was only ever refused, the shadow AI host and the sandbox's model provider

~/code/myapp
Recorded on DefenseClaw 1.0.4 from a real Claude Code sandbox on Linux after a session on the 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 json

The 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 explain

The Pack row names your pack, and each setting shows the layer that set it.

defenseclaw sandbox policy test --sandbox myapp-claude --host pastebin.com:443: the destination is blocked by a blocklist feed entry, with the rule, the source and the reason

~/code/myapp
Recorded on DefenseClaw 1.0.4 on Linux; on an unmanaged computer, 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 loosen

A malformed value, such as an unknown locked key or a bad digest, is a configuration error.

KeyEffect
required_packEvery 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_digestsha256: 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_profileThe loosest profile any run may use (open < balanced < strict). A looser one is raised.
allow_yolo: falseSkip-permissions mode is off for every harness.
allow_mount: falseEvery run uses copy mode and no host folder is bind-mounted, including read-only reference folders.
allow_host_ports: falseNo host port is opened, from config, a run or an approval.
allow_unblock: falseBlocked 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: falseLearn mode (the sandbox API's learn option) is refused.
allowed_harnessesOnly these harnesses run (claude-code and claudecode are the same). With the pack's harness.allowed, only harnesses on both lists.
egress_blockBlocked for every sandbox, checked first. A host name also blocks its subdomains. Neither unblock nor approval opens them.
egress_allow_onlyThe 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_uploadsTurns 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_forProject 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_resourcesCeilings. 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.
lockedopenshell keys per-run options may not loosen.

locked

Locked keyWhat a run can still do
packChoose a pack at least as strict as the configured pack in every setting, or one with the same content.
profileChoose a stricter profile.
yoloKeep the harness prompts.
workdir.modeSwitch to copy mode.
workdir.unmaskUnmask only entries the pack or openshell.workdir.unmask already lists.
mcp.importLeave MCP servers behind.
mcp.host_portsOpen only ports already in openshell.mcp.host_ports.
resourcesAsk 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

ActionRefused by
Unblock a destinationallow_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 onceegress_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 sandboxesEverything above, plus allow_unblock: false on its own
Open a host portallow_host_ports: false, or a pack with mcp.host_ports: false
Mount a host folderallow_mount: false, or a folder covered by require_copy_for
Run in skip-permissions modeallow_yolo: false
Use learn modeallow_learn_mode: false
Run a harnessallowed_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: harness

The 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: profile

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