git:20260130.78e49cb to git:20260210.cd0fc2e

- 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

-

- ```typescript

- 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

-

- ```typescript

- // 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

-

- ```typescript

- // 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

-

- ```typescript

- const result = await sandbox.runFile({

- language: 'python',

- filePath: '/path/to/script.py',

- args: ['--input', 'data.csv'],

- });

- ```

-

- ### Install Packages

-

- ```typescript

- // 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

- ```typescript

- 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

-

- ```typescript

- // 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

- ```typescript

- const result = await sandbox.run({

- language: 'python',

- code: backtestCode,

- packages: ['pandas', 'numpy', 'ta'],

- timeout: 60000,

- memoryMB: 512,

- });

-

- ### Data Processing

-

- ```typescript

- 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