Skip to content

Commit a3c9513

Browse files
committed
fix(sandbox): resolve OpenShell CLI compatibility issues
- Update `settings set` call to use --key/--value flags and --yes - Make profile import idempotent by deleting before reimport - Add unique dummy credentials (_NOOP_<NAME>) for policy-only providers that have no real credentials (OpenShell CLI requires a credential source; see NVIDIA/OpenShell#1978) - Use inline KEY= form for empty credentials to avoid env var lookup - Filter provider creation to only harness-declared providers - Remove GH_TOKEN from github provider (injected via host scripts) Signed-off-by: Marta Anon <[email protected]>
1 parent 7739f39 commit a3c9513

22 files changed

Lines changed: 432 additions & 1213 deletions

‎docs/ADRs/0046-provider-backed-policy-composition.md‎

Lines changed: 0 additions & 104 deletions
This file was deleted.
Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
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)).

‎docs/architecture.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,10 @@ Sandbox defaults (network policy, filesystem restrictions) are configured in the
7272
- Does the sandbox provide a pre-built environment (tools, language runtimes, repo clones), or does the agent set up its own workspace within the sandbox?
7373
- ~~Is the sandbox the same for all agent roles, or does each role get a differently-scoped sandbox?~~ Decided in [ADR 0020](ADRs/0020-composable-single-responsibility-agents-with-individual-sandboxes.md): each agent gets its own sandbox with policies designed for its responsibility.
7474

75+
**Decided:**
76+
77+
- Provider-backed policy composition: network access is granted through provider profiles declared in harness files. Policy files define only non-composable sandbox restrictions (filesystem, landlock, process). A single `base.yaml` replaces per-agent policy files in the scaffold. Inline `network_policies` continue to work but providers are the recommended approach ([ADR 0055](ADRs/0055-provider-backed-policy-composition.md)).
78+
7579
## Agent Harness
7680

7781
The configuration and context layer that prepares an agent for its task. Responsible for providing skills, system prompts, codebase context, tool definitions, and behavioral instructions to the agent runtime.
@@ -590,7 +594,8 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
590594
║ │ Loads harness/code.yaml: │ ║
591595
║ │ agent: agents/code.md │ ║
592596
║ │ image: ghcr.io/fullsend-ai/fullsend-code:latest │ ║
593-
║ │ policy: policies/code.yaml │ ║
597+
║ │ policy: policies/base.yaml │ ║
598+
║ │ providers: [vertex-ai, github, package-registries] │ ║
594599
║ │ skills: [skills/code-implementation] │ ║
595600
║ │ pre_script: scripts/pre-code.sh │ ║
596601
║ │ post_script: scripts/post-code.sh │ ║
@@ -601,7 +606,7 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
601606
║ │ ┌───────────────────────────────────────────────────────┐ │ ║
602607
║ │ │ OPENSHELL SANDBOX │ │ ║
603608
║ │ │ │ │ ║
604-
║ │ │ Created with --from image, --policy code.yaml. │ │ ║
609+
║ │ │ Created with --from image, --policy base.yaml. │ │ ║
605610
║ │ │ Bootstrapped via openshell upload/exec: │ │ ║
606611
║ │ │ agent def → /sandbox/claude-config/agents/ │ │ ║
607612
║ │ │ skills → /sandbox/claude-config/skills/ │ │ ║

0 commit comments

Comments
 (0)