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`)

string

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

string

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

string (sha256)

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

boolean

default:"false"

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

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

number

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

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 }).

string

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

string

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

Record<string, string | Buffer>

CLI: --files <dir> (recursively injects a directory into /sandbox, primarily for agent runtime).API: request.files.Library: execute({ files }).

string[]

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

string[]

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

string

CLI run: --setup <command> (repeatable; concatenated with newlines; reads file if path exists).CLI build: --setup <command> (repeatable; baked into the custom image and runs before every execution).Config: prebuiltImages[].setupScript (image-level setup, runs before request-level setup).API: request.setupScript.Library: execute({ setupScript }).When both an image-level and request-level setup script exist, the image-level script runs first.

string

default:"/sandbox"

CLI: --workdir <path>.API: request.workdir.Library: execute({ workdir }).

string

Extra flags passed to the pi coding agent (e.g. --model claude-sonnet-4-20250514 --thinking). Only used when runtime is "agent".CLI: --agent-flags <flags>.API: request.agentFlags.Library: execute({ agentFlags }).

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).

'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 }).

'none' | 'host' | 'filtered'

default:"none"

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

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

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

number

default:"1"

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

string

default:"512m"

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

number

default:"64"

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

boolean

default:"true"

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

number

default:"1048576"

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

Record<string, string>

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

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.

string

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

string

default:"512m"

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

string

default:"256m"

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

boolean

default:"false"

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

boolean

default:"false"

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

boolean

default:"false"

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

SecurityConfig

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

AuditConfig

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

RemoteCodePolicy

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

'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.

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.

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?)`)

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.

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)).

boolean

default:"true"

Idle session pruning in server mode.

number

default:"3600000"

Idle threshold for server-side pruning.

string[]

Global defaults used when filtered networking is active.

'fast' | 'secure'

default:"fast"

Default pool strategy for engines created by isol8 serve.

number | { clean: number; dirty: number }

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

Default pool size for engines created by isol8 serve.

`isol8 setup` dependency mapping

string[]

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

string[]

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

string[]

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

string[]

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

string[]

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

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

​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