Skip to content
Effloow
← Back to article
EFFLOOW LAB LAB-RUN

Sandcastle Typescript Agent Docker Sandbox Poc 2026

Evidence notes document the bounded local or source-based checks behind an Effloow article. They are not product endorsements, legal advice, or benchmark claims.

Date: 2026-06-04 Environment: macOS 15 arm64, Node.js v25.x, npm Track: sandbox-poc

What Was Inspected

@ai-hero/sandcastle was inspected via npm info @ai-hero/sandcastle --json on 2026-06-04.

Package Metadata Verified

  • Package name: @ai-hero/sandcastle
  • Version: 0.7.0
  • License: MIT
  • Published: 2026-05-30 21:17 UTC (4 days before this lab run)
  • Maintainer: mpocock (GitHub Actions OIDC publish)
  • Repository: git+https://github.com/mattpocock/sandcastle.git
  • Unpackaged size: 14.6 MB
  • Keywords: cli, sandbox, docker, ai, agent
  • bin: sandcastle → dist/main.js

Dependency Surface Verified

  • Direct dependencies: @clack/prompts: ^1.1.0 (1 dep only)
  • Peer dependencies:
    • @daytona/sdk: ^0.164.0
    • @vercel/sandbox: >=1.0.0

Exports Map Verified (via npm view JSON)

5 sandbox providers confirmed from the package exports:

  1. . (root — sandcastle.run() main API)
  2. ./sandboxes/docker
  3. ./sandboxes/vercel
  4. ./sandboxes/podman
  5. ./sandboxes/daytona
  6. ./sandboxes/no-sandbox

API Surface Verified (via GitHub README + EveryDev.ai documentation)

The following configuration options were confirmed from official documentation:

  • sandcastle.run({ prompt, provider, branchStrategy }) — main entry point
  • sandcastle.createSandbox(provider) — low-level sandbox lifecycle
  • sandcastle.interactive(provider) — interactive agent session

Branch strategies (3 confirmed):

  • head — agent writes directly to the host worktree
  • merge-to-head — creates a temporary branch, merges back on completion
  • branch — commits land on an explicitly named branch

Lifecycle hooks (confirmed from docs):

  • onWorktreeReady — runs after git worktree is set up
  • onSandboxReady — runs after Docker/Podman container boots

Runtime options (confirmed):

  • maxIterations — cap on agent iteration count
  • completionSignal — string or regex pattern signaling task done
  • idleTimeoutSeconds — time before idle agent is terminated
  • promptArgs — placeholder substitution in prompt files

Sandbox groups (confirmed from recent release notes):

  • groups option on Docker/Podman providers, maps to --group-add flags

CLI commands (confirmed):

  • sandcastle init — scaffolds .sandcastle/ config directory and Dockerfile
  • sandcastle docker build-image / sandcastle podman build-image — rebuild sandbox images

Workflow templates (5 confirmed from init command docs):

  1. blank
  2. simple-loop
  3. sequential-reviewer
  4. parallel-planner
  5. parallel-planner-with-review

What Was NOT Tested

  • No Docker container was started
  • No Podman container was started
  • No actual coding task was run through sandcastle.run()
  • No agent (Claude, Codex, Pi) was invoked
  • No git worktree merge was observed
  • No Daytona or Vercel sandbox was connected
  • npm install completed with audit warnings (unresolved vulnerabilities in peer deps) — package was not fully installed in this environment

Sources

  • npm registry: npm info @ai-hero/sandcastle --json (verified 2026-06-04)
  • GitHub README: github.com/mattpocock/sandcastle/blob/main/README.md
  • EveryDev.ai tool profile: everydev.ai/tools/sandcastle
  • Codeline.co review: codeline.co/thoughts/repo-review/2026/sandcastle-orchestrate-ai-coding-agents-in-isolated-sandboxes
  • SourcePulse: sourcepulse.org/projects/27307520
  • GitHub issue #233 (OpenCode agent provider PRD): github.com/mattpocock/sandcastle/issues/233
  • GitHub issue #583 (thinking option for pi provider): github.com/mattpocock/sandcastle/issues/583

Read the article

This note supports the public article and records what was actually checked.

Open article →