Runtime reference

isol8 supports six runtimes with a shared execution contract (ExecutionRequest.runtime) and runtime-specific command/extension behavior.

Supported runtimes

Runtime	Base image	Default extension	Extension aliases	Inline support
Python	`isol8:python`	`.py`	none	Yes
Node	`isol8:node`	`.mjs`	`.js`, `.cjs`	Yes
Bun	`isol8:bun`	`.ts`	none	Yes
Deno	`isol8:deno`	`.mts`	none	Yes (engine writes temp file)
Bash	`isol8:bash`	`.sh`	none	Yes
Agent	`isol8:agent`	none	none	Yes (prompt text via `-e`)

Registration order matters for extension detection: Bun wins .ts; Deno uses .mts to avoid collision. The Agent runtime has no extension mapping and must always be specified explicitly via --runtime agent.

How runtime selection works

CLI
Library
API

# Auto-detect from extension
isol8 run script.py
isol8 run app.js
isol8 run job.ts
isol8 run task.mts

# Explicit override
isol8 run script.any --runtime python

# Agent (always explicit, prompt as -e)
isol8 run -e "add tests for all endpoints" --runtime agent \
  --net filtered --allow "api.anthropic.com" \
  --secret "ANTHROPIC_API_KEY=sk-..."

await engine.execute({
  runtime: "python",
  code: "print('hello')",
});

// Agent runtime (code = prompt text)
await engine.execute({
  runtime: "agent",
  code: "refactor this module to use async/await",
});

{
  "request": {
    "runtime": "python",
    "code": "print('hello')"
  }
}

Node.js module behavior (CJS and ESM)

.mjs: ESM
.cjs: CommonJS
.js: Node default resolution behavior
inline (-e/code) executes through node -e

If module mode matters, use explicit extensions (.mjs / .cjs) or force runtime + file extension in request construction.

Runtime execution commands

Runtime	Inline command	File command
Python	`python3 -c <code>`	`python3 <file>`
Node	`node -e <code>`	`node <file>`
Bun	`bun -e <code>`	`bun run <file>`
Deno	Engine writes file first	`deno run --allow-read=/sandbox,/tmp --allow-write=/sandbox,/tmp --allow-env --allow-net <file>`
Bash	`bash -c <code>`	`bash <file>`
Agent	`bash -c "pi --no-session [agentFlags] -p <prompt>"`	N/A (always inline prompt)

Package install behavior (`installPackages` / `--install`)

Runtime	Runtime install command	Setup image build command
Python	`pip install --user --no-cache-dir --break-system-packages ...`	`pip install --no-cache-dir ...`
Node	`npm install --prefix /sandbox ...`	`npm install -g ...`
Bun	`bun install -g --global-dir=...`	`bun install -g ...`
Deno	`deno cache ...`	`deno cache ...`
Bash	`apk add --no-cache ...`	`apk add --no-cache ...`
Agent	`bun install -g --global-dir=...`	`bun install -g ...`

Runtime installs are written under /sandbox so native extensions can execute (/tmp is noexec).

Runtime-specific notes

Python

strong ecosystem for data/scientific workloads
packages install under /sandbox/.local

Node

best for JS ecosystem tooling and JSON transforms
supports .mjs, .cjs, and .js

Bun

fastest TS/JS startup for many workloads
default extension mapping for .ts

Deno

explicit .mts path avoids .ts ambiguity with Bun
adapter requires file execution; inline requests are materialized as files by engine

Bash

useful for shell orchestration and glue scripts
package installs use Alpine apk

Agent

runs the pi coding agent inside the sandbox
the -e value is always treated as the prompt text, not code
requires network: "filtered" with at least one whitelist entry (the agent needs LLM API access)
defaults to higher resource limits: pidsLimit: 200, sandboxSize: "2g"
extra pi flags (e.g. --model, --thinking) are passed via --agent-flags (CLI) or agentFlags (library/API)
use --files <dir> to inject a local project directory into /sandbox for the agent to work on
file output after execution is the user’s responsibility via the prompt

FAQ

Why does .ts run on Bun, not Deno?

Runtime registry gives Bun ownership of .ts. Use .mts for Deno or explicit runtime: "deno".

Can I switch runtimes inside one persistent session?

No. Persistent containers are runtime-bound. Use separate sessions for Python/Node/Bun/Deno/Bash/Agent.

Why does the agent runtime require filtered networking?

The agent needs to call an LLM API (e.g. Anthropic, OpenAI) to function. The engine enforces network: "filtered" with at least one whitelist entry to ensure the agent has controlled API access while preventing unrestricted network use.

Why do some packages fail on Alpine-based images?

Some packages expect glibc or extra system libs. Use custom images with required dependencies or compatible alternatives.

Troubleshooting

Runtime detection mismatch: pass explicit --runtime (CLI) or request.runtime.
Module mode issues in Node: use explicit .mjs or .cjs file extension.
Deno inline confusion: send inline code normally; engine writes temp file for Deno execution.
Install failures: verify network mode and package manager compatibility for selected runtime.

Execution guide

Request lifecycle, modes, I/O, streaming, and resource limits.

Packages and images

Dependency strategy: runtime installs vs pre-baked custom images.

Option mapping

Exact CLI/config/API/library mapping for runtime and options.

Troubleshooting

Fix common runtime and environment issues.

Get Started

Core Concepts

Deployment & Ops

Reference

Help

Runtime reference

Supported runtimes

How runtime selection works

Node.js module behavior (CJS and ESM)

Runtime execution commands

Package install behavior (`installPackages` / `--install`)

Runtime-specific notes

Python

Node

Bun

Deno

Bash

Agent

FAQ

Troubleshooting

Execution guide

Packages and images

Option mapping

Troubleshooting

​Supported runtimes

​How runtime selection works

​Node.js module behavior (CJS and ESM)

​Runtime execution commands

​Package install behavior (installPackages / --install)

​Runtime-specific notes

​Python

​Node

​Bun

​Deno

​Bash

​Agent

​FAQ

​Troubleshooting

​Related pages

Execution guide

Packages and images

Option mapping

Troubleshooting

Supported runtimes

How runtime selection works

Node.js module behavior (CJS and ESM)

Runtime execution commands

Package install behavior (`installPackages` / `--install`)

Runtime-specific notes

Python

Node

Bun

Deno

Bash

Agent

FAQ

Troubleshooting

Related pages