Sandstorm Documentation

Every request follows a specific lifecycle:

1. Sandbox Creation: Sandstorm creates a fresh sandbox using the configured runtime (E2B by default).
2. Upload: Your configuration, prompt, and any specified files are uploaded to the sandbox.
3. Execution: The Claude Agent SDK runs inside the sandbox using the configured tools.
4. Streaming: Sandstorm streams events back to the user via CLI, API, or Slack.
5. Cleanup: The sandbox is destroyed once the task is finished.

You can define specialist sub-agents in the agents object. The main agent can delegate work to these specialists using the Task tool.

Important: Sub-agents are for internal delegation. For external tool integrations, use mcp_servers instead.

{
  "agents": {
    "scraper": {
      "description": "Crawls websites and saves structured data to disk.",
      "prompt": "Scrape the target, extract the useful data, and save it to /home/user/output/.",
      "tools": ["Bash", "WebFetch", "Write", "Read"],
      "model": "sonnet"
    }
  }
}

The Security Auditor uses a multi-agent architecture where a main agent (team lead) coordinates specialized sub-agents to cover different attack surfaces. The main agent uses the Task tool to spawn these sub-agents, collects their findings, deduplicates them, and synthesizes the final report.

Agent Hierarchy:

• Main Agent (team lead, sonnet): Coordinates sub-agents and synthesizes findings.
• dependency-scanner (sonnet): Performs pip audit, npm audit, and CVE checks.
• code-scanner (sonnet): Performs OWASP Top 10 static analysis.
• config-scanner (haiku): Performs configuration reviews.

Since Sandstorm's core query execution is stateless, you can scale horizontally by running multiple Sandstorm instances behind a load balancer.

Scaling Considerations:

• Compute Bottleneck: When using the default E2B runtime, the primary bottleneck is your E2B plan limits (concurrent sandbox limits), not the Sandstorm server itself.
• Server Resources: A single 2-core machine can typically handle dozens of concurrent agents as the server mainly manages open SSE connections and streams stdout.

Many community projects (like claude-code-slack-bot) run Claude Code on a local machine or a single dedicated daemon. Sandstorm is designed for production team environments.

Key differences:

• Isolation: Sandstorm runs a fresh sandbox (e.g., E2B) per thread, whereas local bots run on the host machine's environment.
• Security: Sandstorm limits the 'blast radius' of bad prompts by using sandboxes that can be torn down or paused.
• Concurrency: Sandstorm supports multi-user concurrency via a per-thread sandbox pool, while local bots are typically serialized through a single process.
• Deployment: Sandstorm is built for production deployment (Docker, Railway, etc.), whereas local bots require a machine to stay online.

Decide between Anthropic Managed Agents (MA) and Sandstorm based on your orchestration and infrastructure requirements.

Choose Managed Agents if:

• You want a Claude-only, Anthropic-hosted, zero-infrastructure experience.
• You do not require multi-provider routing.
• You are comfortable with per-session-hour billing.
• You prefer to build and maintain your own scheduler and Slack bot.

Choose Sandstorm if:

• You need self-hosted, multi-provider (OpenRouter, Vertex, Bedrock, etc.), or data-residency control.
• You want a production-ready Slack bot (mentions, DMs, slash commands) out of the box.
• You need sub-hourly scheduling (Sandstorm supports minute-level * * * * * cron, whereas Claude Code Routines is limited to 1-hour minimums).
• You want full ownership of your observability (e.g., OpenTelemetry).

Custom MCP servers run inside your configured sandbox runtime. A malicious or buggy package has the same access to the sandbox as the agent, including:

• Filesystem access
• Network access (subject to runtime policies)
• Any environment variables passed via --env

Best Practices:

1. Prefer well-known first-party MCPs (e.g., HubSpot, Notion, Linear).
2. For community packages, audit the source code before adding them.
3. Use allowed_tools to scope the agent's capabilities, limiting it to only the specific tools required rather than the full MCP surface.

Memories are organized into three hierarchical scopes. The agent sees all three concatenated in the system prompt, starting with the most general scope first:

1. team: Shared across everyone in the Slack tenant (the workspace, or enterprise for Grid installs).
2. channel: Shared across users in a specific Slack channel.
3. user: Personal to one user in one tenant (the default scope since v0.9.0).

Isolation: Memories are keyed on (team_id, user_id). There is no cross-workspace sharing. A user in Workspace A cannot access memories from Workspace B. For CLI/HTTP runs without Slack context, both keys default to __local__.

Sandstorm and Vercel's Slack Agent Skill represent different architectural approaches to Slack-based agents.

Use Sandstorm if you need:

• Python Stack: Built with FastAPI.
• Infrastructure Independence: Deploy anywhere that runs Python, not just Vercel.
• Built-in Replay: Use ds replay <run_id> to replay and archive runs.
• First-class Memory: Managed memory using JSONL per (team_id, user_id).
• Open Observability: OTel support for any backend.

Use Vercel Slack Agent Skill if: You are already in the Vercel ecosystem, your team uses TypeScript, and you want managed durable execution via Workflow DevKit.

The Content Brief Generator uses specific configuration settings to produce structured, research-backed outputs. Key features include:

• output_format: Uses a JSON schema containing title options, keywords, an outline, and competitor gaps.
• max_turns: Set to 15 to allow the agent sufficient steps to perform web research, analyze competitors, and synthesize findings.
• system_prompt: Employs a 'Content strategist' persona to research ranking content and identify gaps.
• WebSearch: Enabled by default to research existing content, keywords, and competitor angles.
• model: Typically uses sonnet for a balance of research quality and speed.