docs: ADR 30 — OpenShell sandbox interaction model

[maruiz93]

Summary

• Records how fullsend run interacts with OpenShell sandboxes: gateway lifecycle, sandbox create/bootstrap/execute/extract/delete sequence, and the primitives used for each concern
• Documents alternatives considered for environment configuration (gRPC API vs files via SCP), file/binary delivery (SCP vs images vs --upload), command execution (SSH vs native exec/upload/download), credential delivery (providers vs host files vs scoped tokens vs REST server), and gateway lifecycle (reuse vs per-run)
• Links to ADRs 0024 (harness definitions) and 0025 (credential tiers) rather than restating them, and notes that the SSH/SCP/rsync choice may be revisited per Replace exec.Command SSH/SCP wrappers with Go-native libraries #261

Test plan

• make lint passes (ADR statuses, numbers, frontmatter all green)
• Review ADR content for accuracy against current internal/sandbox/sandbox.go and internal/cli/run.go

🤖 Generated with Claude Code

[maruiz93]

/review

[github-actions]

Site preview

Preview: https://9121c6de-site.fullsend-ai.workers.dev

Commit: 3036d620dabdc4227a9949a3c93f32ce9f1302ff

[fullsend-ai-review]

Review: #715

Head SHA: 3036d62
Timestamp: 2026-05-07T00:00:00Z
Outcome: approve

Summary

This PR adds ADR 0030, documenting the OpenShell sandbox interaction model used by fullsend run. The ADR is well-structured, accurately reflects the current implementation, and follows established ADR conventions. All technical claims were verified against the codebase — EnsureGateway, SSHStreamReader, bare-key credential form, --no-links/--exclude .git/hooks/ rsync safety flags, .env.d sourcing, --no-auto-providers, and runner_env scoping all match the code in internal/sandbox/sandbox.go and internal/cli/run.go. The decision rationale is clear, alternatives are presented with trade-offs, and cross-references to ADRs 0024 and 0025 are appropriate. No security, correctness, or injection concerns.

Findings

Info

• [style/conventions] docs/ADRs/0030-openshell-sandbox-interaction-model.md — ADR 0029 does not yet exist on main (PR Add agent execution sandbox architecture ADR #659 is open with it). This ADR's number 0030 is correct assuming 0029 merges first. If 0029 is abandoned or renumbered, this may need adjustment. The renumber-adr skill can handle this before merge.

Footer

Outcome: approve
This review applies to SHA 3036d620dabdc4227a9949a3c93f32ce9f1302ff. Any push to the PR head clears this review and requires a new evaluation.

[ralphbean]

Thank you for documenting this!