|
| 1 | +--- |
| 2 | +title: "55. Provider-backed policy composition" |
| 3 | +status: Accepted |
| 4 | +relates_to: |
| 5 | + - agent-infrastructure |
| 6 | +topics: |
| 7 | + - policy |
| 8 | + - providers |
| 9 | + - composition |
| 10 | + - sandbox |
| 11 | +--- |
| 12 | + |
| 13 | +# 55. Provider-backed policy composition |
| 14 | + |
| 15 | +Date: 2026-06-22 |
| 16 | + |
| 17 | +## Status |
| 18 | + |
| 19 | +Accepted |
| 20 | + |
| 21 | +## Context |
| 22 | + |
| 23 | +ADR 0024 established per-agent harness files with a `policy` field |
| 24 | +pointing to an OpenShell policy YAML. Each policy file contains |
| 25 | +filesystem, process, and network restrictions for one agent. |
| 26 | + |
| 27 | +In practice, every policy file duplicates the same network rule blocks |
| 28 | +for shared services: Vertex AI inference endpoints, GitHub API access, |
| 29 | +package registries (npm, PyPI, Go modules), and gitleaks binary |
| 30 | +downloads. Six agents × four service groups = the same endpoints and |
| 31 | +binaries repeated in every combination. |
| 32 | + |
| 33 | +This duplication creates maintenance burden: when a service adds or |
| 34 | +changes endpoints, every policy file must be updated independently. |
| 35 | +The fix.yaml policy comments "Identical to the code agent policy," |
| 36 | +making the redundancy explicit. |
| 37 | + |
| 38 | +OpenShell v0.0.37 introduced provider-backed policy composition |
| 39 | +(NVIDIA/OpenShell#1037). When a provider is attached to a sandbox and |
| 40 | +has a registered profile, the gateway merges the profile's network |
| 41 | +rules into the effective policy at fetch time under reserved |
| 42 | +`_provider_*` keys. This is additive-only and keeps provider rules |
| 43 | +isolated from user/agent rules. |
| 44 | + |
| 45 | +## Options considered |
| 46 | + |
| 47 | +### Option 1: Monolithic per-agent policies (legacy approach) |
| 48 | + |
| 49 | +Each agent has its own policy YAML with all network rules inline. |
| 50 | +Agent designers specify every endpoint and binary in a single file. |
| 51 | + |
| 52 | +**Pros:** |
| 53 | +- Self-contained — one file per agent, easy to read in isolation. |
| 54 | +- No dependency on providers v2 or OpenShell version. |
| 55 | +- Full control per agent. |
| 56 | + |
| 57 | +**Cons:** |
| 58 | +- Duplicated network blocks across agents. |
| 59 | +- Maintenance burden grows with agent count and service count. |
| 60 | +- Easy to drift — one agent's policy gets an endpoint fix, others |
| 61 | + don't. |
| 62 | + |
| 63 | +### Option 2: Composable policies with agent designer freedom |
| 64 | + |
| 65 | +Provide composable provider profiles as an option. Agent designers |
| 66 | +choose whether to use providers for network access or keep inline |
| 67 | +network rules. A shared `base.yaml` covers filesystem, landlock, and |
| 68 | +process restrictions. Agents can mix: use providers for common services |
| 69 | +and inline rules for agent-specific endpoints. |
| 70 | + |
| 71 | +**Pros:** |
| 72 | +- Flexible — agent designers pick the approach that fits. |
| 73 | +- Incremental adoption — no big-bang migration needed. |
| 74 | +- Lowest friction to introduce — no convention change required. |
| 75 | + |
| 76 | +**Cons:** |
| 77 | +- Two ways to do the same thing — harder to reason about effective |
| 78 | + policy. |
| 79 | +- Duplicated endpoints may reappear if designers don't adopt providers. |
| 80 | +- No single source of truth for a service's endpoints. |
| 81 | + |
| 82 | +### Option 3: All network access through providers (chosen) |
| 83 | + |
| 84 | +Provider profiles are the single mechanism for granting network access. |
| 85 | +Policy files define only non-composable sandbox restrictions: |
| 86 | +filesystem access, landlock, and process identity. A single |
| 87 | +`base.yaml` replaces per-agent policy files for these non-network |
| 88 | +concerns. Harnesses declare which providers they need — each |
| 89 | +contributes network rules via composition. |
| 90 | + |
| 91 | +**Pros:** |
| 92 | +- Single source of truth per service — endpoint changes update one |
| 93 | + profile. |
| 94 | +- Policy files are small and uniform (no network section). |
| 95 | +- Clear separation: profiles own network access, policies own sandbox |
| 96 | + restrictions. |
| 97 | +- New agents get network access by declaring providers, not copy-pasting |
| 98 | + endpoint blocks. |
| 99 | + |
| 100 | +**Cons:** |
| 101 | +- Requires OpenShell >= v0.0.37 and `providers_v2_enabled`. |
| 102 | +- Agent designers must understand the provider model. |
| 103 | +- Credential-less providers require a workaround |
| 104 | + ([NVIDIA/OpenShell#1978](https://github.com/NVIDIA/OpenShell/issues/1978)). |
| 105 | + |
| 106 | +## Decision |
| 107 | + |
| 108 | +**Adopt Option 3 as a best practice for fullsend scaffold agents.** |
| 109 | + |
| 110 | +The scaffold ships with provider profiles for shared services and a |
| 111 | +single `base.yaml` policy. Scaffold harnesses declare providers instead |
| 112 | +of inline network rules. |
| 113 | + |
| 114 | +This is a best practice, not an enforcement. Custom agents with inline |
| 115 | +network policies continue to work — composition is additive, so |
| 116 | +duplicated rules between providers and inline policies are redundant |
| 117 | +but harmless. Agent designers who bring their own agents can choose |
| 118 | +whichever approach fits their needs. The scaffold serves as the |
| 119 | +reference implementation. |
| 120 | + |
| 121 | +Five custom profiles ship with the scaffold: |
| 122 | + |
| 123 | +| Profile ID | Service | Access | |
| 124 | +|---|---|---| |
| 125 | +| `fullsend-vertex-ai` | Anthropic API, Google Cloud APIs | read-write | |
| 126 | +| `fullsend-github` | GitHub API, Git transport | read-write | |
| 127 | +| `fullsend-package-registries` | npm, PyPI, Go modules | read-only | |
| 128 | +| `fullsend-gitleaks` | GitHub releases for gitleaks | read-only | |
| 129 | +| `fullsend-github-artifacts` | GitHub Actions artifact download | read-only | |
| 130 | + |
| 131 | +Custom profiles are used instead of OpenShell built-ins because they |
| 132 | +bundle endpoint combinations specific to fullsend (e.g., |
| 133 | +fullsend-vertex-ai combines Anthropic API + GCP APIs). |
| 134 | + |
| 135 | +Provider definitions use dummy credentials as a workaround for |
| 136 | +[NVIDIA/OpenShell#1978](https://github.com/NVIDIA/OpenShell/issues/1978) |
| 137 | +— providers exist for network policy contribution only. Credential |
| 138 | +delivery continues via host_files (ADR 0025 tier 4). |
| 139 | + |
| 140 | +The `providers_v2_enabled` setting and profile imports are managed |
| 141 | +automatically by `fullsend run`. |
| 142 | + |
| 143 | +## Consequences |
| 144 | + |
| 145 | +- Scaffold agents use provider profiles for all network access. Policy |
| 146 | + files contain only filesystem, landlock, and process restrictions. |
| 147 | +- Network rules for each service are defined once in a profile YAML. |
| 148 | + Adding or changing endpoints updates one file. |
| 149 | +- All scaffold agents share a single `policies/base.yaml`. Per-agent |
| 150 | + policy files are eliminated from the scaffold. |
| 151 | +- Custom agents are not required to adopt this pattern. Inline network |
| 152 | + policies continue to work, but the scaffold and guides recommend |
| 153 | + providers as the preferred approach. |
| 154 | +- The building-custom-agents guide is updated to show providers as |
| 155 | + the recommended way to grant network access. |
| 156 | +- Requires OpenShell >= v0.0.37 and the `providers_v2_enabled` gateway |
| 157 | + setting (set automatically). |
| 158 | +- Single profile per service means all agents get the broadest access |
| 159 | + level (read-write for GitHub). If per-agent access differentiation |
| 160 | + is needed later, split into separate profiles (e.g., |
| 161 | + fullsend-github-rw, fullsend-github-ro). |
0 commit comments