Sandstorm

Open-source runtime for general-purpose AI agents in isolated sandboxes.

CLI, API, Python client, and Slack with streaming, file uploads, and config-driven behavior.

Built on the Claude Agent SDK and E2B.

Sandstorm is for people who want real agent work, not a chat wrapper:

• Research Acme's competitors, crawl their sites and recent news, and write a one-page branded briefing PDF with sources
• Analyze uploaded transcripts or PDFs
• Triage incoming support tickets
• Run a security audit in a fresh sandbox
• Turn docs into a draft API spec

Terminal demo

$ pip install duvo-sandstorm
$ ds init research-brief
$ cd research-brief
$ ds "Research Acme's competitors, crawl their sites and recent news, and write a one-page branded briefing PDF with sources."

WEBFETCH competitor sites, product pages, and recent coverage
STREAM compared launches, pricing, positioning, and buyer signals
WRITE briefing.pdf
WRITE reports/sources.md

artifacts:
  - briefing.pdf
  - reports/sources.md

The point is not that an agent can answer a question. It starts from a runnable starter, gets a fresh sandbox, can read uploads or crawl the web, writes artifacts like briefing.pdf, streams its work, and tears itself down when the run is done.

60-second path

pip install duvo-sandstorm
ds init
cd general-assistant
ds add linear
ds "Compare Notion, Coda, and Slite for async product teams"

ds init scaffolds a runnable starter with sandstorm.json, a starter README, .env.example, and any starter-specific assets. If provider settings are missing, the guided flow asks once and writes .env for you.

Direct forms:

ds init --list
ds init research-brief
ds init security-audit my-audit

Install extras

Install the base package for the CLI and server:

pip install duvo-sandstorm

Add extras only when you need them:

pip install "duvo-sandstorm[client]"      # Async Python client
pip install "duvo-sandstorm[slack]"       # Slack bot support
pip install "duvo-sandstorm[telemetry]"   # OpenTelemetry integration

Pick a starter

Starter	Use it when you want to	Typical output	Aliases
general-assistant	Start with one flexible agent for mixed workflows	concise answer, plan, or artifact	-
research-brief	Research a topic, compare options, and support a decision	brief with findings, recommendations, and sources	competitive-analysis
document-analyst	Review transcripts, reports, PDFs, or decks	summary, risks, action items, open questions	-
support-triage	Triage support tickets or issue exports	prioritized queue with owners and next steps	issue-triage
api-extractor	Crawl docs and draft an API summary plus spec	endpoint summary and draft openapi.yaml	docs-to-openapi
security-audit	Run a structured security review	vulnerability report with remediation steps	-

Need CRM access, ticket systems, or internal APIs? Add custom tools to the sandbox.

Add toolpacks

Use ds add to install bundled MCP integrations into the current project:

ds add --list              # Show all available toolpacks
ds add linear              # Issue tracking via Linear
ds add notion              # Knowledge base via Notion
ds add firecrawl           # Web scraping via Firecrawl
ds add exa                 # AI-powered search via Exa
ds add github              # GitHub repos, issues, and PRs

Each command updates sandstorm.json, writes the required API key to .env and .env.example, and future CLI/API/Slack runs from that project expose the MCP server in the sandboxed agent runtime.

If the project already has a different entry for that MCP server, ds add stops instead of overwriting it. Re-run with --force to replace the existing config.

Why Sandstorm exists

Most agent projects break down in one of two ways:

• You wire the SDK yourself and end up rebuilding sandbox lifecycle, file uploads, streaming, config loading, and starter setup.
• You use an agent framework that is good at orchestration but weak at actually shipping a runnable agent product path.

Sandstorm is opinionated about the missing middle:

• starter to runnable project in one command
• fresh sandbox per request with teardown by default
• CLI, API, and Slack over the same runtime
• config-driven behavior through sandstorm.json
• built-in document tooling for PDF, DOCX, and PPTX workflows

Why not wire the SDK yourself?

Capability	Sandstorm	Raw SDK + E2B	DIY runner
Fresh sandbox per request	Built in	Manual wiring	Manual wiring
Streaming API endpoint	Built in	Manual wiring	Custom work
File uploads	Built in	Manual wiring	Custom work
sandstorm.json config layer	Built in	No	Custom work
Slack bot integration	Built in	No	Custom work
Starter scaffolding with ds init	Built in	No	Custom work

Docs

• Getting started
• Python client
• Configuration
• API reference
• Slack bot
• Deployment
• OpenRouter
• Advanced examples

Community

If Sandstorm saves you runner plumbing, please star the repo.

If you want a new starter, a provider integration, or a sharper deploy story, open an issue or start a discussion.