Sandbox Policies and Providers

A SandboxPolicy sets the perimeter of every sandbox admitted under the bundle: which hosts it can reach and how, which paths it can read and write, and which identity its processes run as. APF projects it into OpenShell’s sandbox policy when the bundle is loaded and injects it at admission, and OpenShell enforces it at Layer 1 on every call. APF does not evaluate it per request.

Provider documents declare the services an agent may use and the credentials OpenShell injects for them.

A First Example

This policy lets gh and curl read from the GitHub API and nothing else:

apiVersion: nvidia.agent-policy-fabric.sandbox/v1alpha1
kind: SandboxPolicy
metadata:
  name: default
spec:
  filesystem:
    include_workdir: true
    read_only: [/usr, /lib, /etc]
    read_write: [/sandbox, /tmp]
  landlock:
    compatibility: best_effort
  process:
    run_as_user: sandbox
    run_as_group: sandbox
  network_policies:
    github:
      name: github
      binaries:
        - path: /usr/bin/gh
        - path: /usr/bin/curl
      endpoints:
        - host: api.github.com
          port: 443
          protocol: rest
          access: read-only
          enforcement: enforce

Egress is deny-by-default. Only the endpoints listed under network_policies are reachable, and only by the listed binaries.

Which Sandbox Policy Is Used

The interceptor injects the SandboxPolicy whose metadata.name matches the gateway’s --document-name, which defaults to default. A bundle may carry several sandbox policies with different names, and each projects to its own openshell.sandbox.v1/<name> document.

Filesystem, Landlock, and Process

These values pass through to OpenShell unchanged. Refer to OpenShell sandbox policies for how OpenShell enforces each one.

Network Policies

network_policies is a map of named rules. Each rule lists endpoints and, optionally, the binaries allowed to open connections to them. The map key identifies the rule. name defaults to the key.

Endpoints

The authoring schema enforces these combinations:

• tcp endpoints cannot use access, rules, deny_rules, or enforcement.
• rest, websocket, graphql, and sql endpoints need access or at least one rule.
• json-rpc endpoints need at least one rule and cannot use access.
• mcp endpoints need at least one rule or mcp.allow_all_known_mcp_methods: true, and cannot use access.
• deny_rules require a Layer 7 protocol.

Layer 7 Rules

Each entry in rules has one allow object. Each entry in deny_rules is the match object itself. The fields that apply depend on the protocol:

endpoints:
  - host: httpbin.org
    port: 443
    protocol: rest
    enforcement: enforce
    rules:
      - allow:
          method: POST
          path: /anything

Refer to OpenShell network rules for the matching semantics of each protocol and preset.

Binaries

binaries restricts which executables may open connections governed by the rule. Each entry has a path. Refer to OpenShell network rules for how OpenShell identifies the calling binary.

Credential Controls

Endpoints can also carry request_body_credential_rewrite and websocket_credential_rewrite. APF accepts credential_binding and allow_uninspected_credentials but does not project them in this release: OpenShell always receives no binding and allow_uninspected_credentials: false. Refer to Credential Integration.

Selecting APF’s Middleware

network_middlewares attaches supervisor middleware to destination hosts. Add an entry that selects APF’s middleware for every host whose requests APF should evaluate at Layer 2:

network_middlewares:
  apf_content_policy:
    name: APF content policy
    middleware: apf-content-policy
    order: 10
    on_error: fail_closed
    endpoints:
      include:
        - "api.github.com"
        - "httpbin.org"

APF’s middleware takes no configuration, so an APF SandboxPolicy has no config field for it, and a config key fails compilation. The authoring schema allows at most 10 middleware entries, and OpenShell requires each entry’s order to be unique. APF does not check either limit. A host that no entry selects is never evaluated by APF, even if it is reachable at Layer 1.

Providers

A Provider document declares a service the agent may use: its category, endpoints, permitted binaries, and credentials.

apiVersion: nvidia.agent-policy-fabric.policy/v1alpha1
kind: Provider
metadata:
  name: slack
  title: Slack
  description: Slack Web API, workspace messaging.
spec:
  type: messaging
  endpoints:
    - host: slack.com
      port: 443
      protocol: rest
      access: read-write
      enforcement: enforce
  binaries:
    - /usr/bin/curl
  credentials:
    - name: bot_token
      envVars: [SLACK_TOKEN]
      required: true
      style: bearer
      header: Authorization
      source:
        kind: host-env
        name: SLACK_TOKEN

Bundles may also carry OpenShell-native provider profiles as kind: ProviderProfile documents or as profiles with a top-level id and endpoints. They pass through unchanged. When a Provider and a native profile share a name, the Provider wins.

When APF governs the OpenShell gateway, providers and profiles that the bundle does not manage cannot be created or imported. Refer to Credential Integration.

Next Steps

• To govern what the agent does within reachable endpoints, refer to Capability Grants.
• For the full field list, refer to Policy Schemas.