> ## Documentation Index
> Fetch the complete documentation index at: https://isol8.notdhruv.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  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.
</Info>

## 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)](/option-mapping).

## Full schema shape

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

```json theme={null}
{
  "$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

<ResponseField name="maxConcurrent" type="number" default="10">
  Maximum number of concurrent container executions. Enforced by a global semaphore in the server.
</ResponseField>

### defaults

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

<ResponseField name="defaults.timeoutMs" type="number" default="30000">
  Default execution timeout in milliseconds.
</ResponseField>

<ResponseField name="defaults.memoryLimit" type="string" default="512m">
  Default memory limit. Accepts Docker format: `256m`, `512m`, `1g`.
</ResponseField>

<ResponseField name="defaults.cpuLimit" type="number" default="1.0">
  Default CPU limit as fraction of one core.
</ResponseField>

<ResponseField name="defaults.network" type="string" default="none">
  Default network mode: `none`, `host`, or `filtered`.
</ResponseField>

<ResponseField name="defaults.sandboxSize" type="string" default="64m">
  Default size of the `/sandbox` tmpfs mount.
</ResponseField>

<ResponseField name="defaults.tmpSize" type="string" default="64m">
  Default size of the `/tmp` tmpfs mount.
</ResponseField>

### network

Network filtering rules for `filtered` network mode.

<ResponseField name="network.whitelist" type="string[]" default="[]">
  Regex patterns for allowed hostnames. When non-empty, only matching hostnames can be accessed.
</ResponseField>

<ResponseField name="network.blacklist" type="string[]" default="[]">
  Regex patterns for blocked hostnames. Matching hostnames are denied.
</ResponseField>

### cleanup

Server cleanup behavior for stale containers.

<ResponseField name="cleanup.autoPrune" type="boolean" default="true">
  Whether the server should periodically clean up old containers.
</ResponseField>

<ResponseField name="cleanup.maxContainerAgeMs" type="number" default="3600000">
  Maximum age of a container in milliseconds before it's eligible for auto-pruning (default: 1 hour).
</ResponseField>

### dependencies

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

<ResponseField name="dependencies.python" type="string[]" default="[]">
  Python packages (pip install).
</ResponseField>

<ResponseField name="dependencies.node" type="string[]" default="[]">
  Node.js packages (npm install -g).
</ResponseField>

<ResponseField name="dependencies.bun" type="string[]" default="[]">
  Bun packages (bun install -g).
</ResponseField>

<ResponseField name="dependencies.deno" type="string[]" default="[]">
  Deno module URLs (deno cache).
</ResponseField>

<ResponseField name="dependencies.bash" type="string[]" default="[]">
  Alpine apk packages.
</ResponseField>

### remoteCode

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

<ResponseField name="remoteCode.enabled" type="boolean" default="false">
  Enable remote code fetching. Disabled by default for security.
</ResponseField>

<ResponseField name="remoteCode.allowedSchemes" type="string[]" default="[&#x22;https&#x22;]">
  Allowed URL schemes. Keep this as `https` in production.
</ResponseField>

<ResponseField name="remoteCode.allowedHosts" type="string[]" default="[]">
  Hostname regex allowlist. Empty means all hosts are allowed unless blocked.
</ResponseField>

<ResponseField name="remoteCode.blockedHosts" type="string[]" default="[localhost/private ranges/metadata]">
  Hostname regex blocklist used for SSRF protection.
</ResponseField>

<ResponseField name="remoteCode.maxCodeSize" type="number" default="10485760">
  Maximum bytes allowed when fetching remote source code.
</ResponseField>

<ResponseField name="remoteCode.fetchTimeoutMs" type="number" default="30000">
  Timeout for remote source downloads.
</ResponseField>

<ResponseField name="remoteCode.requireHash" type="boolean" default="false">
  Require `codeHash` on every URL-based execution.
</ResponseField>

### seccomp

Security computing mode profile configuration.

<ResponseField name="security.seccomp" type="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.
</ResponseField>

### audit

Audit logging configuration for execution provenance and compliance tracking.

<ResponseField name="audit.enabled" type="boolean" default="false">
  Enable audit logging. When enabled, every execution is recorded with metadata including code hash, timestamps, and resource usage.
</ResponseField>

<ResponseField name="audit.destination" type="string" default="filesystem">
  Destination for audit logs. Options:

  * `filesystem` or `file`: Write to log files (default)
  * `stdout`: Print to console
</ResponseField>

<ResponseField name="audit.logDir" type="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.
</ResponseField>

<ResponseField name="audit.postLogScript" type="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.
</ResponseField>

<ResponseField name="audit.trackResources" type="boolean" default="true">
  Track resource usage (CPU percentage, memory MB, network bytes) during execution. Adds slight overhead but useful for billing and monitoring.
</ResponseField>

<ResponseField name="audit.retentionDays" type="number" default="90">
  Number of days to retain audit log files. Files older than this are automatically cleaned up when the AuditLogger initializes.
</ResponseField>

<ResponseField name="audit.includeCode" type="boolean" default="false">
  Include the full source code in audit logs. Disabled by default for privacy. Enable only when you need complete code provenance.
</ResponseField>

<ResponseField name="audit.includeOutput" type="boolean" default="false">
  Include stdout and stderr in audit logs. Disabled by default for privacy. Useful for debugging and compliance scenarios.
</ResponseField>

**Example audit configuration:**

```json theme={null}
{
  "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.

<ResponseField name="timeoutMs" type="number" default="30000">
  Hard execution timeout in milliseconds. If execution exceeds this, the container is forcibly killed.
</ResponseField>

<ResponseField name="memoryLimit" type="string" default="512m">
  Container memory limit (e.g., `512m`, `1g`). Code exceeding this will be OOM killed.
</ResponseField>

<ResponseField name="cpuLimit" type="number" default="1.0">
  CPU shares relative to one core. `1.0` allows full usage of one core.
</ResponseField>

<ResponseField name="network" type="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).
</ResponseField>

<ResponseField name="sandboxSize" type="string" default="512m">
  Size of the writable `/sandbox` tmpfs mount where code executes.
</ResponseField>

<ResponseField name="tmpSize" type="string" default="256m">
  Size of the `/tmp` tmpfs mount (mounted `noexec`).
</ResponseField>

## `network`

Global hostname rules used when `network` is set to `filtered`.

<ResponseField name="whitelist" type="string[]" default="[]">
  List of regex patterns for allowed hostnames. If non-empty, *only* matching connections are allowed.
</ResponseField>

<ResponseField name="blacklist" type="string[]" default="[]">
  List of regex patterns for denied hostnames. Matches here are blocked even if they match a whitelist rule.
</ResponseField>

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

## `cleanup`

Server-side idle session management settings.

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

<ResponseField name="autoPrune" type="boolean" default="true">
  Enables the background periodic cleanup loop for idle persistent containers.
</ResponseField>

<ResponseField name="maxContainerAgeMs" type="number" default="3600000">
  Idle time threshold (in milliseconds) before a persistent container is removed. Default is 1 hour.
</ResponseField>

## `poolStrategy` and `poolSize`

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

<Note>
  These config keys are serve defaults. API calls do not override them per request.
</Note>

<ResponseField name="poolStrategy" type="fast | secure" default="fast">
  Default pool strategy used by server-created engines.
</ResponseField>

<ResponseField name="poolSize" type="number | { clean: number; dirty: number }" default="{ clean: 1, dirty: 1 }">
  Default warm pool size used by server-created engines.
</ResponseField>

## `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.

<ResponseField name="prebuiltImages" type="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.
</ResponseField>

**Example:**

```json theme={null}
{
  "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"
    }
  ]
}
```

<Info>
  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.
</Info>

## `security`

System-level security policies.

<ResponseField name="seccomp" type="strict | unconfined | custom" default="strict">
  Syscall filtering profile.

  * `strict`: Default secure profile.
  * `unconfined`: No syscall filtering.
  * `custom`: Use profile from `customProfilePath`.
</ResponseField>

<ResponseField name="customProfilePath" type="string">
  Absolute path to a custom seccomp profile JSON file. Required if `seccomp` is `custom`.
</ResponseField>

## `audit`

Telemetry and audit logging configuration.

<ResponseField name="enabled" type="boolean" default="false">
  Master switch to enable audit logging.
</ResponseField>

<ResponseField name="destination" type="string" default="filesystem">
  Where to write logs. Currently supports `filesystem` or `stdout`.
</ResponseField>

<ResponseField name="logDir" type="string" default="./.isol8_audit">
  Directory to store audit log files when destination is `filesystem`.
</ResponseField>

<ResponseField name="trackResources" type="boolean" default="true">
  Whether to record CPU, memory, and network usage metrics for each execution.
</ResponseField>

<ResponseField name="retentionDays" type="number" default="90">
  Number of days to keep audit logs before auto-deletion.
</ResponseField>

<ResponseField name="includeCode" type="boolean" default="false">
  **Security Risk**. If true, the full source code of every execution is saved in the logs.
</ResponseField>

<ResponseField name="includeOutput" type="boolean" default="false">
  **Security Risk**. If true, full stdout/stderr capture is saved in the logs.
</ResponseField>

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

## Practical baseline configs

### Secure default for most workloads

```json theme={null}
{
  "$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

```json theme={null}
{
  "$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

<CodeGroup>
  ```bash Command theme={null}
  isol8 config
  isol8 config --json
  ```

  ```text Expected output theme={null}
  Prints effective resolved config (human-readable or JSON), including defaults and overrides from the selected config file.
  ```
</CodeGroup>

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

## FAQ

<Accordion title="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.
</Accordion>

<Accordion title="Which values are safe defaults for production start?">
  Start with `defaults.network: "none"`, conservative `timeoutMs`/`memoryLimit`, and `audit.enabled: false` unless you need logging.
</Accordion>

<Accordion title="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.
</Accordion>

## 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

<CardGroup cols={2}>
  <Card title="Option mapping" icon="sliders" href="/option-mapping">
    See exactly where each option is set across CLI, config, API, and library.
  </Card>

  <Card title="How to CLI" icon="terminal" href="/cli">
    Command-level flags and behavior for `run`, `setup`, `serve`, and cleanup.
  </Card>

  <Card title="Library reference" icon="book-open" href="/library">
    TypeScript option mapping for `DockerIsol8` and `RemoteIsol8`.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Diagnose and fix common runtime and server problems.
  </Card>
</CardGroup>