isol8
Original:🇺🇸 English
Translated
2 scriptsChecked / no sensitive code detected
Securely execute untrusted Python, Node.js, Bun, Deno, and Bash code in sandboxed Docker containers.
6installs
Sourceillusion47586/isol8
Added on
NPX Install
npx skill4agent add illusion47586/isol8 isol8Tags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Isol8 Skill
Isol8 is a secure execution engine for running untrusted code inside Docker containers with strict resource limits, network controls, and output sanitization. Use this skill when you need to execute code, scripts, or system commands in a safe, isolated environment.
For full documentation, see the isol8 docs. This file is a quick-reference for AI agents — it covers the most common operations and links to detailed docs for everything else.
Quick Reference
CLI Commands
| Command | Purpose | Full Docs |
|---|---|---|
| Execute code in an isolated container | CLI: run |
| Build Docker images, optionally bake in packages | CLI: setup |
| Remove orphaned isol8 containers | CLI: cleanup |
| Start HTTP server for remote execution (requires Bun) | CLI: serve |
| Display resolved configuration | CLI: config |
Input Resolution (isol8 run
)
isol8 run- flag (inline code, defaults to
--evalruntime)python - File argument (runtime auto-detected from extension, or forced with )
--runtime - Stdin (defaults to runtime)
python
Extension mapping: → python, → node, → bun, → deno, → bash
.py.js.ts.mts.shMost-Used Flags (isol8 run
)
isol8 run| Flag | Default | Description |
|---|---|---|
| — | Execute inline code |
| auto-detect | Force: |
| | Keep container alive between runs |
| — | Install package before execution (repeatable) |
| | Network: |
| | Execution timeout |
| | Memory limit |
| — | Secret env var, value masked in output (repeatable) |
| — | Pipe data to stdin |
For the complete flag reference (20 flags total), see CLI: run.
CLI Examples
bash
# Python inline
isol8 run -e "print('Hello!')" --runtime python
# Run a file (runtime auto-detected)
isol8 run script.py
# With package installation
isol8 run -e "import numpy; print(numpy.__version__)" --runtime python --install numpy
# Pipe via stdin
echo "console.log(42)" | isol8 run --runtime node
# Secrets (masked as *** in output)
isol8 run -e "import os; print(os.environ['KEY'])" --runtime python --secret KEY=sk-1234
# Remote execution
isol8 run script.py --host http://server:3000 --key my-api-key
# Cleanup orphaned containers
isol8 cleanup # Interactive (prompts for confirmation)
isol8 cleanup --force # Skip confirmationLibrary API (Quick Reference)
For full library documentation, see Library Overview.
DockerIsol8
typescript
import { DockerIsol8 } from "isol8";
const isol8 = new DockerIsol8({
mode: "ephemeral", // or "persistent"
network: "none", // or "host" or "filtered"
memoryLimit: "512m",
cpuLimit: 1.0,
timeoutMs: 30000,
secrets: {}, // values masked in output
});
await isol8.start();
const result = await isol8.execute({
code: 'print("hello")',
runtime: "python",
installPackages: ["numpy"], // optional
});
console.log(result.stdout); // captured output
console.log(result.exitCode); // 0 = success
console.log(result.durationMs);
await isol8.stop();Full options reference: Execution Options
RemoteIsol8
typescript
import { RemoteIsol8 } from "isol8";
const isol8 = new RemoteIsol8(
{ host: "http://localhost:3000", apiKey: "secret" },
{ network: "none" }
);
await isol8.start();
const result = await isol8.execute({ code: "print(1)", runtime: "python" });
await isol8.stop();Streaming
typescript
for await (const event of isol8.executeStream({
code: 'for i in range(5): print(i)',
runtime: "python",
})) {
if (event.type === "stdout") process.stdout.write(event.data);
if (event.type === "exit") console.log("Exit code:", event.data);
}Full streaming docs: Streaming
File I/O (Persistent Mode)
typescript
await isol8.putFile("/sandbox/data.csv", "col1,col2\n1,2");
const buf = await isol8.getFile("/sandbox/output.txt");Full file I/O docs: File I/O
HTTP Server API
Full endpoint reference: Server Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| | No | Health check |
| | Yes | Execute code, return result |
| | Yes | Execute code, SSE stream |
| | Yes | Upload file (base64) |
| | Yes | Download file (base64) |
| | Yes | Destroy persistent session |
Configuration
Config is loaded from (first found): or . Partial configs are deep-merged with defaults.
./isol8.config.json~/.isol8/config.jsonFull configuration reference: Configuration
Security Defaults
| Layer | Default |
|---|---|
| Filesystem | Read-only root, |
| Processes | PID limit 64, |
| Resources | 1 CPU, 512MB memory, 30s timeout |
| Network | Disabled ( |
| Output | Truncated at 1MB, secrets masked |
Container Filesystem:
- (512MB): Working directory, packages installed here, execution allowed for
/sandboxfiles.so - (256MB): Temporary files, no execution allowed for security
/tmp
Full security model: Security
Troubleshooting
- "Docker not running": Run to check.
isol8 setup - Timeouts: Increase . Process is killed on timeout.
--timeout - OOM Killed: Increase .
--memory - "No space left on device": Increase (default 512MB) or
--sandbox-size(default 256MB).--tmp-size - "Operation not permitted" with numpy/packages: Packages need large enough for installation (512MB+ recommended).
--sandbox-size - files running with Bun instead of Deno:
.tsdefaults to Bun. Use.tsor--runtime denoextension..mts - Serve command failing: Requires Bun runtime. Run with .
bun run src/cli.ts serve