# Sandcastle — Orchestrate Sandboxed Coding Agents in TypeScript

> A TypeScript library for running coding agents in isolated sandboxes with a simple sandcastle.run() API, handling environment setup, execution, and cleanup automatically.

## Install

Save in your project root:

# Sandcastle — Orchestrate Sandboxed Coding Agents in TypeScript

## Quick Use
```bash
npm install sandcastle

# In your TypeScript project
import { sandcastle } from 'sandcastle';

const result = await sandcastle.run({
  task: "Write a function that sorts an array using quicksort",
  language: "typescript",
  timeout: 30000,
});

console.log(result.code);
console.log(result.tests);
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-e84b35b7
Author: AI Open Source