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
Added on

NPX Install

npx skill4agent add illusion47586/isol8 isol8

Tags

Translated version includes tags in frontmatter

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

CommandPurposeFull Docs
isol8 run [file]
Execute code in an isolated containerCLI: run
isol8 setup
Build Docker images, optionally bake in packagesCLI: setup
isol8 cleanup
Remove orphaned isol8 containersCLI: cleanup
isol8 serve
Start HTTP server for remote execution (requires Bun)CLI: serve
isol8 config
Display resolved configurationCLI: config

Input Resolution (
isol8 run
)

  1. --eval
    flag (inline code, defaults to
    python
    runtime)
  2. File argument (runtime auto-detected from extension, or forced with
    --runtime
    )
  3. Stdin (defaults to
    python
    runtime)
Extension mapping:
.py
→ python,
.js
→ node,
.ts
→ bun,
.mts
→ deno,
.sh
→ bash

Most-Used Flags (
isol8 run
)

FlagDefaultDescription
-e, --eval <code>
Execute inline code
-r, --runtime <name>
auto-detectForce:
python
,
node
,
bun
,
deno
,
bash
--persistent
false
Keep container alive between runs
--install <package>
Install package before execution (repeatable)
--net <mode>
none
Network:
none
,
host
,
filtered
--timeout <ms>
30000
Execution timeout
--memory <limit>
512m
Memory limit
--secret <KEY=VALUE>
Secret env var, value masked in output (repeatable)
--stdin <data>
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 confirmation

Library 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
MethodPathAuthDescription
GET
/health
NoHealth check
POST
/execute
YesExecute code, return result
POST
/execute/stream
YesExecute code, SSE stream
POST
/file
YesUpload file (base64)
GET
/file
YesDownload file (base64)
DELETE
/session/:id
YesDestroy persistent session

Configuration

Config is loaded from (first found):
./isol8.config.json
or
~/.isol8/config.json
. Partial configs are deep-merged with defaults.
Full configuration reference: Configuration

Security Defaults

LayerDefault
FilesystemRead-only root,
/sandbox
tmpfs 512MB (exec allowed),
/tmp
tmpfs 256MB (noexec)
ProcessesPID limit 64,
no-new-privileges
Resources1 CPU, 512MB memory, 30s timeout
NetworkDisabled (
none
)
OutputTruncated at 1MB, secrets masked
Container Filesystem:
  • /sandbox
    (512MB): Working directory, packages installed here, execution allowed for
    .so
    files
  • /tmp
    (256MB): Temporary files, no execution allowed for security
Full security model: Security

Troubleshooting

  • "Docker not running": Run
    isol8 setup
    to check.
  • Timeouts: Increase
    --timeout
    . Process is killed on timeout.
  • OOM Killed: Increase
    --memory
    .
  • "No space left on device": Increase
    --sandbox-size
    (default 512MB) or
    --tmp-size
    (default 256MB).
  • "Operation not permitted" with numpy/packages: Packages need
    --sandbox-size
    large enough for installation (512MB+ recommended).
  • .ts
    files running with Bun instead of Deno
    :
    .ts
    defaults to Bun. Use
    --runtime deno
    or
    .mts
    extension.
  • Serve command failing: Requires Bun runtime. Run with
    bun run src/cli.ts serve
    .