Skip to main content
isol8 supports five runtimes with a shared execution contract (ExecutionRequest.runtime) and runtime-specific command/extension behavior.

​
Supported runtimes

RuntimeBase imageDefault extensionExtension aliasesInline support
Pythonisol8:python.pynoneYes
Nodeisol8:node.mjs.js, .cjsYes
Bunisol8:bun.tsnoneYes
Denoisol8:deno.mtsnoneYes (engine writes temp file)
Bashisol8:bash.shnoneYes
Registration order matters for extension detection: Bun wins .ts; Deno uses .mts to avoid collision.

​
How runtime selection works

# 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

​
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

RuntimeInline commandFile command
Pythonpython3 -c <code>python3 <file>
Nodenode -e <code>node <file>
Bunbun -e <code>bun run <file>
DenoEngine writes file firstdeno run --allow-read=/sandbox,/tmp --allow-write=/sandbox,/tmp --allow-env --allow-net <file>
Bashbash -c <code>bash <file>

​
Package install behavior (installPackages / --install)

RuntimeRuntime install commandSetup image build command
Pythonpip install --user --no-cache-dir --break-system-packages ...pip install --no-cache-dir ...
Nodenpm install --prefix /sandbox ...npm install -g ...
Bunbun install -g --global-dir=...bun install -g ...
Denodeno cache ...deno cache ...
Bashapk add --no-cache ...apk add --no-cache ...
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

​
FAQ

Runtime registry gives Bun ownership of .ts. Use .mts for Deno or explicit runtime: "deno".
No. Persistent containers are runtime-bound. Use separate sessions for Python/Node/Bun/Deno/Bash.
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.