Policy concepts

Resource model

Docker sandbox governance is built around two resource types: policies and rules.

A policy is a named collection of rules that controls sandbox access. Policies exist at two levels:

• Local: configured per machine using the sbx policy CLI. Applies to sandboxes on that machine only.
• Organization: configured in Docker Home. Network and filesystem policies can also be managed via the Governance API. Applies to sandboxes across the organization. An organization can have several policies, each applying either org-wide or to specific teams. See Policy scope.

When organization governance is active, only organization allow rules can grant access. Local and kit-defined deny rules still apply on top. See Precedence.

A rule is the unit of access control within a policy. Each rule has:

• Name: a human-readable label
• Actions: the type of access the rule controls
• Resources: the targets the rule matches against
• Decision: allow or deny

Rules are grouped by domain. Network and filesystem rules in a policy must share the same domain, either network or filesystem. MCP policies use Cedar statements written in the MCP namespace instead of the network and filesystem rule format.

Policy scope

Each organization policy applies either across the whole organization or only to specific teams:

• Org-wide: with no teams assigned, the policy applies to every member of the organization.
• Team-scoped: with one or more teams assigned, the policy applies only to members of those teams.

Teams are the same teams you manage for your organization; Docker matches a policy's teams against each user's team membership. Because an organization can mix org-wide and team-scoped policies, a single user is often subject to several at once. The policies that apply to a given user are their effective policies: every org-wide policy, plus every team-scoped policy for a team they belong to. See Rule evaluation for how a user's effective policies combine.

Rule syntax

Network rules

Network rules use the action connect:tcp. Resources are hostnames, CIDR ranges, or ports. The governance policy schema also accepts connect:udp, but Docker Sandboxes always blocks direct external UDP and ICMP. connect:udp rules have no effect.

Hostname patterns

example.com and *.example.com don't cover each other. Specify both if you need to match the root domain and its subdomains.

CIDR ranges

Both IPv4 and IPv6 notation are supported: 10.0.0.0/8, 192.168.1.0/24, 2001:db8::/32.

For local and organization policy configuration, see Network access policies.

Filesystem rules

Filesystem rules use the actions read and write. Resources are host paths that sandboxes can mount as workspaces.

A workspace mounted with write access must be allowed by both a read and a write rule; a read-only workspace needs only read. When default deny blocks a mount, the denial reason names whether read or write access was missing.

~ expands to the user's home directory on every platform, including Windows, where it resolves to %USERPROFILE%. A single ~/** rule therefore matches each user's home tree on macOS, Linux, and Windows. The policy engine expands only ~: it does not expand environment variables, so a pattern such as %USERPROFILE%\** or $HOME/** matches nothing.

For a path outside the home directory, write it in the format the user's operating system uses. A rule matches only the format it's written in, so a location that several platforms share needs a rule for each:

On Windows, *: matches any drive letter, so *:\data\** matches the path on any drive.

Wildcards behave the same way in every path format:

Use ** to match a directory tree recursively. A single * matches within one path segment and won't cross a path separator. For example, ~/** matches all paths under the home directory, while ~/* matches only its direct children.

For organization policy configuration and enforcement details, see Filesystem access policies.

MCP policies

MCP policies control Model Context Protocol activity made available to a sandbox through Docker's MCP gateway. They are organization policies written in Cedar using the MCP namespace, rather than the network and filesystem rule format.

MCP policy applies when a developer registers a server and when an agent uses the MCP gateway. Registration rules control future sbx mcp add operations. Use-time rules control tool calls, gateway meta-tools, resource reads, and prompt retrieval from servers that are already registered or loaded.

Governed MCP activity is default deny: a request is blocked unless a matching permit allows it. A matching forbid overrides any permit, including a permit that requires approval. Policy scope supplies the principal, so use organization or team scope instead of matching users, teams, tenants, or roles in Cedar.

For representative policies, see MCP access policies. For exact action, resource, context, and approval behavior, see the MCP policy reference.

Rule evaluation

When organization governance is active, the rules from all of a user's effective policies are combined and evaluated together against each request, following two principles:

• Deny wins: if any rule matches with decision: deny, the request is denied, regardless of any matching allow rules.
• Default deny: anything an allow rule doesn't match is blocked. Outbound network traffic is blocked unless a network rule allows the destination, and a host path can't be mounted unless a filesystem rule allows it. MCP activity is blocked unless an MCP permit allows it.

Because every effective policy feeds the same evaluation, allows are additive (a request is allowed if any effective policy allows it) and denies are absolute (a request is blocked if any effective policy denies it). A deny rule in an org-wide policy therefore applies to everyone and can't be overridden by a team-scoped policy, which makes org-wide deny rules useful as guardrails.

Local and kit-defined allow rules take no part in this evaluation. Deny rules from those sources do still apply. See Precedence.

Precedence

What applies depends on whether your organization has governance enabled:

• No organization governance: local rules and any kit-defined network rules determine what sandboxes can access.
• Organization governance active: organization policy determines what access can be granted. Only organization allow rules grant access, so local and kit-defined allow rules are inactive and can't expand what the organization permits. Deny rules apply from every source, so a local or kit-defined deny can still restrict access further.

Precedence is decided by a rule's decision rather than its source:

Local and kit-defined rules cover network access only, so a deny that layers on top of organization policy is always a network deny. sbx policy ls hides inactive rules by default. See Monitoring for how to list them.

When organization governance is active, a user's organization policies are evaluated together, as described in Rule evaluation.