Core Analysis¶

Project Positioning: Sandcastle addresses how to run LLM/AI coding agents in controlled, repeatable isolated environments and map their file modifications back into a Git repository in an auditable way. Rather than letting agents edit the main branch directly, it captures changes as commits on a separate worktree/branch for review and rollback.

Technical Features¶

• Sandbox + worktree separation: By creating an independent Git worktree and running the agent inside a sandbox, all file changes are confined to that worktree and do not mutate the host working tree directly.
• Branch strategy (branchStrategy): Agent changes are recorded as branches and commits with configurable naming/merge behavior to control how changes propagate back to the repository.
• Lifecycle hooks: Hooks such as onWorktreeReady and onSandboxReady allow dependency installation, tests, and verification to run before changes are accepted.
• Result includes iterations & commits: The run result exposes each iteration and the produced commits, enabling audit trails.

Usage Recommendations¶

1. Default flow: Run agents via run() to create separate branches and require human/CI review before merging rather than automatic merges to main.
2. Use hooks for safety gates: Run linters, unit tests, or quick static analysis in onSandboxReady and gate merges on their success.
3. Limit iterations and timeouts: Configure maxIterations and timeouts to avoid long-running or low-quality change loops.

Caveats¶

• When using bind-mount providers you must manage host file permissions and exposure risks; for sensitive repos, prefer isolated microVM providers.
• Sandcastle makes agent output auditable but does not replace proper tests and code review—do not auto-merge without checks.

Important Notice: The safety guarantees depend on the chosen sandbox provider and hook configurations. Sandcastle converts uncontrolled file edits into auditable Git commits, but operational controls remain necessary.

Summary: Sandcastle’s primary value is transforming LLM-driven changes into independent Git branches and commits, making them compatible with existing review, CI, and rollback workflows.

Core Analysis¶

Core Issue: Integrate Sandcastle into CI/CD to automate agent-driven changes while preserving auditability and rollback capabilities.

Technical Analysis¶

• Git-native outputs: run() returns iterations and commits which are auditable artifacts the CI can record and assert against.
• Branch-based workflow: Have Sandcastle produce commits on separate branches, letting CI run full verification on those branches while keeping main clean.
• Hooks for preparation: Use onSandboxReady to pre-install dependencies or run quick checks inside the sandbox to reduce CI duplication.

Recommended Integration Strategy (stepwise)¶

1. Produce and push a branch: CI Job A runs Sandcastle run() and pushes the branch to remote as a PR source or artifact.
2. Parallel verification: CI Job B (triggered by the branch or artifact) runs full unit, integration, and security tests.
3. Review and merge policy: Merge only after all checks pass and either CI approvals or human reviewers accept the changes; avoid unreviewed auto-merges.
4. Persist audit data: Store iterations, commits, and agent logs as build metadata/artifacts for traceability and compliance.
5. Rollback path: Use standard Git revert/reset or produce a repair branch if issues are detected later.

Practical Tips¶

• Put fast non-invasive checks (lint, quick static analysis) in onSandboxReady, reserve expensive tests for CI verification.
• Use isolated providers in CI when running untrusted agents; use warmed images or caches to offset startup costs.
• Initially block automatic merges—introduce automation progressively as confidence builds.

Caveats¶

• Ensure CI has limited-but-sufficient permissions to push branches and write metadata; follow least-privilege principles.
• Preserve agent logs and diffs for post-mortem analysis.

Important Notice: Treat Sandcastle as a generator of auditable changes—not a CI replacement. Integrate it tightly with CI checks and review policies to ensure safe automation.

Summary: Generate branches with Sandcastle, run thorough CI on those branches, and require approval before merge—this pattern preserves auditability, rollback capability, and automation benefits.

Core Analysis¶

Project Positioning: The SandboxProvider abstraction is a key architectural element of Sandcastle. It elevates the choice of execution isolation into a pluggable strategy so the same orchestration logic (e.g., run()) can operate across different isolation levels.

Technical Characteristics and Trade-offs¶

• Abstraction benefits: A unified API (run(), createSandbox()) decouples orchestration from isolation implementations, making it easy to switch providers between local debugging and production.
• Bind-mount containers (Docker/Podman):
• Pros: Fast startup, easy local debugging, good resource utilization.
• Cons: Mounting host filesystem increases exposure risk; requires UID/GID and SELinux handling.
• Use cases: Local development, rapid iteration, non-sensitive repos.
• MicroVM / Isolated providers (Vercel Firecracker):
• Pros: Stronger isolation, reduced host compromise risk — suitable for untrusted agents or multi-tenant setups.
• Cons: Higher startup latency, resource/quota constraints, cloud dependency.
• Use cases: Production CI, security testing, running untrusted agents.
• No-sandbox mode: No isolation — only for trusted debugging, not recommended for risky automation.

Usage Recommendations¶

1. Adopt progressively: Debug locally with Docker/Podman; move to isolated providers for production or sensitive workflows.
2. Validation for bind-mounts: Align UID/GID, set SELinux labels, and use read-only mounts for caches to reduce exposure.
3. Assess resource/costs: When using microVMs, plan for startup latency and quotas; consider prebuilt images or cached dependencies.

Caveats¶

• The abstraction does not eliminate differences in security guarantees: choosing a provider still determines the real isolation boundary.
• Avoid bind-mounts and no-sandbox in multi-tenant or highly sensitive contexts.

Important Notice: SandboxProvider gives you strategy-level flexibility, but actual security depends on the chosen provider and runtime configuration.

Summary: The SandboxProvider abstraction offers portability and flexibility, enabling easy switching of isolation levels while requiring you to balance isolation, cost, and debugging convenience.

Core Analysis¶

Core Question: When agent output is recorded as Git commits, how do you ensure quality and prevent dangerous changes from being merged? Sandcastle does not automatically guarantee quality; it supplies engineering building blocks (isolation, hooks, iteration limits, logging) that you must wire into CI and review gates.

Technical Analysis¶

• Branch isolation: Agent changes are created on separate worktrees/branches, keeping main branch safe by default.
• Lifecycle hooks: onSandboxReady and onWorktreeReady allow you to install dependencies, run linters, unit tests, or security scans before accepting changes.
• Run control: maxIterations and timeout settings prevent infinite or runaway editing loops. The returned iterations and commits provide an audit trail.
• Logging/observability: Persisting agent output and file-level logs enables post-run analysis and rollback decisions.

Practical Recommendations¶

1. Make tests/security scans mandatory in hooks: Run quick unit tests, linters, and static security checks in onSandboxReady. Block merges on failures.
2. Avoid unconditional auto-merges: Require CI or human review to accept branches produced by agents to prevent low-quality code entering main.
3. Limit iterations and review each commit: Configure maxIterations and inspect each returned commit/diff for scope and intent.
4. Principle of least privilege: Use minimal-permission sandbox images and narrow-scoped API keys to reduce agent impact.

Caveats¶

• Sandcastle equips you with tools, not a turnkey quality system—automated gates and review policies must be implemented externally.
• With bind-mount providers, be mindful of host exposure; prefer isolated providers for sensitive repositories.

Important Notice: Storing agent changes as Git commits is only the first step—combine hooks, CI checks, and code review to make those commits trustworthy.

Summary: Sandcastle provides the mechanisms to implement quality gates, but ensuring safe, high-quality merges requires integrating these mechanisms into CI pipelines and review workflows.

Core Analysis¶

Core Issue: The main adoption friction for developers is environment and operational setup (TypeScript/Node, Git worktrees, container/VM permissions, LLM credentials), not the API itself. Sandcastle’s API is straightforward, but surrounding infra requires engineering know-how.

Learning Curve and Common Pitfalls¶

• Learning curve: Medium-high — familiarity with TypeScript, Git (worktrees/branches), containers or microVMs, and basic prompt engineering is needed.
• Common pitfalls:
• UID/GID mismatches causing file permission failures or preflight checks to fail;
• Bind-mount mode accidentally exposing host-sensitive data;
• Omitting lint/tests from hooks and thus producing unchecked commits;
• External LLM rate/cost limits and credential management complexities.

Concrete Best Practices¶

1. Start small locally: Use no-sandbox() or Docker for local debugging and small change experiments.
2. Prebuild and pin images: Bake dependencies and UID/GID alignment into images to reduce runtime variability.
3. Make tests/security scans hook-mandatory: Run fast lint/unit/security checks in onSandboxReady; block progress on failures.
4. Enforce branch strategy and block auto-merges: Require CI or human review before merging agent branches.
5. Mount caches read-only: Use read-only or cached mounts for things like ~/.npm to improve speed with less side effects.
6. Phase provider migration: Debug with bind-mount containers, move to microVMs for production or sensitive workflows.

Caveats¶

• Avoid no-sandbox() or default bind-mount settings for sensitive repositories.
• Ensure hook scripts are well-tested to avoid introducing side effects.

Important Notice: Run agents against small, controlled experiments first; stabilize images and hooks before promoting to CI/production.

Summary: By templating .sandcastle, prebuilding images, and placing validation into hooks, teams can safely onboard Sandcastle into development workflows within a short timeframe, albeit with initial operational effort.