← Back to Docs

🏗️ DCDN Sandbox

Decentralized agent sandboxes — persistent, isolated environments for AI agents on the DCDN node network.

Quick Start

JavaScript / TypeScript

npm install @dcdn/sandbox

import { DcdnSandbox } from '@dcdn/sandbox';

const client = new DcdnSandbox({ apiKey: 'dcdn_live_...' });

// Get or create a sandbox (idempotent)
const sbx = await client.getOrCreate('my-coding-agent', {
  image: 'dcdn/sandbox-python',
  size: 'basic',
});

// Run commands
const result = await sbx.exec('python -c "print(42)"');
console.log(result.stdout); // "42"

// File operations
await sbx.writeFile('/workspace/app.py', 'print("hello world")');
const content = await sbx.readFile('/workspace/app.py');

// Git clone
await sbx.gitClone('https://github.com/org/repo', { targetDir: '/workspace' });

// Background process + preview URL
const proc = await sbx.startProcess('npm run dev', { cwd: '/workspace' });
const { url } = await sbx.exposePort(3000);
console.log(`Preview: ${url}`);

// Snapshot and restore
const snap = await sbx.snapshot();
await sbx.restore(snap.snapshotId);

// Sleep / Wake
await sbx.sleep();   // pauses instantly
await sbx.wake();    // resumes instantly

// Clean up
await sbx.destroy();

Python

pip install dcdn-sandbox

from dcdn_sandbox import Sandbox

# Get or create (idempotent)
sbx = Sandbox(api_key="dcdn_live_...", name="my-agent")

# Execute commands
result = sbx.exec("echo hello && uname -a")
print(result.stdout)

# File operations
sbx.write_file("/workspace/data.csv", "a,b,c\n1,2,3")
content = sbx.read_file("/workspace/data.csv")

# Background processes
proc = sbx.start_process("python server.py")
print(f"PID: {proc.pid}, logs: {proc.log_file}")

# Snapshots
snap = sbx.snapshot()
sbx.restore(snap.snapshot_id)

# Lifecycle
sbx.sleep()
sbx.wake()
sbx.destroy()

cURL

# Create sandbox
curl -X POST https://dcdncloud.com/api/v1/sandbox \
  -H "Authorization: Bearer dcdn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-sandbox", "image": "ubuntu:22.04", "size": "basic"}'

# Execute command
curl -X POST https://dcdncloud.com/api/v1/sandbox/sbx-abc123/exec \
  -H "Authorization: Bearer dcdn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"command": "echo hello world"}'

API Reference

Method	Endpoint	Description
POST	/sandbox	Create or get sandbox by name (idempotent)
GET	/sandbox	List all sandboxes
GET	/sandbox/{id}	Get sandbox details
DELETE	/sandbox/{id}	Destroy sandbox
POST	/sandbox/{id}/exec	Execute command
PUT	/sandbox/{id}/files/write	Write file
GET	/sandbox/{id}/files/read	Read file
GET	/sandbox/{id}/files	List directory
GET	/sandbox/{id}/files/watch	Watch filesystem (SSE)
POST	/sandbox/{id}/git/clone	Git clone into sandbox
POST	/sandbox/{id}/process	Start background process
GET	/sandbox/{id}/processes	List processes
DELETE	/sandbox/{id}/process/{pid}	Kill process
GET	/sandbox/{id}/process/{pid}/logs	Get process logs
POST	/sandbox/{id}/expose	Expose port (preview URL)
GET	/sandbox/{id}/ports	List exposed ports
POST	/sandbox/{id}/snapshot	Take snapshot
GET	/sandbox/{id}/snapshots	List snapshots
POST	/sandbox/{id}/restore	Restore from snapshot
POST	/sandbox/{id}/sleep	Sleep (pause) sandbox
POST	/sandbox/{id}/wake	Wake (resume) sandbox
WS	/sandbox/{id}/terminal	WebSocket PTY terminal

Pricing

Active CPU pricing — you only pay when your sandbox is actively computing. Sleeping sandboxes cost $0.

Images

Image	Contents
dcdn/sandbox-base	Ubuntu 22.04, Python 3.11, Node 20, Git, curl
dcdn/sandbox-python	+ pandas, numpy, matplotlib, jupyter
dcdn/sandbox-node	+ npm, yarn, pnpm, TypeScript
dcdn/sandbox-full	All of the above + Go, Rust
ubuntu:22.04	Stock Ubuntu
python:3.12-slim	Minimal Python
node:22-slim	Minimal Node.js

Payment

Sandbox usage is billed from your Marketplace USD Balance, funded via Stripe. No crypto required.

• Minimum balance: 1 hour of your chosen size (e.g. $0.01 for Basic)
• Metered every 5 minutes — deducted automatically
• If balance runs out → sandbox auto-sleeps (no data loss)
• Top up: Dashboard → 🏪 Marketplace → Top Up

Mesh Network Integration

Attach a sandbox to your DCDN Mesh to access private resources:

POST /api/v1/sandbox
{
  "name": "my-sandbox",
  "size": "basic",
  "mesh_network_id": "net-abc123"   // attach to mesh
}

The sandbox gets a WireGuard interface and can reach all peers + exposed routes. Apply mesh policies to control access.

vs Cloudflare Sandboxes

Feature	Cloudflare	DCDN
Infrastructure	Centralized (CF edge)	Decentralized (8+ nodes)
Vendor lock-in	High (CF Workers ecosystem)	None (standard Docker)
Agent payments	API key only	x402 (USDC, no account)
Custom images	Limited	Any Docker image
Revenue model	100% Cloudflare	70% node operator / 25% platform
Pricing	CF Workers pricing	From $0.005/hr (80% cheaper)

DCDN Cloud — Decentralized CDN, DNS, WAF, GPU Cloud & AI Platform
dcdncloud.com · Marketplace · Mesh · Docs · Dashboard