Add agent execution sandbox architecture ADR - #659
Conversation
Review: #659Head SHA: 8a5c3e4 SummaryThis PR adds ADR-0036 (Agent Execution Sandbox Architecture) and a companion implementation plan for the agent execution environment. The ADR addresses the question explicitly deferred in ADR-0028 (GitLab Support) — verified against ADR-0028 §5 which scopes out agent execution environment as orthogonal to dispatch. The decision to use a shared container image (Docker-first) is well-reasoned, with clear trade-off analysis against three alternatives (platform-specific images, Kubernetes CRDs, minimal sandbox + dynamic tools). The implementation plan correctly defers to ADR-0030 as the authoritative OpenShell interaction model with a prominent disclaimer. The README update adds a previously missing FindingsInfo
FooterOutcome: approve Previous runReview: #659Head SHA: cb8a17f SummaryThis PR adds a well-structured ADR-0036 for the agent execution sandbox architecture and a detailed companion implementation plan. The documents are thorough, present clear trade-off analysis across four options, and include appropriate caveats about illustrative OpenShell configuration. However, the implementation plan contains a broken cross-reference to a non-existent ADR-0029, which must be corrected before merge. FindingsHigh
Medium
Low
Info
FooterOutcome: request-changes Previous run (2)Review: #659Head SHA: a6b6eb0 SummaryThis is a well-structured documentation PR that adds ADR-0036 (Agent Execution Sandbox Architecture) and a companion implementation plan for the agent execution environment. The ADR properly addresses the agent execution question deferred in ADR-0028, presents clear trade-off analysis across four options, and the implementation plan is thorough. Two non-blocking findings: a broken cross-reference in the implementation doc's References section (links to ADR-0029 instead of ADR-0036, likely leftover from the original numbering matching the branch name), and an illustrative token that may trigger automated secret scanners. FindingsMedium
Low
FooterOutcome: comment-only Previous run (3)Review: #659Head SHA: 7308582 SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and an accompanying implementation plan document. The ADR is well-structured, presents four options with clear trade-offs, and makes a defensible decision for a shared Docker-first container image. The implementation document provides detailed, actionable guidance covering the container build pipeline, OpenShell configuration, resource limits, privileged container alternatives, GitLab runner setup, image signing, and upgrade procedures. All cross-references to existing ADRs (0005, 0017, 0025, 0028, 0030) and problem documents are valid. The README update correctly documents the previously-unlisted docs/plans/ directory. No correctness, security, or injection issues were found. FindingsInfo
FooterOutcome: approve Previous run (4)Review: #659Head SHA: 665de4b SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation plan document. The ADR is well-structured with clear options analysis, sound decision rationale favoring a shared container image approach, and honest treatment of consequences and risks. The implementation document provides thorough operational guidance for container builds, OpenShell configuration, resource limits, GitLab runner setup, image signing, and upgrade procedures. The caveat about ADR-0030 overriding illustrative OpenShell interaction details is a good practice that prevents stale design docs from being treated as implementation specs. A few minor observations are noted below but nothing that should block this PR. FindingsMedium
Low
Info
FooterOutcome: comment-only Previous run (5)Review: #659Head SHA: a53603d SummaryThis documentation-only PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation plan. The ADR is well-structured, presents four options with clear trade-offs, and makes a well-reasoned decision for a shared container image approach. All cross-references to existing ADRs (0017, 0025, 0028, 0030) and problem documents (agent-infrastructure.md) are valid. The implementation plan correctly disclaims that OpenShell configuration examples are illustrative and defers to ADR-0030 for the actual interaction model. The README addition appropriately adds a FindingsMedium
Low
Info
FooterOutcome: approve Previous run (6)Review: #659Head SHA: 0c06fd7 SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation plan, along with a README update to surface the FindingsMedium
Low
Info
FooterOutcome: comment-only Previous run (7)Review: #659Head SHA: 27409bf SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation plan for the agent execution environment. The change is well-scoped: it addresses the execution environment question explicitly deferred by ADR-0028 (GitLab support). The ADR follows the repo's established format, presents four options with clear trade-offs, and the decision rationale (shared container image, Docker-first) is well-argued from a security-parity standpoint. The implementation plan provides thorough guidance across build pipeline, OpenShell configuration, resource limits, signing, and cross-platform considerations. The README update correctly adds the FindingsMedium
Low
Info
FooterOutcome: approve Previous run (8)Review: #659Head SHA: dc59975 SummaryThis is a well-structured documentation PR adding ADR-0029 (agent execution sandbox architecture) and a companion implementation plan. The ADR follows established conventions, presents four options with clear trade-offs, and makes a well-reasoned decision for a shared container image approach. The dependency on PR #601 (ADR-0028) is satisfied — that PR is merged. No code changes are included, so platform security, content security, and correctness dimensions are not materially implicated. Two minor style/completeness findings are noted below. FindingsMediumNone Low
Info
FooterOutcome: comment-only Previous run (9)Review: #659Head SHA: 6c94c8a SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation plan document. The design is well-structured, explores four options with honest trade-offs, and makes a clear decision for the shared container image approach. The security discussion (privileged container requirements, rootless alternatives, image signing) is thorough. No critical or high findings. Two medium findings relate to README categorization and a stale ADR-0028 reference. FindingsMedium
Low
Info
FooterOutcome: comment-only Previous run (10)Review: #659Head SHA: 2fe5274 SummaryThis is a well-structured documentation PR that adds ADR-0029 (agent execution sandbox architecture) and a companion implementation document. The ADR follows the repo's template, considers four options with clear trade-offs, and makes a defensible decision for a shared container image approach. The security implications of privileged containers are thoroughly documented with mitigations. Two medium-severity observations are noted below regarding ADR numbering dependency and an unverifiable external reference, neither of which block the PR. FindingsMedium
Low
Info
FooterOutcome: comment-only Previous run (11)Review: #659Head SHA: 1c3ecb8 SummaryThis is a well-structured documentation PR adding ADR-0029 (agent execution sandbox architecture) and a companion implementation document. The ADR thoroughly evaluates four options, justifies the shared-container-image decision with clear security rationale, and documents trade-offs honestly. The implementation document provides comprehensive guidance across container builds, OpenShell configuration, resource limits, image signing, and platform-specific considerations. One medium finding: the implementation document contains a markdown link to FindingsMedium
Info
FooterOutcome: comment-only Previous run (12)Review: #659Head SHA: 8c27c94 SummaryThis is a well-structured documentation PR adding ADR-0029 (Agent Execution Sandbox Architecture) and a companion implementation document ( FindingsMedium
Low
Info
FooterOutcome: comment-only Previous run (13)Review: #659Head SHA: a94832b SummaryThis PR adds ADR-0029 (agent execution sandbox architecture) and a companion implementation document for the agent execution environment. The documents are well-structured, present multiple options with trade-offs, and follow the repo's design exploration conventions. The decision rationale is sound — a shared container image provides environment parity across GitHub Actions and GitLab CI, which is a genuine security requirement. Several findings are worth noting: the example Dockerfile references an undefined build stage, the GitLab runner setup example mounts the Docker socket (contradicting the security isolation goals), and the ADR references documents (ADR-0028, gitlab-implementation.md) that don't yet exist in the repo. None of these block the PR — they are design document quality issues that should be addressed before the ADR moves past "Proposed" status. FindingsMedium
Low
Info
FooterOutcome: comment-only |
Addresses the open question from GitLab implementation (PR fullsend-ai#601) about how agents execute on GitLab runners vs GitHub Actions. Key decisions: - Shared container image (ghcr.io/fullsend-ai/agent-sandbox) for both GitHub Actions and GitLab CI - OpenShell as PID 1 with nested sandboxes for individual agents - Docker and Kubernetes executors supported (shell executor excluded) - Privileged container requirement for OpenShell network namespace manipulation - Resource limits and timeout enforcement per platform - Image signing with Sigstore for supply chain integrity The ADR explores four options: 1. Shared container image, Docker-first (chosen) 2. Platform-specific images (rejected: maintenance burden, inconsistent security) 3. Kubernetes-native with CRDs (rejected: poor fit for ephemeral task execution) 4. Minimal sandbox + dynamic tools (rejected: violates zero-trust execution) Implementation details moved to docs/problems/agent-execution-environment.md: - Container image build pipeline and Dockerfile structure - OpenShell gateway configuration and sandbox creation flow - L7 policy and provider configuration examples - Platform-specific considerations (GitHub Actions VMs, GitLab Docker/K8s executors) - Host-side REST server lifecycle in containerized environments - Image signing, verification, upgrade, and rollback procedures Open questions documented: - Rootless OpenShell support (user namespaces, eBPF alternatives) - Image build and distribution strategy (public vs per-org registry) - Builder services for Docker-in-Docker use cases (external Kaniko vs prohibit) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Lint fixes: - Remove gitlab-implementation from ADR frontmatter relates_to (doesn't exist yet) - Update references to ADR-0028 and gitlab-implementation.md to note they are pending in PR fullsend-ai#601 Review findings (Medium): - Add builder stage to Dockerfile example (was missing, would fail to build) - Remove Docker socket mount from GitLab runner registration (security violation - bypasses sandbox isolation) - Update all references to pending GitLab support work (PR fullsend-ai#601 instead of ADR-0028) Review findings (Low): - Remove placeholder OpenShell issue link, describe as upstream feature request instead - Replace non-existent docker/run@v1 action with standard docker run command - Add comment explaining docker login in GitLab job (for pulling additional images, not the base image) All changes address findings from fullsend-ai-review comment-only review. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace markdown link to non-existent ADR-0028 file with plain text noting it is pending in PR fullsend-ai#601. This prevents broken link if this PR merges before fullsend-ai#601. Addresses review finding about broken link in References section. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
**From @maruiz93:** - Add note about Fedora/Podman compatibility consideration in image composition - Clarify language runtimes are for fullsend's built-in agents; BYOA can customize - Clarify harness role as control plane for agent execution - Add disadvantage note about OpenShell feature parity validation needed for Kubernetes vs Docker **From fullsend-ai-review bot:** - Add note that OpenShell configuration examples are illustrative and subject to validation - Enhance implementation doc header to clarify it's an ADR companion, not a problem exploration Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2fe5274 to
73604fd
Compare
|
fullsend review is working on this — view logs |
This implementation document is a companion to ADR-0029, not a problem exploration. Moving it to docs/plans/ better reflects its purpose as implementation guidance. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
Site previewPreview: https://c5654e2a-site.fullsend-ai.workers.dev Commit: |
**Medium:** - Add docs/plans/ section to README for proper categorization - Update stale ADR-0028 reference in implementation doc (was "pending in PR fullsend-ai#601") **Low:** - Update ADR context to reflect GitLab support is decided (ADR-0028), not "under development" - Update all references from "PR fullsend-ai#601" to ADR-0028 throughout **Other:** - Remove agent-execution-environment from ADR frontmatter relates_to (now in plans, not problems) - Fix agent-infrastructure.md link path in implementation doc references Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
**Low:** - Complete README docs/plans/ index with all three existing plan files - Update GitLab runner registration to use modern authentication tokens (glrt-) instead of deprecated registration tokens, with note about GitLab 15.10+ requirement Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
**Medium:** - Update Kubernetes Helm install to use modern runnerToken instead of deprecated runnerRegistrationToken - Fix PodSecurityPolicy deprecation timeline (deprecated in 1.21, removed in 1.25, not 1.29) **Low:** - Move Fedora/Podman note from image composition to Rootless OpenShell Support section for better flow Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
**Medium:** - Remove confusing docker login example from GitLab CI config - Clarify that base image pull is handled by runner, not by agents in sandbox - Agents do NOT have Docker daemon access (isolated by OpenShell) **Low:** - Remove parenthetical explanation from Layer 3 for consistency with other layers Iteration 7/7 complete. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
|
@ggallen can you change the ADR number please? We already have ADR 29 in flight for the token mint, and a number of other follow-up ADRs that reference it. |
Update agent execution sandbox ADR number from 0029 to 0036 to avoid conflicts with ADRs merged to main. Update all references in agent-execution-environment.md. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
ggallen
changed the title
|
fullsend review is working on this — view logs |
Just updated to 0036, which I think is the first free number. |
- Mention Fedora/RHEL as base image alternatives for Podman deployments - Add explicit note about BYOA image customization in Decision section - Clarify GitLab CI script: field usage vs GitHub Actions - OpenShell K8s/Docker parity already addressed in Option 3 disadvantages Addresses review comments from maruiz93 and ifireball. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
ggallen
left a comment
ggallen
left a comment
There was a problem hiding this comment.
Addressed all review feedback:
Re: Fedora mention (line 81): Added Fedora/RHEL as base image alternatives for Podman deployments in both Options and Decision sections.
Re: BYOA and language runtimes (line 42): Added explicit note in Decision section clarifying that organizations implementing custom agents can build customized images with different runtime sets.
Re: OpenShell features on Kubernetes (line 112): This concern was already addressed in the disadvantages list - line 146 notes that OpenShell feature parity between Kubernetes pod networking and Docker needs validation.
Re: GitLab script field (line 61): Added inline comment clarifying that GitLab CI uses the script: field for commands to run inside the container, while GitHub Actions uses the uses: action syntax.
|
/review |
|
fullsend review is working on this — view logs |
- Fix broken link in agent-execution-environment.md: ADR-0029 → ADR-0036 - Add ADR-0030 reference to ADR-0036 References section Addresses High and Medium severity findings from fullsend-ai-review. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
fullsend review is working on this — view logs |
3 participants
This ADR addresses the agent execution environment question deferred in the GitLab support design (ADR-0028).
Summary
Proposes a shared container image (
ghcr.io/fullsend-ai/agent-sandbox) for agent execution that works on both GitHub Actions and GitLab CI. The image contains OpenShell, the fullsend agent harness, and a curated set of tools.Key Decisions
Contents
docs/ADRs/0036-agent-execution-sandbox.md) - Architectural decision covering context, options (shared image vs platform-specific vs Kubernetes CRDs vs minimal sandbox), decision rationale, and consequencesdocs/plans/agent-execution-environment.md) - Detailed implementation guidance including container image build pipeline, OpenShell configuration, resource limits, GitLab runner setup, image signing, and upgrade proceduresRelationship to Existing ADRs
Open Questions
Status: Proposed (design exploration, seeking feedback)