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