Skip to main content
isol8 loads configuration from a JSON file. The config sets defaults for all executions and controls server behavior.

​
Config File Location

isol8 looks for config in this order (first found wins):
  1. ./isol8.config.json (current working directory)
  2. ~/.isol8/config.json (home directory)
If no config file is found, built-in defaults are used. Partial configs are deep-merged with defaults.

​
Full Schema

{
  "$schema": "./schema/isol8.config.schema.json",
  "maxConcurrent": 10,
  "defaults": {
    "timeoutMs": 30000,
    "memoryLimit": "512m",
    "cpuLimit": 1.0,
    "network": "none",
    "sandboxSize": "64m",
    "tmpSize": "64m"
  },
  "network": {
    "whitelist": [],
    "blacklist": []
  },
  "cleanup": {
    "autoPrune": true,
    "maxContainerAgeMs": 3600000
  },
  "dependencies": {
    "python": ["numpy", "pandas"],
    "node": ["lodash"],
    "bun": [],
    "deno": [],
    "bash": ["jq", "curl"]
  }
}

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

​
JSON Schema

A JSON Schema file is available at schema/isol8.config.schema.json. Reference it in your config file for editor autocompletion: 
{
  "$schema": "./schema/isol8.config.schema.json"
}

​
Viewing Resolved Config

Use the CLI to see the fully resolved configuration: 
isol8 config
isol8 config --json