沙堡

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

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

sandcastle init

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

Install a community template

sandcastle hub install competitive-radar

Install a whole collection

sandcastle hub collections sandcastle hub install-collection marketing-pro

Docker Sandbox Hardening

When using the Docker backend, every container runs with: - All capabilities dropped (CapDrop: ALL) - Seccomp profile restricting dangerous syscalls - PID limit (default 100, configurable) - CPU quota (default 50%, configurable) - Memory limit (default 512 MiB, configurable) - Unprivileged user (1000:1000) - Auto-remove on exit

---

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 'S3_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.

---

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: mode: redact # "redact" | "audit_only" patterns: # optional: restrict to specific patterns - email - credit_card - ssn exclude_steps: # optional: skip privacy check on these steps - internal-analysis

Per-server configuration (env vars)

PRIVACY_MODE=redact PRIVACY_PATTERNS=email,phone,ssn,credit_card,ip,iban,dob ```

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:

Configured via environment variables

MEMORY_BACKEND=local # "local" (SQLite + embeddings) or "cloud" (Mem0) MEMORY_GRAPH_ENABLED=false # Enable Neo4j graph backend MEMORY_MAX_AGE_DAYS=90 # TTL for memory decay (0 = keep forever) MEMORY_ADMIT_THRESHOLD=0.3 # Minimum quality score for admission ```

---

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: S3_ENDPOINT_URL=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

API Key Rotation

Rotate API keys with zero downtime. The old key remains valid during a configurable grace period (default 24 hours), giving clients time to switch over.

```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"

---

62 Built-in Integrations

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

Sandcastle ships with 62 zero-config tool connectors across 9 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"

---

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}"

---

Workflow Version Diff

Every workflow edit is versioned. Compare any two versions side-by-side with YAML diff highlighting. See exactly what changed, when, and roll back if needed.