shreed27/sandbox

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