Execution guide

isol8 provides a unified execution engine accessible through three interfaces: a CLI for local development, a TypeScript Library for application integration, and an HTTP API for remote services.

Execution Lifecycle

Every execution request follows a strict pipeline to ensure security and isolation.

Pipeline Overview

In ephemeral mode, simple requests can skip file injection and execute inline (for example python -c, node -e, bun -e, bash -c) when no stdin, files, outputPaths, or package installs are requested. The agent runtime always uses file injection and passes the code as a prompt to the pi coding agent.

Execution Modes

isol8 supports two execution modes, determined by your use case.

Mode	Behavior	Best For
Ephemeral (Default)	Creates a fresh container for every request. State is lost after execution.	stateless tasks, untrusted code, parallel workloads
Persistent	Reuses a single container across multiple requests. Files and state are preserved.	interactive sessions, multi-step workflows, notebooks

Selecting a Mode

CLI
Library
API

Use the --persistent flag to enable persistent mode.

# Ephemeral (Default)
isol8 run script.py

# Persistent (Keeps container alive)
isol8 run --persistent script.py

In CLI persistent mode, the container is tied to the CLI process. To reuse a persistent container across multiple CLI commands, you would need to use the API or Library.

Configure the mode when initializing the engine.

// Ephemeral (Default)
const engine = new DockerIsol8({ mode: "ephemeral" });

// Persistent
const session = new DockerIsol8({ mode: "persistent" });
await session.execute({ ... }); // State preserved for next call

Include a sessionId to trigger persistent mode.

// Ephemeral (No sessionId)
{
  "request": { "code": "x = 1", "runtime": "python" }
}

// Persistent (With sessionId)
{
  "sessionId": "user-session-123",
  "request": { "code": "print(x)", "runtime": "python" }
}

Inputs & Outputs

You can pass code, environment variables, and files into the sandbox.

1. Source Code

The core of every request.

CLI
Library
API

Pass a file path, an inline string, or pipe from stdin.

# File
isol8 run script.py

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

# Stdin
echo "print('Piped')" | isol8 run --runtime python

Pass the code string in the request object.

await engine.execute({
  code: "console.log('Hello')",
  runtime: "node"
});

{
  "request": {
    "code": "console.log('Hello')",
    "runtime": "node"
  }
}

1.1 Remote Code URLs

isol8 can fetch source code from a URL before execution.

code and codeUrl are mutually exclusive. Provide only one per request.

Remote URL execution is controlled by:

request fields: codeUrl, codeHash, allowInsecureCodeUrl
CLI flags: --url, --github, --gist, --hash, --allow-insecure-code-url
config policy: remoteCode.* in isol8.config.json

CLI
Library
API

# Direct URL
isol8 run --url https://raw.githubusercontent.com/user/repo/main/script.py --runtime python

# GitHub shorthand
isol8 run --github user/repo/main/script.py --runtime python

# Gist shorthand
isol8 run --gist abcd1234/example.js --runtime node

# Integrity verification
isol8 run --url https://example.com/script.py --hash <sha256> --runtime python

await engine.execute({
  codeUrl: "https://raw.githubusercontent.com/user/repo/<sha>/script.py",
  codeHash: "<sha256>",
  runtime: "python",
});

{
  "request": {
    "codeUrl": "https://raw.githubusercontent.com/user/repo/<sha>/script.py",
    "codeHash": "<sha256>",
    "runtime": "python"
  }
}

URL fetching is disabled by default. Enable and tune remoteCode policy in config first. For full policy fields and security guidance, see Remote code URLs.

2. Environment Variables

Inject configuration or secrets.

Security Note: Environment variables are visible to the running process. For sensitive data, use the “Secrets” feature to ensure values are masked in logs and output.

CLI
Library
API

The CLI only supports Secrets via --secret. These are injected as environment variables but their values are masked in stdout/stderr.

isol8 run script.py --secret API_KEY=sk_12345

You can pass plain env variables (visible) or global secrets (masked).

const engine = new DockerIsol8({
  // Global secrets (masked in output)
  secrets: { API_KEY: "sk_12345" }
});

await engine.execute({
  code: "...",
  runtime: "python",
  // Per-request env vars (visible in output)
  env: { LOG_LEVEL: "debug" }
});

{
  "request": {
    "runtime": "python",
    "code": "import os; print(os.getenv('LOG_LEVEL', 'unset'))",
    "env": { "LOG_LEVEL": "debug" }
  }
}

3. Files

Inject files before execution and retrieve them after.

CLI
Library
API

The CLI supports file injection for the agent runtime via --files <dir>, which recursively copies a local directory into /sandbox. For other runtimes, use the Library or API for generic file injection (files) or retrieval (outputPaths). All runtimes support --out to capture stdout to a file.

# Capture stdout to file
isol8 run script.py --out result.txt

# Inject project files for agent runtime
isol8 run -e "add tests" --runtime agent \
  --files ./my-project \
  --net filtered --allow "api.anthropic.com" \
  --secret "ANTHROPIC_API_KEY=sk-..."

Full support for virtual file I/O.

const result = await engine.execute({
  code: "print(open('/sandbox/data.txt').read())",
  runtime: "python",
  // Inject files
  files: {
    "/sandbox/data.txt": "Hello from file!"
  },
  // Retrieve files
  outputPaths: ["/sandbox/output.json"]
});

const fileContent = result.files["/sandbox/output.json"]; // base64 encoded

{
  "request": {
    "runtime": "python",
    "code": "print(open('/sandbox/data.txt').read())",
    "files": {
      "/sandbox/data.txt": "Hello from file!"
    },
    "outputPaths": ["/sandbox/output.json"]
  }
}

Streaming Output

Real-time output is essential for long-running tasks or LLM code generation.

CLI
Library
API

Streaming is enabled by default. Use --no-stream to wait for completion.

# Streams output as it appears
isol8 run long_task.py

# Waits until finished, then prints all output
isol8 run long_task.py --no-stream

Use executeStream instead of execute.

const stream = engine.executeStream({
  code: "...",
  runtime: "python"
});

for await (const event of stream) {
  if (event.type === 'stdout') process.stdout.write(event.data);
  if (event.type === 'stderr') process.stderr.write(event.data);
  if (event.type === 'exit') console.log(`Exited with ${event.data}`);
}

curl -N -X POST http://localhost:3000/execute/stream \
  -H "Authorization: Bearer $ISOL8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "runtime": "python",
      "code": "import time\nfor i in range(3):\n print(i)\n time.sleep(1)"
    }
  }'

When using RemoteIsol8, executeStream() automatically selects the best available transport: WebSocket (/execute/ws) with automatic SSE (/execute/stream) fallback. See the WebSocket endpoint reference for protocol details.

StreamEvent reference

Each value yielded by executeStream is a StreamEvent:

Field	Type	Description
`type`	`"stdout" \| "stderr" \| "exit" \| "error"`	Event kind. `exit` carries the process exit code as a string in `data`.
`data`	`string`	Payload: output text for stdout/stderr, exit code string for exit, error message for error.
`phase`	`"setup" \| "code"`	Which stage produced the event. `"setup"` = from a `setupScript`; `"code"` = from the main code/command. Always set by isol8.

Use phase to distinguish setupScript output from main code output when both are present:

for await (const event of engine.executeStream({
  runtime: "bash",
  setupScript: "git clone https://$GITHUB_TOKEN@github.com/my-org/repo.git /sandbox/repo",
  code: "ls /sandbox/repo",
})) {
  if (event.phase === "setup") {
    process.stderr.write(`[setup] ${event.data}`);
  } else if (event.type === "stdout") {
    process.stdout.write(event.data);
  }
}

If a setupScript exits non-zero, executeStream yields an error event then an exit event (both with phase: "setup") and stops — no phase: "code" events follow. See Setup scripts for full details.

Resource Limits & Safety

isol8 enforces strict limits to contain untrusted code.

Parameter	CLI Flag	Library Option	Default	Description
Timeout	`--timeout`	`timeoutMs`	30s	Hard execution time limit.
Memory	`--memory`	`memoryLimit`	512m	RAM limit for the container.
CPU	`--cpu`	`cpuLimit`	1.0	CPU shares (1.0 = 1 core).
Network	`--net`	`network`	none	`none`, `host`, or `filtered`.
Output	`--max-output`	`maxOutputSize`	1MB	Max stdout/stderr size before truncation.

Output Truncation

If a script produces excessive output, isol8 truncates it to prevent memory issues.

result.truncated will be true.
The output will end with a truncation message.

Secret Masking

If you provide secrets (via CLI --secret or Library config), isol8 scans stdout and stderr and replaces occurrences of secret values with ***.

# Input
isol8 run -e "print('my-secret-value')" --secret KEY=my-secret-value

# Output
***

Troubleshooting

Execution Timed Out

The code ran longer than timeoutMs.

Fix: Increase limit via --timeout or optimize the code.
Note: Infinite loops are a common cause.

Output Truncated

The script printed more data than maxOutputSize allowed.

Fix: Reduce logging or increase the limit via --max-output.

File Not Found

Remember that the code runs in an isolated container.

It cannot see files on your host machine unless you explicitly inject them (Library/API).
CLI users should pipe data via stdin or use inline strings for simple inputs.

FAQ

Should I pass timeout in request or options?

Use request.timeoutMs when you want a per-execution timeout. Use options.timeoutMs as a baseline engine default for a client/session.

When should I use codeUrl instead of code?

Use codeUrl for pinned remote artifacts (for example immutable GitHub raw URLs). Keep code for direct inline or generated source. Never set both in one request.

Why does persistent mode not carry over between separate CLI invocations?

CLI runs are process-scoped. For durable cross-call state, use a stable sessionId through the API or RemoteIsol8.

Option mapping

Exact option mapping across CLI, config, API, and library.

Runtime reference

Runtime-specific behavior, extensions, and package semantics.

Setup scripts

Run shell commands before execution — streaming output, phase events, and early-exit on failure.

Remote code URLs

URL-based source fetching policy and integrity controls.

Troubleshooting

Symptom-based fixes for execution and session issues.

Get Started

Core Concepts

Deployment & Ops

Reference

Help

Execution guide

Execution Lifecycle

Pipeline Overview

Execution Modes

Selecting a Mode

Inputs & Outputs

1. Source Code

1.1 Remote Code URLs

2. Environment Variables

3. Files

Streaming Output

StreamEvent reference

Resource Limits & Safety

Output Truncation

Secret Masking

Troubleshooting

FAQ

Option mapping

Runtime reference

Setup scripts

Remote code URLs

Troubleshooting

​Execution Lifecycle

​Pipeline Overview

​Execution Modes

​Selecting a Mode

​Inputs & Outputs

​1. Source Code

​1.1 Remote Code URLs

​2. Environment Variables

​3. Files

​Streaming Output

​StreamEvent reference

​Resource Limits & Safety

​Output Truncation

​Secret Masking

​Troubleshooting

​FAQ

​Related pages

Option mapping

Runtime reference

Setup scripts

Remote code URLs

Troubleshooting

Execution Lifecycle

Pipeline Overview

Execution Modes

Selecting a Mode

Inputs & Outputs

1. Source Code

1.1 Remote Code URLs

2. Environment Variables

3. Files

Streaming Output

StreamEvent reference

Resource Limits & Safety

Output Truncation

Secret Masking

Troubleshooting

FAQ

Related pages