Option mapping (CLI, config, API, library)

Use this reference when you need to answer: “where should I set this value?”

CLI flags (isol8 run, isol8 setup, isol8 serve)
Config (isol8.config.json)
API payloads (POST /execute, POST /execute/stream)
Library calls (new DockerIsol8(...), execute(...), start(...))

Precedence rules

Local CLI (`isol8 run`)

CLI flags
isol8.config.json defaults
built-in defaults

Library (`DockerIsol8`)

request-level values (execute({ ... })) for request fields
constructor-level options (new DockerIsol8({ ... })) for engine defaults
built-in defaults

Server API (`isol8 serve`)

request options (where allowed)
server config (isol8.config.json loaded by server)
built-in defaults

For POST /execute, sessionId forces persistent behavior on the server (mode is derived from sessionId there).

Same execution across interfaces

CLI
API
Library

isol8 run \
  -e "print('hello')" \
  --runtime python \
  --timeout 15000 \
  --memory 512m \
  --cpu 1 \
  --net none

{
  "request": {
    "code": "print('hello')",
    "runtime": "python",
    "timeoutMs": 15000
  },
  "options": {
    "memoryLimit": "512m",
    "cpuLimit": 1,
    "network": "none"
  }
}

const engine = new DockerIsol8({
  memoryLimit: "512m",
  cpuLimit: 1,
  network: "none",
});

const result = await engine.execute({
  code: "print('hello')",
  runtime: "python",
  timeoutMs: 15000,
});

Execution request fields (`ExecutionRequest`)

code

string

CLI: -e, --eval, file argument, or piped stdin source.Config: not configurable in isol8.config.json.API: request.code.Library: execute({ code }).

codeUrl

string

CLI: --url, --github, --gist.Config policy: controlled by remoteCode.* (must allow URL fetches).API: request.codeUrl.Library: execute({ codeUrl }).

codeHash

string (sha256)

CLI: --hash.Config policy: remoteCode.requireHash can make hash mandatory.API: request.codeHash.Library: execute({ codeHash }).

allowInsecureCodeUrl

boolean

default:"false"

CLI: --allow-insecure-code-url.Config policy: still constrained by remoteCode.allowedSchemes.API: request.allowInsecureCodeUrl.Library: execute({ allowInsecureCodeUrl: true }).

runtime

'python' | 'node' | 'bun' | 'deno' | 'bash'

CLI: -r, --runtime or extension auto-detection.Config: not set via config.API: request.runtime.Library: execute({ runtime }).

timeoutMs

number

CLI: --timeout <ms>.Config fallback: defaults.timeoutMs.API: request.timeoutMs.Library: execute({ timeoutMs }).

env

Record<string, string>

CLI: no generic env map flag on run (only --secret KEY=VALUE).Config: not set via config.API: request.env.Library: execute({ env }).

fileExtension

string

CLI: no direct override flag.API: request.fileExtension.Library: execute({ fileExtension }).

stdin

string

CLI: --stdin <data> or shell pipe.API: request.stdin.Library: execute({ stdin }).

files

Record<string, string | Buffer>

CLI: not exposed as a run flag.API: request.files.Library: execute({ files }).

outputPaths

string[]

CLI: not exposed as a run flag.API: request.outputPaths.Library: execute({ outputPaths }).

installPackages

string[]

CLI: --install <package> (repeatable).API: request.installPackages.Library: execute({ installPackages }).

metadata

Record<string, string>

CLI: not exposed as a run flag.API: request.metadata.Library: execute({ metadata }).

code and codeUrl are mutually exclusive in the same request.

Execution option fields (`Isol8Options`)

These are engine/runtime behavior options (constructor options locally, options in API requests).

mode

'ephemeral' | 'persistent'

default:"ephemeral"

CLI: --persistent (for local run behavior).Config: no mode key.API: server derives mode from sessionId on /execute.Library: new DockerIsol8({ mode }).

network

'none' | 'host' | 'filtered'

default:"none"

CLI: --net <mode>.Config fallback: defaults.network.API: options.network.Library: network.

networkFilter

{ whitelist: string[]; blacklist: string[] }

CLI: --allow <regex>, --deny <regex> (for filtered mode).Config fallback: network.whitelist, network.blacklist.API: options.networkFilter.Library: networkFilter.

cpuLimit

number

default:"1"

CLI: --cpu <n>.Config fallback: defaults.cpuLimit.API: options.cpuLimit.Library: cpuLimit.

memoryLimit

string

default:"512m"

CLI: --memory <size>.Config fallback: defaults.memoryLimit.API: options.memoryLimit.Library: memoryLimit.

pidsLimit

number

default:"64"

CLI: --pids-limit <n>.Config: no direct key.API: options.pidsLimit.Library: pidsLimit.

readonlyRootFs

boolean

default:"true"

CLI: no direct run flag.Config: no direct key.API: options.readonlyRootFs.Library: readonlyRootFs.

maxOutputSize

number

default:"1048576"

CLI: --max-output <bytes>.Config: no direct key.API: options.maxOutputSize.Library: maxOutputSize.

secrets

Record<string, string>

CLI: --secret KEY=VALUE (repeatable).Config: no direct key.API: options.secrets.Library: secrets.

timeoutMs

number

default:"30000"

CLI: engine default from --timeout per run; config fallback still applies.Config fallback: defaults.timeoutMs.API: options.timeoutMs (engine default for request if request.timeoutMs is omitted).Library: constructor timeoutMs.

image

string

CLI: --image <name>.Config: no direct key.API: options.image.Library: image.

sandboxSize

string

default:"512m"

CLI: --sandbox-size <size>.Config fallback: defaults.sandboxSize.API: options.sandboxSize.Library: sandboxSize.

tmpSize

string

default:"256m"

CLI: --tmp-size <size>.Config fallback: defaults.tmpSize.API: options.tmpSize.Library: tmpSize.

debug

boolean

default:"false"

CLI: global --debug.Config fallback: top-level debug.API: options.debug.Library: debug.

persist

boolean

default:"false"

CLI: --persist.Config: no direct key.API: options.persist.Library: persist.

logNetwork

boolean

default:"false"

CLI: --log-network.Config: no direct key.API: options.logNetwork.Library: logNetwork.

security

SecurityConfig

CLI: no run flag.Config: security.seccomp, security.customProfilePath.API: options.security.Library: security.

audit

AuditConfig

CLI: no run flag.Config: audit.*.API: options.audit.Library: audit.

remoteCode

RemoteCodePolicy

CLI: no direct policy flag (only per-request URL flags).Config: remoteCode.*.API: options.remoteCode.Library: constructor remoteCode.

poolStrategy

'fast' | 'secure'

default:"fast"

CLI: not exposed as a run flag.Config: top-level poolStrategy (applies to isol8 serve defaults only).API: not configurable per request (server uses config default).Library: poolStrategy.

poolSize

number | { clean: number; dirty: number }

default:"{ clean: 1, dirty: 1 }"

CLI: not exposed as a run flag.Config: top-level poolSize (applies to isol8 serve defaults only).API: not configurable per request (server uses config default).Library: poolSize.

dependencies

Isol8Dependencies

CLI: set through isol8 setup inputs (or config), then used at runtime for custom image resolution.Config: dependencies.*.API: options.dependencies.Library: constructor dependencies.

Top-level poolStrategy and poolSize in isol8.config.json define defaults for server-created engines (isol8 serve). Library engine options can override them, but API requests cannot.

Startup options (`start(options?)`)

prewarm

boolean | { runtimes?: Runtime[] }

CLI: not exposed directly.API: not exposed as request field.Library: await engine.start({ prewarm: true }) or await engine.start({ prewarm: { runtimes: ["python"] } }).

Config-only operational keys (`isol8.config.json`)

These keys are config concerns, not per-execution request fields.

maxConcurrent

number

default:"10"

Server/global concurrency cap.CLI: no dedicated run flag.Config: top-level maxConcurrent.API: not a request body field; applied by server.Library: second constructor arg (new DockerIsol8(options, maxConcurrent)).

cleanup.autoPrune

boolean

default:"true"

Idle session pruning in server mode.

cleanup.maxContainerAgeMs

number

default:"3600000"

Idle threshold for server-side pruning.

network.whitelist / network.blacklist

string[]

Global defaults used when filtered networking is active.

poolStrategy

'fast' | 'secure'

default:"fast"

Default pool strategy for engines created by isol8 serve.

poolSize

number | { clean: number; dirty: number }

default:"{ clean: 1, dirty: 1 }"

Default pool size for engines created by isol8 serve.

`isol8 setup` dependency mapping

dependencies.python

string[]

CLI: isol8 setup --python numpy,pandasConfig: dependencies.python

dependencies.node

string[]

CLI: isol8 setup --node lodash,axiosConfig: dependencies.node

dependencies.bun

string[]

CLI: isol8 setup --bun zodConfig: dependencies.bun

dependencies.deno

string[]

CLI: isol8 setup --deno https://deno.land/std@...Config: dependencies.deno

dependencies.bash

string[]

CLI: isol8 setup --bash jq,curlConfig: dependencies.bash

rebuild behavior

flag

CLI: isol8 setup --forceConfig: no equivalent key

FAQ

Can I set global pool defaults for `isol8 serve`?

Yes. Set top-level poolStrategy and poolSize in isol8.config.json. They apply as server defaults for API execution.

What wins if both request timeout and option timeout are set?

request.timeoutMs wins for that call. options.timeoutMs is the fallback default for requests that omit timeout.

How do I force persistent behavior on the server API?

Send a sessionId on POST /execute. The server uses that to set persistent mode for the session.

Can I use `codeUrl` without changing config?

Only if remote code policy allows it. If remoteCode.enabled is false, URL-based execution is rejected.

Troubleshooting quick checks

Request rejected for URL execution: verify remoteCode.enabled, host/scheme policy, and hash requirements in /remote-code.
Unexpected runtime settings: run isol8 config --json and confirm effective defaults.
Filter rules not taking effect: check both request-level networkFilter and global network.* defaults.
Persistent session not behaving as expected over API: confirm sessionId is present and stable across calls.

Configuration reference

Full schema, defaults, and merge behavior for isol8.config.json.

How to CLI

Flag-level behavior for run, setup, serve, config, and cleanup.

Library reference

Complete TypeScript API contracts and lifecycle methods.

Remote code URLs

URL execution policy, hash verification, and SSRF controls.

Get Started

Core Concepts

Deployment & Ops

Reference

Help

Option mapping (CLI, config, API, library)

Precedence rules

Local CLI (`isol8 run`)

Library (`DockerIsol8`)

Server API (`isol8 serve`)

Same execution across interfaces

Execution request fields (`ExecutionRequest`)

Execution option fields (`Isol8Options`)

Startup options (`start(options?)`)

Config-only operational keys (`isol8.config.json`)

`isol8 setup` dependency mapping

FAQ

Troubleshooting quick checks

Configuration reference

How to CLI

Library reference

Remote code URLs

Get Started

Core Concepts

Deployment & Ops

Reference

Help

​Precedence rules

​Local CLI (isol8 run)

​Library (DockerIsol8)

​Server API (isol8 serve)

​Same execution across interfaces

​Execution request fields (ExecutionRequest)

​Execution option fields (Isol8Options)

​Startup options (start(options?))

​Config-only operational keys (isol8.config.json)

​isol8 setup dependency mapping

​FAQ

​Troubleshooting quick checks

​Related pages

Configuration reference

How to CLI

Library reference

Remote code URLs

Precedence rules

Local CLI (`isol8 run`)

Library (`DockerIsol8`)

Server API (`isol8 serve`)

Same execution across interfaces

Execution request fields (`ExecutionRequest`)

Execution option fields (`Isol8Options`)

Startup options (`start(options?)`)

Config-only operational keys (`isol8.config.json`)

`isol8 setup` dependency mapping

FAQ

Troubleshooting quick checks

Related pages