TypeScript SDK
@codecapsules/sandbox is the official TypeScript client for the Sandbox API.
The API is in private beta. Join the waitlist to get an API key.
npm install @codecapsules/sandbox
Requires Node.js 18+.
Basic usage
import { Sandbox } from '@codecapsules/sandbox';
// Create, use, and auto-delete
await Sandbox.using(async (sb) => {
const r = await sb.exec('python --version');
console.log(r.stdout); // "Python 3.12.3\n"
});
Lifecycle patterns
Sandbox.using() (recommended for most cases)
Creates a sandbox, runs your function, and deletes the sandbox when done, even if the function throws.
const output = await Sandbox.using(async (sb) => {
const r = await sb.exec('python -c "print(1+1)"');
return r.stdout.trim(); // "2"
}, { flavor: 'python-3.12' });
Manual lifecycle
const sb = await Sandbox.create({ flavor: 'node-20' });
try {
const r = await sb.exec('node --version');
console.log(r.stdout);
} finally {
await sb.delete();
}
TypeScript 5.2+ await using
await using sb = await Sandbox.create();
const r = await sb.exec('echo hello');
// sb.delete() called automatically when the block exits
Configuration
Set CODECAPSULES_API_KEY in your environment, or pass it explicitly:
const sb = await Sandbox.create(
{ flavor: 'python-3.12' },
{ apiKey: 'your_api_key', timeout: 60_000, maxRetries: 3 }
);
SDK reference
- API Reference:
Sandboxclass, all methods, types, and error classes