Governing sbx fleets

Two things exist: policies, and the rules inside them. A rule has a decision (allow or deny), an action (connect:tcp/connect:udp for network, read/write for filesystem), and a resource it matches. Policies live at two levels — local (per machine, sbx policy CLI) and organization (Docker Home, or the Governance API). MCP policy is Cedar-based and belongs to wiring-sbx-mcp-servers; this skill covers network, filesystem, audit, and sign-in.

A developer chasing a blocked request should land in diagnosing-sbx-sandboxes. This skill is for the person who writes the policy that blocked them.

The one rule that explains most surprises

Organization governance makes local and kit allow rules inactive; it never touches deny rules from any source. Once an org policy is enforced, only an org allow rule can grant access — a local sbx policy allow sits in the store but does nothing. A local or kit deny, by contrast, still fires on top of the org policy. This is why "I added an allow rule and nothing changed" is almost always an org-governance question, and "I added a deny rule and it worked" tells you nothing about whether governance is active.

Within org governance, deny always wins and everything is default deny: a request needs some effective policy to allow it and is blocked if any effective policy denies it. Allows across effective policies are additive; denies are absolute — so an org-wide deny can't be loosened by a team-scoped policy, which makes org-wide deny rules useful as guardrails a team can't override.

Filesystem has no local or kit deny rule at all — sbx policy deny is network-only — so once an org filesystem policy is active there is no local lever left to restrict it further.

Creating an organization policy

Requires a separate AI Governance subscription, and by default only organization owners can manage it — grant a custom role with the Governance permission to delegate it.

In Docker Home, under AI Platform, network, filesystem, and MCP policies are separate sections, each with its own rule editor. A policy has a name, a Scope (Organization or Teams), and rules. Network and filesystem rules are built with Add rule; MCP policies are Cedar text.

Team scoping targets existing Docker teams — create the team before you can scope a policy to it, either by hand in Docker Home or by SCIM group mapping, which also creates missing teams and keeps membership synced to your IdP. A developer's effective policies are every org-wide policy plus every team-scoped policy for a team they belong to, so one person is routinely governed by several policies combined per Rule evaluation above.

An optional support message (up to 500 characters, under AI Platform > Manage) is appended to denial output for org-governance blocks only — it never shows for a preset-driven local denial.

Propagation is not instant. A saved policy takes up to 5 minutes to reach a developer machine. sbx policy reset forces an immediate re-pull, but it also deletes the local policy store and stops the daemon (running sandboxes stop too) before prompting for a new preset — it is a bigger hammer than "refresh my policy," not a smaller one.

Filesystem access policies

Filesystem rules gate what a sandbox can mount as a workspace: read for a read-only mount, read and write for a writable one. There is no network-style CIDR/port matching here — resources are host path patterns, one rule format per OS (/data/project/** vs C:\data\project\** vs the WSL UNC form), because a rule matches only the format it is written in.

The mount policy denied trap: a rule written with a single * — e.g. /data/project/* — matches one path segment and stops at the first separator. Sandboxes mount a specific file or subtree, so the segment boundary is hit almost immediately and the mount is denied. The fix is **, which recurses. This is the most common cause of a filesystem denial that "looks like it should obviously work."

Filesystem policy is checked once, at mount time — sandbox creation. Editing the org filesystem policy has zero effect on sandboxes that are already running; they keep whatever access they were created with. To apply a change, remove the sandbox and create a new one. This is a different timing model from network policy, which is re-evaluated on every outbound request — don't assume a filesystem edit landed just because the sync window passed.

Verifying what's actually in force

sbx policy ls is the source of truth, not the policy you think you wrote:

$ sbx policy ls
Governance: Managed by my-org | Sync: OK, last synced 08:21:01 | Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive

The Governance: line only appears when org governance is active — its absence is how you confirm a machine is running on local policy alone. Sync confirms the daemon has the latest org rules; a stale or errored sync means edits in Docker Home haven't landed yet.

sbx policy ls hides inactive (overridden) allow rules by default. Pass --include-inactive to see them with an inactive STATUS — this confirms which of your local allow rules the org policy is currently shadowing, rather than guessing from the precedence table. Filter with --source {local,org,kit} or --decision {allow,deny}, add --wide for rule IDs, or use sbx policy inspect <policy> for one policy in full. sbx policy check network <host> tells you whether a request would be allowed without running a sandbox.

sbx policy reset and sbx reset are not the same command at different verbosity — they have different blast radii. sbx policy reset clears only the local policy store and daemon, then reprompts for a preset; it does not touch sandboxes' data or secrets. sbx reset (optionally --preserve-secrets) stops every VM and deletes all sandbox state — policy, sandbox filesystems, everything except secrets if you passed the flag. Reach for sbx policy reset to force a policy re-sync; reach for sbx reset only when you mean to throw away every sandbox on the machine.

Local policy and presets

A fresh machine with no org governance prompts for a preset before the first run: Open (equivalent to sbx policy allow network "**"), Balanced (default deny plus a curated allowlist of AI provider APIs, package registries, code hosts, and cloud services — inspect it with sbx policy ls rather than assuming its contents), or Locked Down (default deny, no exceptions, including model provider APIs). Set it non-interactively in CI with sbx policy init {allow-all|balanced|deny-all}.

sbx policy allow|deny network <host> edits take effect immediately and apply to all sandboxes unless scoped with --sandbox <name>. sbx create and sbx run also take --deny-network <host> (repeatable) to set a per-sandbox deny at creation time, appearing in sbx policy ls <name> like any other rule. None of this local tooling matters once org governance enforces allow rules centrally — it still works for deny.

Audit logging

Audit records need three things at once: an AI Governance license on the developer, an enforced organization policy governing them, and Docker Cloud and/or local delivery turned on. A developer missing any one of these — including anyone on a personal account — produces no audit data at all and won't appear in the log or SIEM stream. That silence is expected, not a delivery bug, so check licensing and enforcement before debugging the pipeline.

Two delivery modes, independently toggleable, both configured in Docker Home under AI Platform > Audit logs > Audit Delivery:

Local files rotate to a new .jsonl at 5 minutes, 1000 events, or 50 MiB, whichever comes first, or on clean daemon shutdown. The daemon writes to a .tmp file until rotation, then atomically renames it — point a shipper at .jsonl files only; a .tmp is mid-write and reading it yields partial or duplicate data. Files are never deleted by the sandbox itself; retention is your shipper's job for local delivery.

For Cloud delivery, retention is two independently configured windows: searchable (default 90 days) and archive (default 90 days, must be ≥ searchable). Shortening a window only affects records going forward — it doesn't retroactively delete anything already retained under the old window.

Full field-by-field schema, categories, decisions, and action types are in references/audit-record-schema.md.

SIEM forwarding requires Cloud delivery on first. Configure it under Export & Connectors: Splunk Cloud or self-hosted Splunk Enterprise (HEC endpoint + token, self-hosted needs a publicly-trusted TLS cert), Dynatrace (Log Ingest API + a token with logs.ingest scope), or a custom HTTPS endpoint with a header you name. Docker verifies the endpoint is reachable before saving, so a save failure means connectivity or credentials, not config syntax.

Viewing and exporting (Cloud delivery only) lives under Audit Events in Docker Home: filter by decision and time range, search by principal, resource, event type, or agent. CSV export caps at 1,000,000 rows and the download link expires after 24 hours — re-export rather than expecting the link to still work the next day.

Sign-in enforcement

Sign-in enforcement is the piece that makes organization governance mandatory rather than optional: without it, a developer can sign in with a personal account and skip org policy entirely, since governance is keyed off being signed in as a member of a governed org. Enforcement closes that gap by pinning allowedOrgs in a location only an administrator, not the developer, can write — a macOS managed-preferences profile, a Windows registry key under HKLM, or a root-owned file on Linux.

allowedOrgs (a list of org slugs, matched case-insensitively) is the only required field; leaving it empty or absent leaves enforcement inactive. The optional adminName/adminEmail/adminURL populate the denial message a rejected developer sees. sbx login checks membership after authenticating and immediately revokes credentials on a failed check — sbx login and sbx logout always run regardless, but every other command needs a valid signed-in session and fails until the developer signs in with an allowed account.

Per-platform deployment payloads (the macOS .mobileconfig, the Windows registry values, the Linux file permissions the loader fails closed on) are in references/sign-in-enforcement-deploy.md. One trap worth knowing before you open that file: on macOS, an MDM-deployed profile always beats a local defaults write test value in the same preference domain — if a manual test looks like it's being ignored on a managed device, that's why.

The Governance API

Network and filesystem organization policies can be managed programmatically through the AI Governance API instead of Docker Home — the same policy and rule model, HTTP+JSON. Reach for it when policy needs to be generated or synced from an external system (Terraform, an internal admin dashboard) rather than edited by hand. MCP policy is not exposed there; it stays Cedar-only, in Docker Home or the MCP-specific API surface covered by wiring-sbx-mcp-servers.

Last verified

Verified against the sbx governance docs of 2026-08-07 (re-fetched unchanged on 2026-08-10). Version-gated behavior noted inline: the --deny-network creation flag (v0.38.0) and the expanded Balanced-preset allowlist (v0.35.0). AI Governance — org policy, audit logs, and sign-in enforcement — is a separate paid subscription; treat any claim about what it includes as subject to change and re-check in Docker Home before relying on it.