> ## Documentation Index
> Fetch the complete documentation index at: https://isol8.notdhruv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash theme={null}
# 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-..."
```
```typescript theme={null}
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",
});
```
```json theme={null}
{
"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 ` | `python3 ` |
| Node | `node -e ` | `node ` |
| Bun | `bun -e ` | `bun run ` |
| Deno | Engine writes file first | `deno run --allow-read=/sandbox,/tmp --allow-write=/sandbox,/tmp --allow-env --allow-net ` |
| Bash | `bash -c ` | `bash ` |
| Agent | `bash -c "pi --no-session [agentFlags] -p "` | 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](https://github.com/mariozechner/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 ` 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
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/Agent.
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.
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
Request lifecycle, modes, I/O, streaming, and resource limits.
Dependency strategy: runtime installs vs pre-baked custom images.
Exact CLI/config/API/library mapping for runtime and options.
Fix common runtime and environment issues.