Configuration reference

isol8.config.json defines your baseline security, resource, and server behavior. Config resolution order:

./isol8.config.json (current working directory)
~/.isol8/config.json
Built-in defaults

The first existing file is loaded and deep-merged with defaults. You only need to provide the fields you want to override.

Config files are not merged with each other. isol8 loads the first file it finds (./isol8.config.json before ~/.isol8/config.json) and then merges that file with built-in defaults.

How configuration is applied

CLI isol8 run: CLI flags override config defaults.
Library (DockerIsol8): constructor options are authoritative.
Server API (isol8 serve): server config establishes defaults, request options may override them.

For a side-by-side mapping, see Option mapping (CLI, config, API, library).

Full schema shape

Use this as a complete reference template. In real configs, you can provide only the sections you need.

{
  "$schema": "./schema/isol8.config.schema.json",
  "debug": false,
  "maxConcurrent": 10,
  "defaults": {
    "timeoutMs": 30000,
    "memoryLimit": "512m",
    "cpuLimit": 1,
    "network": "none",
    "sandboxSize": "512m",
    "tmpSize": "256m"
  },
  "network": {
    "whitelist": [],
    "blacklist": []
  },
  "cleanup": {
    "autoPrune": true,
    "maxContainerAgeMs": 3600000
  },
  "poolStrategy": "fast",
  "poolSize": { "clean": 1, "dirty": 1 },
  "dependencies": {
    "python": [],
    "node": [],
    "bun": [],
    "deno": [],
    "bash": []
  },
  "remoteCode": {
    "enabled": false,
    "allowedSchemes": ["https"],
    "allowedHosts": [],
    "blockedHosts": ["^localhost$", "^127(?:\\.[0-9]{1,3}){3}$", "^169\\.254\\.169\\.254$"],
    "maxCodeSize": 10485760,
    "fetchTimeoutMs": 30000,
    "requireHash": false,
    "enableCache": true,
    "cacheTtl": 3600
  },
  "security": {
    "seccomp": "strict",
    "customProfilePath": "./seccomp.json"
  },
  "audit": {
    "enabled": false,
    "destination": "filesystem",
    "logDir": "./.isol8_audit",
    "postLogScript": "./scripts/on-audit.sh",
    "trackResources": true,
    "retentionDays": 90,
    "includeCode": false,
    "includeOutput": false
  }
}

Fields

Top-Level

maxConcurrent

number

default:"10"

Maximum number of concurrent container executions. Enforced by a global semaphore in the server.

defaults

Default values for execution options. These are used when a request doesn’t specify its own values.

defaults.timeoutMs

number

default:"30000"

Default execution timeout in milliseconds.

defaults.memoryLimit

string

default:"512m"

Default memory limit. Accepts Docker format: 256m, 512m, 1g.

defaults.cpuLimit

number

default:"1.0"

Default CPU limit as fraction of one core.

defaults.network

string

default:"none"

Default network mode: none, host, or filtered.

defaults.sandboxSize

string

default:"64m"

Default size of the /sandbox tmpfs mount.

defaults.tmpSize

string

default:"64m"

Default size of the /tmp tmpfs mount.

network

Network filtering rules for filtered network mode.

network.whitelist

string[]

default:"[]"

Regex patterns for allowed hostnames. When non-empty, only matching hostnames can be accessed.

network.blacklist

string[]

default:"[]"

Regex patterns for blocked hostnames. Matching hostnames are denied.

cleanup

Server cleanup behavior for stale containers.

cleanup.autoPrune

boolean

default:"true"

Whether the server should periodically clean up old containers.

cleanup.maxContainerAgeMs

number

default:"3600000"

Maximum age of a container in milliseconds before it’s eligible for auto-pruning (default: 1 hour).

dependencies

Packages to bake into custom Docker images when running isol8 setup.

dependencies.python

string[]

default:"[]"

Python packages (pip install).

dependencies.node

string[]

default:"[]"

Node.js packages (npm install -g).

dependencies.bun

string[]

default:"[]"

Bun packages (bun install -g).

dependencies.deno

string[]

default:"[]"

Deno module URLs (deno cache).

dependencies.bash

string[]

default:"[]"

Alpine apk packages.

remoteCode

Controls URL-based source fetching (ExecutionRequest.codeUrl, isol8 run --url).

remoteCode.enabled

boolean

default:"false"

Enable remote code fetching. Disabled by default for security.

remoteCode.allowedSchemes

string[]

default:"[\"https\"]"

Allowed URL schemes. Keep this as https in production.

remoteCode.allowedHosts

string[]

default:"[]"

Hostname regex allowlist. Empty means all hosts are allowed unless blocked.

remoteCode.blockedHosts

string[]

default:"[localhost/private ranges/metadata]"

Hostname regex blocklist used for SSRF protection.

remoteCode.maxCodeSize

number

default:"10485760"

Maximum bytes allowed when fetching remote source code.

remoteCode.fetchTimeoutMs

number

default:"30000"

Timeout for remote source downloads.

remoteCode.requireHash

boolean

default:"false"

Require codeHash on every URL-based execution.

seccomp

Security computing mode profile configuration.

security.seccomp

string

default:"safety"

The seccomp profile to use:

safety: Blocks known dangerous syscalls (mount, ptrace, kernel modules) while allowing standard runtime operations (blacklist approach).
unconfined: Disables seccomp filtering (use with caution).
path/to/profile.json: Path to a custom seccomp profile JSON file.

audit

Audit logging configuration for execution provenance and compliance tracking.

audit.enabled

boolean

default:"false"

Enable audit logging. When enabled, every execution is recorded with metadata including code hash, timestamps, and resource usage.

audit.destination

string

default:"filesystem"

Destination for audit logs. Options:

filesystem or file: Write to log files (default)
stdout: Print to console

audit.logDir

string

Custom directory for audit log files. Defaults to ./.isol8_audit in the current working directory, or the value of ISOL8_AUDIT_DIR environment variable.

audit.postLogScript

string

Path to a script that runs after each audit log entry is written. The script receives the log file path as its first argument. Useful for integrating with external systems like CloudWatch, Splunk, or custom log aggregators.

audit.trackResources

boolean

default:"true"

Track resource usage (CPU percentage, memory MB, network bytes) during execution. Adds slight overhead but useful for billing and monitoring.

audit.retentionDays

number

default:"90"

Number of days to retain audit log files. Files older than this are automatically cleaned up when the AuditLogger initializes.

audit.includeCode

boolean

default:"false"

Include the full source code in audit logs. Disabled by default for privacy. Enable only when you need complete code provenance.

audit.includeOutput

boolean

default:"false"

Include stdout and stderr in audit logs. Disabled by default for privacy. Useful for debugging and compliance scenarios.

Example audit configuration:

{
  "audit": {
    "enabled": false,
    "destination": "filesystem",
    "logDir": "./.isol8_audit",
    "postLogScript": "./scripts/on-audit.sh",
    "trackResources": true,
    "retentionDays": 90,
    "includeCode": false,
    "includeOutput": false
  }
}

Top-level sections

Field	Type	Default	Used by
`debug`	boolean	`false`	CLI/server/engine internal logs
`maxConcurrent`	number	`10`	Global server concurrency cap
`defaults`	object	safe baseline	Engine defaults for runs
`network`	object	empty lists	Filter lists for filtered mode
`cleanup`	object	prune enabled	Server session lifecycle
`poolStrategy`	string	`fast`	Serve-time pool default
`poolSize`	number/object	`{ clean: 1, dirty: 1 }`	Serve-time pool capacity default
`dependencies`	object	`{}`	Custom image setup inputs
`security`	object	strict seccomp	Syscall policy
`audit`	object	disabled	Audit and telemetry logging

`defaults`

These values are applied to every execution unless overridden by CLI flags or request options.

timeoutMs

number

default:"30000"

Hard execution timeout in milliseconds. If execution exceeds this, the container is forcibly killed.

memoryLimit

string

default:"512m"

Container memory limit (e.g., 512m, 1g). Code exceeding this will be OOM killed.

cpuLimit

number

default:"1.0"

CPU shares relative to one core. 1.0 allows full usage of one core.

network

none | host | filtered

default:"none"

Default network egress mode.

none: No network access.
filtered: Access allowed only to whitelisted hosts via proxy.
host: Full host network access (dangerous).

sandboxSize

string

default:"512m"

Size of the writable /sandbox tmpfs mount where code executes.

tmpSize

string

default:"256m"

Size of the /tmp tmpfs mount (mounted noexec).

`network`

Global hostname rules used when network is set to filtered.

whitelist

string[]

default:"[]"

List of regex patterns for allowed hostnames. If non-empty, only matching connections are allowed.

blacklist

string[]

default:"[]"

List of regex patterns for denied hostnames. Matches here are blocked even if they match a whitelist rule.

Keep allow/deny regexes as narrow as possible (exact host patterns when feasible) to reduce accidental data egress.

`cleanup`

Server-side idle session management settings.

cleanup applies to long-running server sessions (isol8 serve). It does not change one-off local CLI runs.

autoPrune

boolean

default:"true"

Enables the background periodic cleanup loop for idle persistent containers.

maxContainerAgeMs

number

default:"3600000"

Idle time threshold (in milliseconds) before a persistent container is removed. Default is 1 hour.

`poolStrategy` and `poolSize`

Server-side pool defaults for engines created by isol8 serve.

These config keys are serve defaults. API calls do not override them per request.

poolStrategy

fast | secure

default:"fast"

Default pool strategy used by server-created engines.

poolSize

number | { clean: number; dirty: number }

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

Default warm pool size used by server-created engines.

`dependencies`

Runtime-specific packages to bake into custom Docker images during isol8 setup.

python

string[]

List of pip packages (e.g., ["numpy", "pandas"]).

node

string[]

List of global npm packages.

bun

string[]

List of global bun packages.

deno

string[]

List of Deno module URLs to pre-cache.

bash

string[]

List of Alpine packages to install via apk.

`security`

System-level security policies.

seccomp

strict | unconfined | custom

default:"strict"

Syscall filtering profile.

strict: Default secure profile.
unconfined: No syscall filtering.
custom: Use profile from customProfilePath.

customProfilePath

string

Absolute path to a custom seccomp profile JSON file. Required if seccomp is custom.

`audit`

Telemetry and audit logging configuration.

enabled

boolean

default:"false"

Master switch to enable audit logging.

destination

string

default:"filesystem"

Where to write logs. Currently supports filesystem or stdout.

logDir

string

default:"./.isol8_audit"

Directory to store audit log files when destination is filesystem.

trackResources

boolean

default:"true"

Whether to record CPU, memory, and network usage metrics for each execution.

retentionDays

number

default:"90"

Number of days to keep audit logs before auto-deletion.

includeCode

boolean

default:"false"

Security Risk. If true, the full source code of every execution is saved in the logs.

includeOutput

boolean

default:"false"

Security Risk. If true, full stdout/stderr capture is saved in the logs.

Enabling audit.includeCode or audit.includeOutput may store sensitive user data. Turn these on only when you have explicit retention and access controls.

Practical baseline configs

Secure default for most workloads

{
  "$schema": "./schema/isol8.config.schema.json",
  "defaults": {
    "network": "none",
    "timeoutMs": 20000,
    "memoryLimit": "512m"
  },
  "cleanup": {
    "autoPrune": true,
    "maxContainerAgeMs": 1800000
  }
}

API-heavy workload with filtered egress and audit logs

{
  "$schema": "./schema/isol8.config.schema.json",
  "maxConcurrent": 25,
  "defaults": {
    "network": "filtered",
    "timeoutMs": 45000,
    "memoryLimit": "1g",
    "cpuLimit": 2
  },
  "network": {
    "whitelist": ["^api\\.openai\\.com$", "^api\\.github\\.com$"],
    "blacklist": [".*\\.internal$"]
  },
  "audit": {
    "enabled": true,
    "destination": "filesystem",
    "logDir": "./.isol8_audit",
    "trackResources": true,
    "retentionDays": 30
  }
}

Validation and inspection

isol8 config
isol8 config --json

Keep $schema in your config for IDE validation/autocomplete.

FAQ

Can I combine project and home config files?

No. isol8 picks the first existing config file by search order, then merges that single file with built-in defaults.

Which values are safe defaults for production start?

Start with defaults.network: "none", conservative timeoutMs/memoryLimit, and audit.enabled: false unless you need logging.

Where should I set package dependencies for setup images?

Use the dependencies section in config (or equivalent flags on isol8 setup) for runtime-specific pre-baked packages.

Troubleshooting quick checks

Config changes not reflected: confirm which file is being loaded (./isol8.config.json takes precedence over ~/.isol8/config.json).
Filtered mode not behaving as expected: validate network.whitelist/network.blacklist regex patterns.
Persistent sessions not being cleaned up: check cleanup.autoPrune and cleanup.maxContainerAgeMs on the server.
Missing audit files: verify audit.enabled, audit.destination, and audit.logDir settings.

Option mapping

See exactly where each option is set across CLI, config, API, and library.

How to CLI

Command-level flags and behavior for run, setup, serve, and cleanup.

Library reference

TypeScript option mapping for DockerIsol8 and RemoteIsol8.

Troubleshooting

Diagnose and fix common runtime and server problems.

Get Started

Core Concepts

Deployment & Ops

Reference

Help

Configuration reference

How configuration is applied

Full schema shape

Fields

Top-Level

defaults

network

cleanup

dependencies

remoteCode

seccomp

audit

Top-level sections

`defaults`

`network`

`cleanup`

`poolStrategy` and `poolSize`

`dependencies`

`security`

`audit`

Practical baseline configs

Secure default for most workloads

API-heavy workload with filtered egress and audit logs

Validation and inspection

FAQ

Troubleshooting quick checks

See also

Option mapping

How to CLI

Library reference

Troubleshooting

Get Started

Core Concepts

Deployment & Ops

Reference

Help

​How configuration is applied

​Full schema shape

​Fields

​Top-Level

​defaults

​network

​cleanup

​dependencies

​remoteCode

​seccomp

​audit

​Top-level sections

​defaults

​network

​cleanup

​poolStrategy and poolSize

​dependencies

​security

​audit

​Practical baseline configs

​Secure default for most workloads

​API-heavy workload with filtered egress and audit logs

​Validation and inspection

​FAQ

​Troubleshooting quick checks

​See also

Option mapping

How to CLI

Library reference

Troubleshooting

How configuration is applied

Full schema shape

Fields

Top-Level

defaults

network

cleanup

dependencies

remoteCode

seccomp

audit

Top-level sections

`defaults`

`network`

`cleanup`

`poolStrategy` and `poolSize`

`dependencies`

`security`

`audit`

Practical baseline configs

Secure default for most workloads

API-heavy workload with filtered egress and audit logs

Validation and inspection

FAQ

Troubleshooting quick checks

See also