Skip to content

Commit 2d17fc7

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 558cbc4 commit 2d17fc7

17 files changed

Lines changed: 378 additions & 1203 deletions

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

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

‎docs/architecture.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ Sandbox defaults (network policy, filesystem restrictions) are configured in the
7070
- 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?
7171
- ~~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.
7272

73+
**Decided:**
74+
75+
- 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)).
76+
7377
## Agent Harness
7478

7579
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.

‎docs/guides/user/building-custom-agents.md‎

Lines changed: 48 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -117,19 +117,23 @@ model: opus
117117
image: ghcr.io/fullsend-ai/fullsend-sandbox:latest
118118
policy: customized/policies/my-agent.yaml
119119

120+
providers:
121+
- vertex-ai # Required: model access (Anthropic API + GCP)
122+
- github # GitHub API + Git transport
123+
120124
host_files:
121125
# GCP credentials for Vertex AI (required for model access)
122126
- src: env/gcp-vertex.env
123-
dest: /tmp/workspace/.env.d/gcp-vertex.env
127+
dest: /sandbox/workspace/.env.d/gcp-vertex.env
124128
expand: true
125129
- src: ${GOOGLE_APPLICATION_CREDENTIALS}
126-
dest: /tmp/workspace/.gcp-credentials.json
130+
dest: /tmp/.gcp-credentials.json
127131
- src: ${GCP_OIDC_TOKEN_FILE}
128-
dest: /tmp/workspace/.gcp-oidc-token
132+
dest: /sandbox/workspace/.gcp-oidc-token
129133
optional: true
130134
# Your custom input files (written by pre-script)
131135
- src: /tmp/workspace/my-input.json
132-
dest: /tmp/workspace/my-input.json
136+
dest: /sandbox/workspace/my-input.json
133137
optional: true
134138

135139
skills:
@@ -170,6 +174,8 @@ The agent never has direct access to credentials. The pre-script uses credential
170174

171175
## Step 3: Define the sandbox policy
172176

177+
The sandbox policy controls filesystem, process, and landlock restrictions. Network access is handled separately through provider profiles (see below).
178+
173179
Create `.fullsend/customized/policies/my-agent.yaml`:
174180

175181
```yaml
@@ -183,43 +189,58 @@ landlock:
183189
process:
184190
run_as_user: sandbox
185191
run_as_group: sandbox
192+
```
193+
194+
Most custom agents can reuse the scaffold's `policies/base.yaml` instead of creating their own. Override only when your agent has specific filesystem or process requirements.
195+
196+
### Network access via providers (recommended)
197+
198+
The recommended way to grant network access is through provider profiles declared in the harness. Add a `providers` field to your harness YAML:
199+
200+
```yaml
201+
providers:
202+
- vertex-ai # Anthropic API + GCP (required for model access)
203+
- github # GitHub API + Git transport
204+
- package-registries # npm, PyPI, Go modules (optional)
205+
```
206+
207+
Each provider has a profile that defines its endpoints and binaries. When the sandbox starts, the gateway composes these profiles into the effective network policy automatically. This keeps endpoint definitions in one place and avoids copy-pasting network blocks across agents.
208+
209+
The scaffold ships with profiles for common services. To see what's available:
210+
211+
```bash
212+
ls .fullsend/providers/ # provider definitions (name + type)
213+
ls .fullsend/profiles/ # profile YAMLs (endpoints + binaries)
214+
```
215+
216+
For services not covered by existing profiles, you can either create a custom profile or use inline `network_policies` in your policy YAML (both approaches work — composition is additive).
217+
218+
### Network access via inline policies (alternative)
219+
220+
You can also define network rules directly in the policy YAML. This is useful for one-off endpoints specific to a single agent:
221+
222+
```yaml
186223
network_policies:
187-
# Required: Vertex AI for model access
188-
vertex_ai:
189-
name: vertex-ai
190-
endpoints:
191-
- host: "*.googleapis.com"
192-
port: 443
193-
protocol: rest
194-
enforcement: enforce
195-
access: read-write
196-
- host: "api.anthropic.com"
197-
port: 443
198-
protocol: rest
199-
enforcement: enforce
200-
access: read-write
201-
binaries:
202-
- path: "**/claude"
203-
- path: "**/node"
204-
# Optional: GitHub API access (if agent needs it)
205-
github_api:
206-
name: github-api
224+
my_service:
225+
name: my-service
207226
endpoints:
208-
- host: "api.github.com"
227+
- host: "api.example.com"
209228
port: 443
210229
protocol: rest
211230
enforcement: enforce
212231
access: read-only
213232
binaries:
214-
- path: "**/gh"
215233
- path: "**/curl"
216234
```
217235

236+
Inline rules and provider-composed rules coexist — composition is additive. If both define the same endpoint, the duplicate is harmless.
237+
218238
### Policy design principles
219239

220-
- **Vertex AI is always required** — the agent needs it to talk to the LLM.
240+
- **Vertex AI is always required** — the agent needs it to talk to the LLM. Use the `vertex-ai` provider.
221241
- **Add network access only for what the agent needs.** If the agent doesn't need web search, don't allow it.
222242
- **Use `binaries` to restrict which programs can access each endpoint.** This prevents the agent from using unexpected tools to exfiltrate data.
243+
- **Prefer providers for shared services.** Use inline policies only for agent-specific endpoints.
223244
- **Never allow Jira/internal APIs from the sandbox.** All Jira reads happen in pre-scripts; all Jira writes happen in post-scripts.
224245

225246
## Step 4: Define the output schema

0 commit comments

Comments
 (0)