Sandcastle — Orchestrate Sandboxed Coding Agents in TypeScript

Introduction

Sandcastle provides a clean TypeScript API for spawning coding agents in isolated sandboxes. Each sandcastle.run() call creates a fresh environment, executes the agent task, and returns structured output. It handles the complexity of containerization, filesystem isolation, and resource limits so developers can focus on orchestration logic.

What Sandcastle Does

• Runs coding agents in isolated containers with a single function call
• Manages environment provisioning, execution, and teardown automatically
• Provides structured output including generated code, test results, and logs
• Supports parallel execution of multiple sandboxed agents
• Enforces resource limits (CPU, memory, network, time) per sandbox

Architecture Overview

Sandcastle uses a TypeScript orchestrator that communicates with a local container runtime (Docker or compatible). Each sandcastle.run() call provisions a minimal container with the requested language toolchain, mounts the task context, invokes the agent, and streams output. The orchestrator manages a pool of warm containers for fast startup. Results are returned as typed TypeScript objects with code, stdout, stderr, and exit status.

Self-Hosting & Configuration

• Requires Node.js 18+ and Docker installed locally
• Configure default resource limits in sandcastle.config.ts
• Pre-built container images available for Python, TypeScript, Go, and Rust
• Custom images can be specified per task for specialized toolchains
• No cloud services required; everything runs on your machine

Key Features

• One-function API: sandcastle.run() handles the entire lifecycle
• Type-safe TypeScript SDK with full IntelliSense support
• Warm container pool for sub-second sandbox startup
• Parallel execution with configurable concurrency limits
• Built-in timeout and resource enforcement per sandbox

Comparison with Similar Tools

• E2B — cloud-hosted sandboxes with per-minute billing; Sandcastle is local and free
• microsandbox — microVM-based; Sandcastle uses containers for faster startup
• Docker SDK — low-level container API; Sandcastle provides agent-specific abstractions
• Daytona — full dev environments; Sandcastle is lightweight, single-task focused

FAQ

Q: How fast is sandbox startup? A: With warm containers, startup is under 500ms. Cold starts take 2-3 seconds depending on the base image size.

Q: Can agents access the network? A: Network access is disabled by default. You can opt in per task with network: true in the run configuration.

Q: What happens if an agent hangs? A: Each sandbox has a configurable timeout (default 60 seconds). Exceeding it terminates the container and returns a timeout error.

Q: Can I run multiple agents in parallel? A: Yes, Sandcastle supports concurrent execution. Set concurrency in the config to control how many sandboxes run simultaneously.

Sources

• https://github.com/mattpocock/sandcastle