sandbox

name	sandbox
description	Safe code execution in Docker containers with resource limits
emoji	📦
gates	{"envs":{"anyOf":["DOCKER_HOST"]}}

Sandbox - Complete API Reference

Execute code safely in isolated Docker containers with resource limits and timeout protection.

---

Chat Commands

Run Code

/run python "print('Hello')"                Run Python code
/run node "console.log('Hi')"               Run JavaScript
/run bash "ls -la"                          Run shell command
/run ruby "puts 'Hello'"                    Run Ruby code

With Options

/run python "code" --timeout 30             Set timeout (seconds)
/run node "code" --memory 512               Memory limit (MB)
/run python "code" --file script.py         From file

Sandbox Management

/sandbox status                             Container status
/sandbox images                             Available images
/sandbox cleanup                            Remove old containers

---

TypeScript API Reference

Create Sandbox

import { createSandbox } from 'clodds/sandbox';

const sandbox = createSandbox({
  // Docker settings
  dockerHost: process.env.DOCKER_HOST,

  // Default limits
  defaultTimeoutMs: 30000,
  defaultMemoryMB: 256,
  defaultCpuShares: 512,

  // Cleanup
  autoCleanup: true,
  maxContainerAgeMs: 3600000,
});

Run Code

// Run Python
const result = await sandbox.run({
  language: 'python',
  code: `
import math
print(f"Pi is {math.pi}")
  `,
});

console.log(`Output: ${result.stdout}`);
console.log(`Exit code: ${result.exitCode}`);
console.log(`Duration: ${result.durationMs}ms`);

// Run with limits
const result = await sandbox.run({
  language: 'node',
  code: `console.log('Hello from Node.js')`,
  timeout: 10000,
  memoryMB: 128,
});

Supported Languages

// Python
await sandbox.run({ language: 'python', code: 'print("Hello")' });

// JavaScript (Node.js)
await sandbox.run({ language: 'node', code: 'console.log("Hello")' });

// Bash
await sandbox.run({ language: 'bash', code: 'echo "Hello"' });

// Ruby
await sandbox.run({ language: 'ruby', code: 'puts "Hello"' });

// Go
await sandbox.run({ language: 'go', code: 'package main\nimport "fmt"\nfunc main() { fmt.Println("Hello") }' });

Run From File

const result = await sandbox.runFile({
  language: 'python',
  filePath: '/path/to/script.py',
  args: ['--input', 'data.csv'],
});

Install Packages

// Python packages
const result = await sandbox.run({
  language: 'python',
  code: `
import pandas as pd
print(pd.__version__)
  `,
  packages: ['pandas', 'numpy'],
});

// Node packages
const result = await sandbox.run({
  language: 'node',
  code: `
const _ = require('lodash');
console.log(_.VERSION);
  `,
  packages: ['lodash'],
});

Resource Limits

const result = await sandbox.run({
  language: 'python',
  code: 'import time; time.sleep(100)',

  // Limits
  timeout: 5000,        // 5 second timeout
  memoryMB: 256,        // 256 MB RAM
  cpuShares: 512,       // CPU shares (default 1024)
  networkDisabled: true, // No network access
});

Container Management

// Get status
const status = await sandbox.getStatus();
console.log(`Running containers: ${status.running}`);
console.log(`Total containers: ${status.total}`);

// List available images
const images = await sandbox.listImages();
for (const img of images) {
  console.log(`${img.language}: ${img.image}`);
}

// Cleanup old containers
await sandbox.cleanup({
  olderThan: '1h',
  status: 'exited',
});

---

Language Images

Language	Image	Version
python	python:3.11-slim	3.11
node	node:20-slim	20.x
bash	alpine:latest	Alpine
ruby	ruby:3.2-slim	3.2
go	golang:1.21-alpine	1.21

---

Resource Limits

Resource	Default	Max
Timeout	30s	300s
Memory	256 MB	2048 MB
CPU	512 shares	2048 shares
Disk	100 MB	1 GB

---

Security

Feature	Description
Isolation	Each run in separate container
No network	Network disabled by default
No volumes	No host filesystem access
Read-only	Filesystem is read-only
Resource caps	Memory and CPU limits
Timeout	Force kill after timeout

---

Use Cases

Run Backtest

const result = await sandbox.run({
  language: 'python',
  code: backtestCode,
  packages: ['pandas', 'numpy', 'ta'],
  timeout: 60000,
  memoryMB: 512,
});

Data Processing

const result = await sandbox.run({
  language: 'python',
  code: `
import json
data = ${JSON.stringify(inputData)}
result = process(data)
print(json.dumps(result))
  `,
});
const output = JSON.parse(result.stdout);

---

Best Practices

1. Set timeouts — Prevent runaway code
2. Limit memory — Avoid OOM
3. Disable network — Unless needed
4. Use slim images — Faster startup
5. Cleanup regularly — Remove old containers