Skip to main content
Migration: CLI is now @isol8/cli (installed as isol8 command).
This page is a flag-by-flag reference for the isol8 CLI.

​
Global option

​
--debug
flag
Enables debug logs for CLI internals and engine operations.

​
isol8 run

isol8 run [file] [options]
isol8 run streams output by default. Use --no-stream only when you want buffered output after execution completes.

​
Input and runtime flags

​
[file]
argument
Script file path. Runtime is auto-detected from extension unless --runtime is provided.
​
-e, --eval <code>
string
Inline code to execute.
​
-r, --runtime <name>
python | node | bun | deno | bash
Force runtime instead of extension-based detection.
​
--stdin <data>
string
Explicit stdin payload for the execution process.

​
Security and resource flags

​
--net <mode>
none | host | filtered
default:"none"
Sets the network egress mode for the container.
  • none: Blocks all network access (default).
  • filtered: Routes traffic through a proxy with whitelist/blacklist enforcement.
  • host: Allows full host network access (use with extreme caution).
If --install is used and --net is not explicitly provided, CLI automatically uses filtered.
--net host gives untrusted code full outbound network access. Prefer none (default) or filtered for most workloads.
​
--allow <regex>
repeatable
Adds a regex pattern to the whitelist in filtered mode. Only hostnames matching at least one allow pattern will be permitted.
​
--deny <regex>
repeatable
Blacklist pattern for filtered mode.
​
--timeout <ms>
number
Timeout in milliseconds for package installation and code execution.
​
--memory <size>
string
Memory limit (512m, 1g, etc.).
​
--cpu <limit>
number
CPU limit as fraction/cores.
​
--pids-limit <n>
number
default:"64"
Maximum number of processes.
​
--max-output <bytes>
number
default:"1048576"
Maximum output size before truncation.
​
--sandbox-size <size>
string
default:"512m"
/sandbox tmpfs size.
​
--tmp-size <size>
string
default:"256m"
/tmp tmpfs size.

​
State and behavior flags

​
--persistent
flag
Use persistent mode (mode=persistent).
​
--persist
flag
Keep container alive after execution finishes.
​
--no-stream
flag
Disable realtime streaming and use buffered execute() path.
​
--install <package>
repeatable
Install package before execution.In filtered mode, CLI automatically merges default runtime package registry hosts into the allowlist. Explicit --net is never overridden.
​
--secret <KEY=VALUE>
repeatable
Inject secret env vars and mask values in output.
​
--out <file>
string
Write stdout to local file.
​
--image <name>
string
Override runtime image.
​
--log-network
flag
Enable network request logs in results (filtered mode).

​
Remote execution flags

​
--host <url>
string
Execute against remote isol8 serve instance.
​
--key <key>
string
API key for remote execution (ISOL8_API_KEY fallback).

​
Examples

# Inline Python
isol8 run \
  -e "print(2 ** 10)" \
  --runtime python

# Filtered networking
isol8 run \
  task.py \
  --net filtered \
  --allow "^api\.openai\.com$"

# Persistent mode
isol8 run \
  --persistent \
  -e "x = 42" \
  --runtime python

# Remote execution
isol8 run \
  script.py \
  --host http://localhost:3000 \
  --key my-key

​
isol8 setup

isol8 setup [options]

​
@isol8/cli setup

@isol8/cli setup [options]
​
--python <a,b,c>
string
Comma-separated Python dependencies for custom image.
​
--node <a,b,c>
string
Comma-separated Node dependencies for custom image.
​
--bun <a,b,c>
string
Comma-separated Bun dependencies for custom image.
​
--deno <a,b,c>
string
Comma-separated Deno modules to pre-cache.
​
--bash <a,b,c>
string
Comma-separated apk packages for bash runtime.
​
--force
flag
Force rebuild even when hashes indicate cache hit.

​
isol8 serve

isol8 serve --key <api-key> [options]
​
-p, --port <port>
number
default:"3000"
Port for server listener. Resolution order is --port > ISOL8_PORT > PORT > 3000. If the selected port is occupied, the CLI prompts to choose a different port or automatically finds an available one.
​
-k, --key <key>
string
API key for bearer auth. If omitted, ISOL8_API_KEY environment variable is used.
​
--update
flag
Force re-download of standalone server binary.
​
--debug
flag
Enable debug logs for server internals.
For full server behavior and endpoints, see the Server docs tab: Server overview and Server routes.

​
isol8 build

isol8 build --base <runtime> --install <package> [options]
​
--base <runtime>
python | node | bun | deno | bash
Runtime base image to extend.
​
--install <package>
repeatable
Package to bake into the image. Supports repeated flags and comma-separated values.
​
--tag <name>
string
Optional alias tag (for example my-registry/ml-image:latest) applied to the built hashed image.
​
--force
flag
Force rebuild even if current inputs resolve to an existing up-to-date image.

​
isol8 config

isol8 config [options]

​
isol8 cleanup

isol8 cleanup [options]
​
--json
flag
Print resolved config as JSON.

​
isol8 cleanup

isol8 cleanup [options]
​
--force
flag
Skip confirmation prompt.
​
--images
flag
Also remove isol8 Docker images.

​
FAQ

--persistent sets execution mode to persistent (reuses container state across runs). --persist keeps the container alive after a run for inspection/debugging.
No. isol8 serve accepts --key, but it can also read the API key from ISOL8_API_KEY.
Streaming is the default behavior. Use --no-stream if you want buffered output only after the run completes.

​
Troubleshooting quick checks

  • [ERR] API key required on serve or remote run: pass --key or set ISOL8_API_KEY.
  • Runtime not detected from file extension: pass --runtime <name> explicitly.
  • No output appears while command runs: check if --no-stream is enabled.
  • Filtered mode still blocks host: verify --allow regex matches hostname exactly.

​
See also

Option mapping

Map each CLI flag to config, API, and library equivalents.

Configuration reference

Full config schema, defaults, and precedence rules.

Troubleshooting

Diagnose and fix common CLI/runtime failures quickly.