沙堡

Install and start PostgreSQL (macOS example)

brew install postgresql@16 brew services start postgresql@16

Install and start Redis (macOS example)

brew install redis brew services start redis

Production Mode - Docker (recommended)

One command. PostgreSQL, Redis, API server, and background worker - all configured.

```bash git clone https://github.com/gizmax/Sandcastle.git cd Sandcastle

Describe a workflow in plain language (build/new are aliases of `generate`)

sandcastle build "enrich inbound leads and post a summary to Slack"

Interactive setup wizard (API keys, .env, workflows/)

sandcastle init

Generate a workflow (the classic form; `build` / `new` are friendly aliases)

sandcastle generate -d "enrich inbound leads" -o workflows/leads.yaml

Community Hub - browse and install templates

sandcastle hub search "lead scoring" sandcastle hub install competitive-radar sandcastle hub collections sandcastle hub install-collection marketing-pro

On the Spark: serve a local model (example: Ollama), then point Sandcastle at it

OLLAMA_HOST=http://localhost:11434 sandcastle serve # Spark Mode auto-detects and engages

Override detection anytime with `SANDCASTLE_SPARK_MODE=on|off`. On any non-Spark machine nothing
changes — detection is fail-closed.

**Spark Mode in Docker.** The plain `docker-compose.yml` does not pass the GPU through, so Spark
Mode stays off in containers. With nvidia-container-toolkit installed on the Spark host, run:

Overnight Self-Tune goes one step further: with pip install 'sandcastle-ai[training]', TRAINER_BACKEND=gpu, and EVOLUTION_AUTO_FINETUNE=true, the evolution loop fine-tunes a real LoRA adapter (transformers + peft) on the workflow's own eval data and routes the workflow to it — served by your local vLLM/Ollama/NIM at $0/run. See docs/overnight-self-tune-spark.md.

Spark Mode auto-configures Sandcastle for NVIDIA DGX Spark and local NVIDIA GPU inference. It is not an official NVIDIA certification or endorsement. "NVIDIA", "DGX", and "DGX Spark" are trademarks of NVIDIA Corporation, used here only to describe compatibility.

---

Quickstart

Example: lead-enrichment.yaml

name: "Lead Enrichment"
description: "Scrape, enrich, and score leads for sales outreach."
default_model: sonnet
default_max_turns: 10
default_timeout: 300

steps:
  - id: "scrape"
    prompt: |
      Visit {input.target_url} and extract:
      company name, employee count, main product, contact info.
      Return as structured JSON.
    output_schema:
      type: object
      properties:
        company_name: { type: string }
        employees: { type: integer }
        product: { type: string }
        contact_email: { type: string }

  - id: "enrich"
    depends_on: ["scrape"]
    prompt: |
      Given this company data: {steps.scrape.output}
      Research: revenue, industry, key decision makers, recent news.
    retry:
      max_attempts: 3
      backoff: exponential
      on_failure: abort

  - id: "score"
    depends_on: ["enrich"]
    prompt: |
      Score this lead 1-100 for B2B SaaS potential.
      Based on: {steps.enrich.output}
    model: haiku

on_complete:
  storage_path: "leads/{run_id}/result.json"

Templates (Quickstart)

15 built-in agent templates across 6 categories:

Advanced features: output_format (json/files/markdown), shared_files between agents, fallback_template on failure.

```yaml

Add to .env

echo 'DATABASE_URL=postgresql+asyncpg://localhost/sandcastle' >> .env

Add to .env

echo 'REDIS_URL=redis://localhost:6379' >> .env

Add to .env

echo 'STORAGE_BACKEND=s3' >> .env echo 'STORAGE_BUCKET=sandcastle-artifacts' >> .env echo 'AWS_ACCESS_KEY_ID=...' >> .env echo 'AWS_SECRET_ACCESS_KEY=...' >> .env

Set DATABASE_URL and REDIS_URL in .env

Set in .env or via sandcastle init

SANDBOX_BACKEND=e2b # default SANDBOX_BACKEND=docker # requires Docker + pip install sandcastle-ai[docker] SANDBOX_BACKEND=local # dev only, no isolation SANDBOX_BACKEND=cloudflare # requires deployed CF Worker ```

All backends share the same SandboxBackend protocol - same YAML, same API, same dashboard. Switch backends without changing workflows.

Docker hardening: When using the Docker backend, containers run with all capabilities dropped, a seccomp profile restricting syscalls, PID limits (default 100), CPU quotas (default 50%), memory limits (default 512 MiB), and an unprivileged user (1000:1000). All configurable via environment variables.

Security-relevant settings:

---

A) Template - one line to configure

steps: - id: deep-research type: managed-agent managed_agent_config: agent_template: researcher message: "Research {input.topic} and provide a comprehensive report with citations"

Per-workflow configuration

privacy: enabled: true mode: redact # "redact" | "audit_only" entities: # optional: restrict to known entity types - email - credit_card - ssn - ip_address - iban - date_of_birth apply_to: # optional: defaults to outputs,webhooks - outputs - webhooks replacement_template: "[{entity_type}]"

Per-server configuration (env vars)

PRIVACY_ENABLED=true PRIVACY_ENTITIES=email,phone,ssn,credit_card,ip_address,iban,date_of_birth PRIVACY_APPLY_TO=outputs,webhooks ```

The Privacy Router integrates with the audit trail - every redaction event is logged with run ID, step ID, and matched pattern type (not the matched value).

---

Enable EU AI Act enforcement in .env

COMPLIANCE_MODE=eu_ai_act

Check active compliance features:

.env

COMPLIANCE_MODE=black_box # enable the flight recorder DATA_RESIDENCY=local # required: the audit trail never leaves your infra SANDCASTLE_AUDIT_KEY=<secret> # signs every chain head

With `COMPLIANCE_MODE=black_box`, Sandcastle enforces at runtime:

- **Every run is recorded** - a signed cassette is written for each run, automatically
- **Every chain head is signed** - runs refuse to start without an audit key
- **Local data residency** - runs refuse to start unless `DATA_RESIDENCY=local`
- **Attested run API** - `GET /api/runs/{id}` returns `signed: true` plus the chain head hash

Verify any run or cassette file offline:

Restart API + start a worker in a second terminal

sandcastle serve sandcastle worker

With Redis, workflows run in background workers instead of in-process. You can run multiple workers for parallel execution.

**Step 3 - S3 / MinIO** (artifact storage)

For MinIO, also set: STORAGE_ENDPOINT=http://localhost:9000

Add your API keys

cat > .env << 'EOF' ANTHROPIC_API_KEY=sk-ant-... E2B_API_KEY=e2b_... SANDBOX_BACKEND=e2b WEBHOOK_SECRET=your-signing-secret EOF

docker compose up -d

That's it. Sandcastle is running at `http://localhost:8080` with PostgreSQL 16, Redis 7, auto-migrations, and an arq background worker.

Start the API server (serves API + dashboard on one port)

uv run python -m sandcastle serve

Python SDK

Install from PyPI and use Sandcastle programmatically from any Python app:

pip install sandcastle-ai

```python from sandcastle import SandcastleClient

client = SandcastleClient(base_url="http://localhost:8080", api_key="sc_...")

Start the server (API + dashboard on one port)

sandcastle serve

Streaming CLI (sandcastle run --stream)

The sandcastle run --stream flag enables live terminal output with color-coded status: green for completed steps, yellow for running, red for failed. Each step shows timing, cost, and responsibility. Pressing Ctrl+C detaches from the stream and lets the workflow continue in background. Three additional commands ship in this release: sandcastle describe, sandcastle lint, and sandcastle owners.

---

Cost Estimation API

Estimate the cost of a workflow before running it. The /runs/estimate endpoint parses the workflow YAML, resolves model assignments per step (including classify/gate overrides), and returns a per-step and total cost breakdown based on average token usage.

curl -X POST http://localhost:8080/api/runs/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "lead-enrichment",
    "input": { "target_url": "https://example.com" }
  }'

{
  "data": {
    "valid": true,
    "validation_errors": [],
    "estimated_cost_usd": 0.18,
    "steps": [
      { "id": "scrape",  "model": "sonnet", "estimated_cost_usd": 0.06 },
      { "id": "enrich",  "model": "sonnet", "estimated_cost_usd": 0.09 },
      { "id": "score",   "model": "haiku",  "estimated_cost_usd": 0.03 }
    ]
  }
}

The valid field indicates whether the workflow passes validation. Invalid workflows still return an estimate but include a disclaimer that the figure may be unreliable. Falls back to sonnet pricing for unknown models.

---

Audit Endpoints

```bash

🕸️ Sandcastle Mesh — one workflow, your whole fleet

Your machines have different superpowers. Sandcastle Mesh turns them into one orchestration mesh: a DGX Spark runs the GPU steps, a Mac mini runs the browser steps, and any spare box runs the code steps — all inside a single workflow.

┌─────────────┐      requires: [gpu]      ┌─────────────┐
│ Coordinator │ ────────────────────────▶ │  DGX Spark  │  gpu · spark · code
│  (any box)  │      requires: [browser]  ├─────────────┤
│   runs the  │ ────────────────────────▶ │  Mac mini   │  browser · code
│   workflow  │      (no requires)        ├─────────────┤
│             │ ──── runs locally ──────  │  any server │  docker · code
└─────────────┘                           └─────────────┘

Joining a machine is one command — it registers itself, auto-detects its capabilities (DGX Spark → gpu+spark, Playwright → browser, Docker socket → docker, always code) and heartbeats every 15 seconds:

```bash

Your First Workflow

```bash

Run a workflow asynchronously

curl -X POST http://localhost:8080/api/workflows/run \ -H "Content-Type: application/json" \ -d '{ "workflow": "lead-enrichment", "input": { "target_url": "https://example.com", "max_depth": 3 }, "callback_url": "https://your-app.com/api/done" }'

Run a workflow and wait for completion

run = client.run("lead-enrichment", input={"target_url": "https://example.com"}, wait=True, ) print(run.status) # "completed" print(run.total_cost_usd) # 0.12 print(run.outputs) # {"lead_score": 87, "tier": "A", ...}

Stream live events from a running workflow

for event in client.stream(run.run_id): print(event)

Run a workflow

sandcastle run lead-enrichment -i target_url=https://example.com

List runs, workflows, schedules

sandcastle ls runs --status completed --limit 10 sandcastle ls workflows sandcastle ls schedules

Cancel a running workflow

sandcastle cancel <run-id>

MCP Integration

Sandcastle ships with a built-in MCP (Model Context Protocol) server. This lets Claude Desktop, Cursor, Windsurf, and any MCP-compatible client interact with Sandcastle directly from the chat interface - run workflows, check status, manage schedules, browse results.

Install the MCP extra:

pip install sandcastle-ai[mcp]

Available MCP Tools

Available MCP Resources

Client Configuration

Claude Desktop - add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sandcastle": {
      "command": "sandcastle",
      "args": ["mcp"],
      "env": {
        "SANDCASTLE_URL": "http://localhost:8080",
        "SANDCASTLE_API_KEY": "sc_..."
      }
    }
  }
}

Cursor - add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sandcastle": {
      "command": "sandcastle",
      "args": ["mcp", "--url", "http://localhost:8080"]
    }
  }
}

Windsurf - add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sandcastle": {
      "command": "sandcastle",
      "args": ["mcp"]
    }
  }
}

The MCP server uses stdio transport (spawned as a child process by the client). It requires a running sandcastle serve instance to connect to. Connection is configured via --url / --api-key CLI args or SANDCASTLE_URL / SANDCASTLE_API_KEY env vars.

What You Can Do from Chat

Once connected, ask your AI assistant to:

• "Run the lead-enrichment workflow for https://example.com"
• "What's the status of my last run?"
• "List all failed runs from today"
• "Create a schedule to run data-sync every day at 9am"
• "Cancel run abc-123"
• "Save this workflow YAML to the server"
• "Show me all available workflows"
• "Check if Sandcastle is healthy"

---

64 Built-in Integrations

<p align="center"> <img src="docs/screenshots/integrations.png" alt="Integrations" width="720" /> </p>

Sandcastle ships with 64 zero-config tool connectors across 11 categories. Each integration is a lightweight JavaScript module that agents can call during workflow execution. Named connections let you wire multiple accounts (e.g. "production-slack" vs "staging-slack"), and all credentials are encrypted at rest with Fernet (AES-128-CBC + HMAC-SHA256).

steps:
  - id: "notify"
    type: notify
    service: slack
    connection: production-slack
    template: "Lead {steps.score.output.company} scored {steps.score.output.score}/100"

---

Workflow Engine

Define multi-step agent pipelines as YAML. Each step can run in parallel, depend on previous steps, pass data forward, and use different models.

Self-Describing Workflows

Every step can declare responsibility, source_hint, owner, and added_date metadata so your workflows stay understandable as they grow. Three new CLI commands support this: sandcastle describe prints a human-readable summary of any workflow, sandcastle lint flags missing metadata and structural issues, and sandcastle owners lists who owns each step. The audit trail and dashboard are enriched with this metadata automatically.

Self-Optimizing Workflows (AutoPilot)

A/B test different models, prompts, and configurations for any step. Sandcastle automatically runs variants, evaluates quality (via LLM judge or schema completeness), tracks cost and latency, and picks the best-performing variant. Supports quality, cost, latency, and pareto optimization targets.

steps:
  - id: "enrich"
    prompt: "Enrich this lead: {input.company}"
    autopilot:
      enabled: true
      optimize_for: quality
      min_samples: 20
      auto_deploy: true
      variants:
        - id: fast
          model: haiku
        - id: quality
          model: opus
          prompt: "Thoroughly research and enrich: {input.company}"
      evaluation:
        method: llm_judge
        criteria: "Rate completeness, accuracy, and depth 1-10"

---

Self-Healing Workflows

When a step lands in the dead letter queue, Sandcastle can fix the workflow itself. The healer scans unresolved failures, gathers the workflow YAML, the failing step, the error, and the last successful run, then asks the advisor LLM for a minimal patch with a diagnosis and a confidence score. Every patch is validated through the DAG parser and filed as a new draft workflow version behind an approval request - a human reviews the diagnosis and diff, approves, and the patched version ships on the next pass.

Once a healed workflow completes its next run, the originating dead-letter item is resolved automatically (resolved_by="healer"). If the patch regresses, the item stays open and the healer tries again, up to healer_max_attempts times.

```bash

Review recent heal attempts (diagnosis, status, workflow, version)

curl http://localhost:8080/api/healer/activity ```

Human-in-the-loop by default: with healer_auto_apply=false, every patch waits for explicit approval before it goes live.

---

Hierarchical Workflows (Workflow-as-Step)

Call one workflow from another. Parent workflows can pass data to children via input mapping, collect results via output mapping, and fan out over lists with configurable concurrency. Depth limiting prevents runaway recursion.

steps:
  - id: "find-leads"
    prompt: "Find 10 leads in {input.industry}"

  - id: "enrich-each"
    type: sub_workflow
    depends_on: ["find-leads"]
    sub_workflow:
      workflow: lead-enrichment
      input_mapping:
        company: steps.find-leads.output.company
      output_mapping:
        result: enriched_data
      max_concurrent: 5
      timeout: 600

  - id: "summarize"
    depends_on: ["enrich-each"]
    prompt: "Summarize enrichment results: {steps.enrich-each.output}"

---