Configuration reference

Detailed reference for isol8.config.json, merge behavior, defaults, and operational guidance for each section.

isol8.config.json defines your baseline security, resource, and server behavior.

Config resolution order:

1. ./isol8.config.json (current working directory)
2. ~/.isol8/config.json
3. 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 },
  "prebuiltImages": [
    { "tag": "my-python-ml", "runtime": "python", "installPackages": ["numpy", "pandas"] }
  ],
  "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
prebuiltImages	array	[]	Custom image definitions for auto-build
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.

prebuiltImages

Custom Docker images to auto-build when the server starts or when running isol8 setup. Each entry defines a named image with a runtime, list of packages, and an optional setup script.

prebuiltImages · array · default: "[]"

List of prebuilt image configurations. Each entry has:

• tag (string, required): Docker image tag (e.g. my-python-ml).
• runtime (string, required): Base runtime (python, node, bun, deno, bash).
• installPackages (string[], required): Packages to bake into the image.
• setupScript (string, optional): Shell script that runs automatically before every execution using this image. When a request also provides its own setupScript, the image-level script runs first.

Example:

{
  "prebuiltImages": [
    { "tag": "my-python-ml", "runtime": "python", "installPackages": ["numpy", "pandas", "scikit-learn"] },
    { "tag": "my-node-api", "runtime": "node", "installPackages": ["express", "lodash"] },
    {
      "tag": "my-python-dev",
      "runtime": "python",
      "installPackages": ["pytest"],
      "setupScript": "pip install -e /sandbox/mylib"
    }
  ]
}

On server startup, each image is checked locally. Missing images are built automatically before the server begins accepting requests. The CLI isol8 setup command also builds these images.

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

Command

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 define prebuilt images?

Use the prebuiltImages array in config. Each entry specifies a tag, runtime, and installPackages. Run isol8 setup or start the server to auto-build them.

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.

See also

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.