Runtime reference

Supported runtimes, extension mapping, module behavior, and package-install semantics for Python, Node, Bun, Deno, Bash, and Agent.

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

# 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-..."

Library

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",
});

API

{
  "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.

Related pages

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.