Back to Details

isol8

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Isol8 Skill

Isol8 工具

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.
Isol8 是一个安全执行引擎，可在带有严格资源限制、网络控制和输出清理的Docker容器中运行不可信代码。当你需要在安全、隔离的环境中执行代码、脚本或系统命令时，可以使用这个工具。
完整文档请查看 isol8 docs。本文档是AI Agent的快速参考指南——涵盖最常用操作，并链接到其他所有内容的详细文档。

Quick Reference

快速参考

CLI Commands

CLI 命令

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
命令用途完整文档
isol8 run [file]
在隔离容器中执行代码CLI: run
isol8 setup
构建Docker镜像，可选择性预装包CLI: setup
isol8 cleanup
移除孤立的isol8容器CLI: cleanup
isol8 serve
启动HTTP服务器用于远程执行（需要Bun）CLI: serve
isol8 config
显示已解析的配置CLI: config

Input Resolution (
isol8 run
)

输入解析（
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
  1. --eval
    参数（单行代码，默认使用
    python
    运行时）
  2. 文件参数（根据扩展名自动检测运行时，或使用
    --runtime
    强制指定）
  3. 标准输入（默认使用
    python
    运行时）
扩展名映射： 
.py
→ python, 
.js
→ node, 
.ts
→ bun, 
.mts
→ deno, 
.sh
→ bash

Most-Used Flags (
isol8 run
)

最常用参数（
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.
参数默认值描述
-e, --eval <code>
—执行单行代码
-r, --runtime <name>
自动检测强制指定：
python
, 
node
, 
bun
, 
deno
, 
bash
--persistent
false
在多次运行之间保持容器存活
--install <package>
—执行前安装包（可重复使用）
--net <mode>
none
网络模式：
none
, 
host
, 
filtered
--timeout <ms>
30000
执行超时时间
--memory <limit>
512m
内存限制
--secret <KEY=VALUE>
—敏感环境变量，值在输出中会被掩码（可重复使用）
--stdin <data>
—将数据通过标准输入传入
完整参数参考（共20个参数）请查看 CLI: run。

CLI Examples

CLI 示例

bash
undefined
bash
undefined

Python inline

Python inline

isol8 run -e "print('Hello!')" --runtime python
isol8 run -e "print('Hello!')" --runtime python

Run a file (runtime auto-detected)

Run a file (runtime auto-detected)

isol8 run script.py
isol8 run script.py

With package installation

With package installation

isol8 run -e "import numpy; print(numpy.version)" --runtime python --install numpy
isol8 run -e "import numpy; print(numpy.version)" --runtime python --install numpy

Pipe via stdin

Pipe via stdin

echo "console.log(42)" | isol8 run --runtime node
echo "console.log(42)" | isol8 run --runtime node

Secrets (masked as *** in output)

Secrets (masked as *** in output)

isol8 run -e "import os; print(os.environ['KEY'])" --runtime python --secret KEY=sk-1234
isol8 run -e "import os; print(os.environ['KEY'])" --runtime python --secret KEY=sk-1234

Remote execution

Remote execution

isol8 run script.py --host http://server:3000 --key my-api-key
isol8 run script.py --host http://server:3000 --key my-api-key

Cleanup orphaned containers

Cleanup orphaned containers

isol8 cleanup # Interactive (prompts for confirmation) isol8 cleanup --force # Skip confirmation
undefined
isol8 cleanup # Interactive (prompts for confirmation) isol8 cleanup --force # Skip confirmation
undefined

Library API (Quick Reference)

库API（快速参考）

For full library documentation, see Library Overview.
完整库文档请查看 Library Overview。

DockerIsol8

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
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();
完整参数参考：Execution Options

RemoteIsol8

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();
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
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);
}
完整流式执行文档：Streaming

File I/O (Persistent Mode)

文件I/O（持久化模式）

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
typescript
await isol8.putFile("/sandbox/data.csv", "col1,col2\n1,2");
const buf = await isol8.getFile("/sandbox/output.txt");
完整文件I/O文档：File I/O

HTTP Server API

HTTP服务器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
完整端点参考：Server Endpoints
方法路径认证描述
GET
/health
否健康检查
POST
/execute
是执行代码，返回结果
POST
/execute/stream
是执行代码，使用SSE流式返回
POST
/file
是上传文件（base64格式）
GET
/file
是下载文件（base64格式）
DELETE
/session/:id
是销毁持久化会话

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
配置从以下位置加载（优先找到的第一个）：
./isol8.config.json
或 
~/.isol8/config.json
。部分配置会与默认配置深度合并。
完整配置参考：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
层级默认值
文件系统只读根目录，
/sandbox
临时文件系统512MB（允许执行），
/tmp
临时文件系统256MB（禁止执行）
进程PID限制64，启用
no-new-privileges
资源1核CPU，512MB内存，30秒超时
网络禁用（
none
）
输出截断至1MB，敏感信息掩码
容器文件系统：
  • /sandbox
    （512MB）：工作目录，包安装在此处，允许
    .so
    文件执行
  • /tmp
    （256MB）：临时文件目录，为安全起见禁止执行
完整安全模型：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
    .
  • "Docker not running"：运行
    isol8 setup
    检查。
  • 超时：增加
    --timeout
    参数。超时后进程会被终止。
  • OOM被终止：增加
    --memory
    参数。
  • "No space left on device"：增加
    --sandbox-size
    （默认512MB）或
    --tmp-size
    （默认256MB）。
  • 安装numpy/包时提示"Operation not permitted"：包安装需要足够的
    --sandbox-size
    （推荐512MB以上）。
  • .ts
    文件使用Bun而非Deno运行    ：
    .ts
    默认使用Bun。使用
    --runtime deno
    或
    .mts
    扩展名。
  • Serve命令失败：需要Bun运行时。使用
    bun run src/cli.ts serve
    启动。