Experiment: host-side API server for sandboxed agents

[maruiz93]

Tracking issue: fullsend-ai/fullsend#879

What should happen

Build a working proof-of-concept of a host-side API server that runs outside an
OpenShell sandbox and is callable by the agent inside. This experiment should
validate assumptions and inform the ADR design (fullsend-ai/fullsend#880).

What to explore

1. Basic API server lifecycle — a minimal HTTP server started by the runner
   on the host side, callable from inside the sandbox via curl through the
   L7 proxy. Verify the network path works (agent → 10.200.0.1:port → server).

2. Credential isolation — the server holds a credential (e.g. a GitHub
   token) and performs operations on behalf of the agent. Verify the credential
   never enters the sandbox.

3. Container build delegation — the API server exposes a build endpoint
   that triggers podman build or docker build on the host. This tests a
   confirmed sandbox limitation: OpenShell's seccomp blocks CLONE_NEWUSER,
   AF_NETLINK, and setns, and the agent has zero Linux capabilities, so
   neither Docker nor rootless podman/buildah can run inside the sandbox
   (NVIDIA/OpenShell#113).
   Also verify whether rootless podman/buildah works inside the sandbox
   directly — if it does, document what changed.

4. API discoverability — try at least two approaches for making the API
   known to the agent (e.g. OpenAPI spec in sandbox, instructions in agent
   definition) and document what works best.

5. Per-run auth — implement a bearer token generated per run, passed to both
   the server and the sandbox, and validated on each request.

6. Long-running operations — test an operation that takes longer than the
   MCP client timeout (~30-60s) to confirm the REST API approach handles it
   where MCP would fail.

7. Policy tuning — write the most restrictive L7 network policy that still
   allows the agent to use the API server. Document what rules were needed.

Context

• ADR issue: ADR: host-side API server design for sandboxed agents fullsend#880
• Feature issue: fullsend run: implement host-side API server lifecycle fullsend#881
• Existing experiments for reference: runner-hello-world/,
  openshell-sandbox-evaluation.md.
• ADRs 0017, 0024, 0025 in fullsend define the credential isolation model and
  harness schema.

[github-actions]

fullsend triage is working on this — view logs

[fullsend-ai-triage]

Triage Summary

This experiment is well-defined and ready for implementation.

Category: Enhancement (PoC / Experiment)
Severity: Medium

Problem

The OpenShell sandbox security model blocks privileged operations (container builds, credential-backed API calls) inside the sandbox. A host-side API server pattern needs to be validated as the solution.

Scope

Seven exploration areas are clearly specified, covering network connectivity, credential isolation, container build delegation, API discoverability, per-run auth, long-running operations, and network policy tuning.

Recommended Approach

Build incrementally — start with basic network path validation (agent → L7 proxy → host server), then layer on credential isolation and container build delegation. Reference existing runner-hello-world/ and openshell-sandbox-evaluation.md experiments for patterns.

Proposed Validation Tests

For each exploration area:
1. Network path: curl from sandbox → host API returns 200
2. Credential isolation: API performs authenticated call; token absent from sandbox env/fs
3. Container build: POST to /build triggers host-side build; podman/docker fails inside sandbox
4. API discoverability: Agent discovers and calls endpoints via each approach
5. Per-run auth: Missing/invalid bearer token → 401; valid token → 200
6. Long-running ops: Operation >60s completes via async/polling pattern
7. Network policy: API calls succeed; other outbound sandbox traffic is blocked

Notes

• Cross-repo references (tracking issue, ADR issue, feature issue in fullsend, and the OpenShell issue) could not be accessed to verify their current state. If any of those represent blocking dependencies, please flag them.
• This experiment feeds into the ADR design, so findings should be documented per exploration area.