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

# FAQ

> Detailed answers to common isol8 questions across execution modes, sessions, networking, runtimes, limits, remote API, and config behavior.

This FAQ is grounded in current code behavior (`src/`, `src/types.ts`, and `schema/isol8.config.schema.json`).

## Core behavior and defaults

<AccordionGroup>
  <Accordion title="What are the default execution settings if I do not configure anything?">
    Defaults are conservative:

    * `timeoutMs: 30000`
    * `memoryLimit: "512m"`
    * `cpuLimit: 1`
    * `network: "none"`
    * `sandboxSize: "512m"`
    * `tmpSize: "256m"`
    * `maxConcurrent: 10`
  </Accordion>

  <Accordion title="Where does isol8 load config from?">
    First match wins:

    1. `./isol8.config.json` in current working directory
    2. `~/.isol8/config.json`
    3. built-in defaults
  </Accordion>

  <Accordion title="Does my config fully replace defaults?">
    No. User config is deep-merged with defaults. You can override only the keys you need.
  </Accordion>

  <Accordion title="How can I inspect the effective configuration?">
    Use:

    ```bash theme={null}
    isol8 config --json
    ```

    This is the best way to confirm what values are actually active.
  </Accordion>

  <Accordion title="What wins if the same setting is provided in config and request/CLI?">
    Request/CLI values override config defaults for that execution. Config remains the baseline.
  </Accordion>

  <Accordion title="Does isol8 require Bun to run CLI and remote server?">
    Not always. The built CLI can run under Node, and `isol8 serve` in built mode downloads a standalone server binary that embeds Bun.
  </Accordion>
</AccordionGroup>

## Setup and build behavior

<AccordionGroup>
  <Accordion title="What does `isol8 setup` actually do?">
    It checks Docker connectivity, builds base runtime images, and can build custom images with configured dependencies.
  </Accordion>

  <Accordion title="When should I rebuild images with `--force`?">
    Use `--force` after Dockerfile/runtime dependency changes, or when troubleshooting stale image behavior.
  </Accordion>

  <Accordion title="Why does `isol8 serve` ask about updating binaries?">
    Built CLI checks standalone server binary version against CLI version. If mismatched, it prompts to update.
  </Accordion>

  <Accordion title="Can I force standalone server binary refresh?">
    Yes:

    ```bash theme={null}
    isol8 serve --update
    ```
  </Accordion>

  <Accordion title="What if my platform is unsupported for standalone server binary?">
    CLI fails with an unsupported platform error for unknown OS/arch combinations.
  </Accordion>
</AccordionGroup>

## Execution modes, lifecycle, and persistence

<AccordionGroup>
  <Accordion title="What is the difference between `--persistent` and `--persist`?">
    * `--persistent`: selects persistent execution mode (reuse one container state for that engine/session).
    * `--persist`: keep container(s) running after execution for inspection/debugging.
      They control different concerns and can be combined.
  </Accordion>

  <Accordion title="Does `--persistent` on CLI keep state across multiple separate `isol8 run` commands?">
    Not by default. Each CLI invocation creates a new process and a new engine lifecycle, then stops it in `finally`.
    For true cross-call persistence, use remote API/library with a stable `sessionId`.
  </Accordion>

  <Accordion title="Can I switch runtime inside one persistent container (Python -> Node)?">
    No. Persistent containers are runtime-bound. Switching runtime in the same persistent engine throws an error.
  </Accordion>

  <Accordion title="When does a persistent session get deleted on remote server?">
    * explicit `DELETE /session/:id`
    * auto-prune if enabled and session is idle past `cleanup.maxContainerAgeMs`
  </Accordion>

  <Accordion title="Does auto-prune delete active sessions mid-execution?">
    No. Active sessions are skipped while executing (`isActive` check).
  </Accordion>
</AccordionGroup>

## Streaming and output behavior

<AccordionGroup>
  <Accordion title="Is streaming enabled by default in CLI?">
    Yes. `isol8 run` streams output by default. Use `--no-stream` to wait for final result.
  </Accordion>

  <Accordion title="What event types are emitted in streaming mode?">
    `stdout`, `stderr`, `exit`, `error`.
  </Accordion>

  <Accordion title="Can I stream and still save final stdout to `--out` file in one command?">
    `--out` writing is part of non-streaming result handling path. If you need predictable captured output file, use `--no-stream`.
  </Accordion>

  <Accordion title="Why was my output truncated?">
    Output is capped by `maxOutputSize` (default `1MB`). If exceeded, output is truncated and marked.
  </Accordion>

  <Accordion title="Does secret masking apply in streamed output too?">
    Yes. Secret value masking is applied in both collected output and streaming output pipelines.
  </Accordion>

  <Accordion title="Are file contents also auto-masked like stdout/stderr?">
    No. Masking is text-output masking. Retrieved file contents are returned as-is.
  </Accordion>
</AccordionGroup>

## Networking and security

<AccordionGroup>
  <Accordion title="What is the difference between `none`, `filtered`, and `host` network modes?">
    * `none`: outbound network blocked (default, safest)
    * `filtered`: proxy + hostname policy + iptables enforcement
    * `host`: unrestricted host networking (use only for trusted workloads)
  </Accordion>

  <Accordion title="In filtered mode, which wins: allowlist or denylist?">
    Denylist/blacklist wins. Matching blocked hosts are denied even if also allowed by whitelist.
  </Accordion>

  <Accordion title="Why do my filtered requests get blocked even with an allow pattern?">
    Common causes:

    * regex mismatch against actual hostname
    * blacklist also matches
    * request host differs from what you expected
  </Accordion>

  <Accordion title="Does filtered mode rely only on proxy env vars?">
    No. It also applies in-container iptables rules so uid 100 traffic is restricted to proxy path.
  </Accordion>

  <Accordion title="What does seccomp `strict`/`unconfined`/`custom` mean?">
    * `strict`: apply the default built-in seccomp profile
    * `unconfined`: no seccomp filter
    * `custom`: use profile from `security.customProfilePath`
  </Accordion>

  <Accordion title="What happens if the default seccomp profile cannot be loaded?">
    Execution fails instead of running without seccomp. In standalone server binary mode, isol8 uses an embedded default profile when on-disk profile files are unavailable.
  </Accordion>

  <Accordion title="Can I configure seccomp from `isol8 run` flags directly?">
    No direct `run` seccomp flag currently. Use config (`security.*`) or API/library `options.security`.
  </Accordion>

  <Accordion title="Why do I not see network logs even with `--log-network`?">
    Network logs require filtered mode. `--log-network` only works when network mode is `filtered`.
  </Accordion>

  <Accordion title="What happens when I use `--install` without `--net`?">
    CLI auto-selects `filtered` networking for that run and adds runtime-default package registry hosts to the allowlist (for example PyPI or npm registry hosts).
  </Accordion>

  <Accordion title="If I pass `--net` explicitly with `--install`, is it overridden?">
    No. Explicit `--net` is preserved. Only the allowlist is merged when effective mode is `filtered`.
  </Accordion>

  <Accordion title="Does `--timeout` include package install time when using `--install`?">
    Yes. The timeout now applies to both package installation and code execution, so blocked or stalled installs fail instead of hanging indefinitely.
  </Accordion>
</AccordionGroup>

## Runtimes, files, and package installs

<AccordionGroup>
  <Accordion title="How is runtime auto-detected from filename?">
    Runtime registry maps extensions to adapters. Examples:

    * `.py` -> python
    * `.mjs` / `.js` / `.cjs` -> node
    * `.ts` -> bun
    * `.mts` -> deno
    * `.sh` -> bash
  </Accordion>

  <Accordion title="Why does `.ts` default to Bun and not Deno?">
    Bun is mapped to `.ts`. Deno uses `.mts` to avoid extension collisions.
  </Accordion>

  <Accordion title="Can Deno run inline `-e` code in current adapter?">
    Deno adapter currently requires a file path and does not support inline command path.
  </Accordion>

  <Accordion title="How do I choose ESM vs CJS for Node?">
    Use `fileExtension` (library/API) or file suffix in CLI input:

    * `.mjs` for ESM
    * `.cjs` for CJS
      Node adapter supports both.
  </Accordion>

  <Accordion title="Where are runtime package installs written?">
    Package installs are placed under `/sandbox` user directories (e.g. Python user base, npm/bun globals), not `/tmp`.
  </Accordion>

  <Accordion title="Can I inject files and retrieve files in one execution?">
    Yes in API/library via `files` and `outputPaths`. CLI currently does not expose full generic `files/outputPaths` request fields.
  </Accordion>

  <Accordion title="Why does `putFile`/`getFile` fail with 'No active container' in local engine?">
    Local file APIs require persistent mode and at least one execution to create/activate the container.
  </Accordion>

  <Accordion title="Why not install packages in `/tmp`?">
    `/tmp` is mounted `noexec`. Native extensions often require executable paths, so `/sandbox` is used.
  </Accordion>

  <Accordion title="Why do package names sometimes fail validation?">
    install package names are validated to reduce injection risk. Invalid characters are rejected.
  </Accordion>
</AccordionGroup>

## Resource limits and performance

<AccordionGroup>
  <Accordion title="What does `cpuLimit: 1` mean?">
    One full CPU core worth of quota (`NanoCpus` mapping inside Docker host config).
  </Accordion>

  <Accordion title="What happens on timeout?">
    Command is wrapped with timeout enforcement and will be terminated when limit is exceeded.
  </Accordion>

  <Accordion title="What memory format is accepted for limits?">
    Formats like `512m`, `1g`, `256k`, or raw bytes are accepted. Invalid format throws a parse error.
  </Accordion>

  <Accordion title="How should I choose sandbox and tmp sizes?">
    * increase `sandboxSize` for larger user files/package footprints
    * keep `tmpSize` sufficient for temporary build/runtime caches
  </Accordion>

  <Accordion title="What do `poolStrategy` and `poolSize` control?">
    * `poolStrategy: "fast"` (default): clean/dirty pools with background cleanup
    * `poolStrategy: "secure"`: cleanup in acquire path
    * `poolSize`: warm pool capacity
  </Accordion>

  <Accordion title="How does `poolSize` relate to `maxConcurrent`?">
    * `maxConcurrent` limits total parallel executions (semaphore).
    * `poolSize` controls warm container availability per runtime image.
    * If concurrency exceeds warm capacity for a runtime, requests can still run but may pay cold create/start latency.
  </Accordion>

  <Accordion title="Does background pool cleanup matter for one-shot CLI runs?">
    Usually not much. One-shot CLI exits and calls `engine.stop()`, which drains/removes pool containers. Background cleaning is most useful for long-lived processes (`serve`, long-running app instance).
  </Accordion>
</AccordionGroup>

## Remote server and API

<AccordionGroup>
  <Accordion title="Why do I get 401 vs 403 from remote server?">
    * `401`: missing `Authorization` header
    * `403`: header present but API key invalid
  </Accordion>

  <Accordion title="Does `/health` require auth?">
    No. `/health` is intentionally unauthenticated for liveness checks.
  </Accordion>

  <Accordion title="Do file upload/download APIs require sessionId?">
    Yes. File operations are tied to persistent sessions. Without `sessionId`, they fail.
  </Accordion>

  <Accordion title="Does `/execute/stream` support persistent sessions?">
    Not currently. Server streaming path is forced to ephemeral mode.
  </Accordion>

  <Accordion title="Can I override server defaults per request in remote mode?">
    Yes. Send `options` in request envelope; they are merged over server defaults for that execution.
  </Accordion>

  <Accordion title="What does `RemoteIsol8.start()` do?">
    It performs a health check against `/health` to verify remote server reachability.
  </Accordion>

  <Accordion title="What does `RemoteIsol8.stop()` do?">
    If `sessionId` is configured, it calls `DELETE /session/{id}`. Without sessionId it is effectively a no-op cleanup.
  </Accordion>
</AccordionGroup>

## Audit logging and observability

<AccordionGroup>
  <Accordion title="When are audit logs written?">
    Only when `audit.enabled` is true.
  </Accordion>

  <Accordion title="What audit destinations are supported?">
    `filesystem` (or `file`) and `stdout` are implemented.
  </Accordion>

  <Accordion title="Can I keep audit logs but exclude sensitive fields?">
    Yes. Use:

    * `audit.includeCode: false`
    * `audit.includeOutput: false`
      and keep metadata/codeHash/duration-level provenance.
  </Accordion>

  <Accordion title="Can I run custom automation after each audit entry?">
    Yes. `audit.postLogScript` executes after writes and receives audit file path.
  </Accordion>

  <Accordion title="When do network logs appear in execution result?">
    Only when both are true:

    * network mode is `filtered`
    * `logNetwork` is enabled
  </Accordion>

  <Accordion title="How do I reduce audit data retention risk?">
    Keep `audit.includeCode=false` and `audit.includeOutput=false`, and set reasonable `retentionDays`.
  </Accordion>
</AccordionGroup>

## Troubleshooting quick map

* Runtime detection errors: see `/runtimes` and pass explicit runtime.
* Session/file 404s: verify stable `sessionId` and that session was created.
* Unexpected network blocks: verify allow/deny regex and network mode.
* Missing logs/metrics: verify feature flags (`audit.enabled`, `logNetwork`, etc).

## Related pages

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Symptom-driven diagnostics and concrete recovery steps.
  </Card>

  <Card title="Configuration reference" icon="gear" href="/configuration">
    Full defaults, schema keys, and safe override patterns.
  </Card>

  <Card title="Execution guide" icon="terminal" href="/execution">
    Request lifecycle, mode behavior, and streaming semantics.
  </Card>

  <Card title="Remote server and client" icon="server" href="/remote">
    API auth, session lifecycle, and file endpoint behavior.
  </Card>
</CardGroup>