How to CLI

Detailed command-line guide for isol8 with flag-by-flag behavior for run, setup, build, serve, config, and cleanup commands.

Migration: CLI is now @isol8/cli (installed as isol8 command).

This page is a flag-by-flag reference for the isol8 CLI.

Global option

--debug · flag

Enables debug logs for CLI internals and engine operations.

isol8 run

isol8 run [file] [options]

isol8 run streams output by default. Use --no-stream only when you want buffered output after execution completes.

Input and runtime flags

[file] · argument

Script file path. Runtime is auto-detected from extension unless --runtime is provided.

-e, --eval <code> · string

Inline code to execute.

-r, --runtime <name> · python | node | bun | deno | bash | agent

Force runtime instead of extension-based detection. The agent runtime must always be specified explicitly (no file extension mapping).

--stdin <data> · string

Explicit stdin payload for the execution process.

--workdir <path> · string · default: "/sandbox"

Working directory for the main code execution. Accepts an absolute path under /sandbox or a relative path resolved from /sandbox. Paths that escape the sandbox boundary are rejected.

Security and resource flags

--net <mode> · none | host | filtered · default: "none"

Sets the network egress mode for the container.

• none: Blocks all network access (default).
• filtered: Routes traffic through a proxy with whitelist/blacklist enforcement.
• host: Allows full host network access (use with extreme caution).

If --install is used and --net is not explicitly provided, CLI automatically uses filtered.

--net host gives untrusted code full outbound network access. Prefer none (default) or filtered for most workloads.

--allow <regex> · repeatable

Adds a regex pattern to the whitelist in filtered mode. Only hostnames matching at least one allow pattern will be permitted.

--deny <regex> · repeatable

Blacklist pattern for filtered mode.

--timeout <ms> · number

Timeout in milliseconds for package installation and code execution.

--memory <size> · string

Memory limit (512m, 1g, etc.).

--cpu <limit> · number

CPU limit as fraction/cores.

--pids-limit <n> · number · default: "64"

Maximum number of processes.

--max-output <bytes> · number · default: "1048576"

Maximum output size before truncation.

--sandbox-size <size> · string · default: "512m"

/sandbox tmpfs size.

--tmp-size <size> · string · default: "256m"

/tmp tmpfs size.

State and behavior flags

--persistent · flag

Use persistent mode (mode=persistent).

--persist · flag

Keep container alive after execution finishes.

--no-stream · flag

Disable realtime streaming and use buffered execute() path.

--install <package> · repeatable

Install package before execution.

In filtered mode, CLI automatically merges default runtime package registry hosts into the allowlist. Explicit --net is never overridden.

--setup <command> · repeatable

Inline shell command or path to a script file to run before the main code execution. Runs as the sandbox user from /sandbox. If the value is an existing file path, its contents are read and used as the script. Multiple --setup flags are concatenated with newlines. Useful for cloning repos, creating directories, configuring tools, etc.

--secret <KEY=VALUE> · repeatable

Inject secret env vars and mask values in output.

--agent-flags <flags> · string

Extra flags passed to the pi coding agent before the prompt. Only valid with --runtime agent. Common flags: --model <name>, --thinking, --max-tokens <n>.

--files <dir> · string

Recursively inject a local directory into the container under /sandbox. Skips .git, node_modules, __pycache__, .venv, venv, and .tox directories. Useful with the agent runtime to provide project files for the agent to work on.

--out <file> · string

Write stdout to local file.

--image <name> · string

Override runtime image.

--log-network · flag

Enable network request logs in results (filtered mode).

Remote execution flags

--host <url> · string

Execute against remote isol8 serve instance.

--key <key> · string

API key for remote execution (ISOL8_API_KEY fallback).

--session-id <id> · string

Use a named persistent session on the remote server. The session survives after the CLI exits and can be resumed by passing the same ID again.

Implies --persistent — you do not need to pass both. Requires --host — session IDs are a server-side concept.

Examples

# Inline Python
isol8 run \
  -e "print(2 ** 10)" \
  --runtime python

# Filtered networking
isol8 run \
  task.py \
  --net filtered \
  --allow "^api\.openai\.com$"

# Persistent mode
isol8 run \
  --persistent \
  -e "x = 42" \
  --runtime python

# Remote execution
isol8 run \
  script.py \
  --host http://localhost:3000 \
  --key my-key

# Named session — survives after CLI exits
isol8 run \
  -e "x = 42" \
  --runtime python \
  --session-id my-session \
  --host http://localhost:3000 \
  --key my-key

# Resume the same session later
isol8 run \
  -e "print(x)" \
  --runtime python \
  --session-id my-session \
  --host http://localhost:3000 \
  --key my-key

# AI coding agent
isol8 run \
  -e "add error handling to all API endpoints" \
  --runtime agent \
  --net filtered --allow "api.anthropic.com" \
  --secret "ANTHROPIC_API_KEY=sk-..." \
  --files ./my-project \
  --workdir /sandbox/my-project \
  --timeout 600000

# Agent with extra pi flags
isol8 run \
  -e "refactor auth module" \
  --runtime agent \
  --net filtered --allow "api.anthropic.com" \
  --secret "ANTHROPIC_API_KEY=sk-..." \
  --files ./src \
  --agent-flags "--model claude-sonnet-4-20250514 --thinking"

isol8 setup

isol8 setup [options]

Builds base isol8 Docker images and any prebuiltImages declared in isol8.config.json.

--force · flag

Force rebuild even when images are up to date.

If your config defines prebuiltImages, isol8 setup will also check each one and build any that don’t already exist locally.

isol8 serve

isol8 serve --key <api-key> [options]

-p, --port <port> · number · default: "3000"

Port for server listener. Resolution order is --port > ISOL8_PORT > PORT > 3000. If the selected port is occupied, the CLI prompts to choose a different port or automatically finds an available one.

-k, --key <key> · string

API key for bearer auth. If omitted, ISOL8_API_KEY environment variable is used. When --auth-db is also provided, this key becomes the master key with admin privileges.

--auth-db [connection] · string

Enable DB-backed API key management. When provided without a value or with a file path, uses SQLite (defaults to ~/.isol8/auth.db). Pass a postgres:// or postgresql:// URL for PostgreSQL, or a mysql:// URL for MySQL. The backend is auto-detected from the connection string format. When enabled, the --key value becomes the master key, and additional keys can be created via the /auth/keys endpoint or the isol8 login flow. See Server overview for the full authentication model.

--update · flag

Force re-download of standalone server binary.

--debug · flag

Enable debug logs for server internals.

Examples

# Static key auth (default)
isol8 serve --key my-secret-key --port 3000

# DB-backed auth with SQLite (default path ~/.isol8/auth.db)
isol8 serve --key my-master-key --auth-db --port 3000

# DB-backed auth with SQLite (custom path)
isol8 serve --key my-master-key --auth-db ./isol8-auth.db --port 3000

# DB-backed auth with PostgreSQL
isol8 serve --key my-master-key --auth-db "postgres://user:pass@localhost:5432/isol8" --port 3000

# DB-backed auth with MySQL
isol8 serve --key my-master-key --auth-db "mysql://user:pass@localhost:3306/isol8" --port 3000

For full server behavior and endpoints, see the Server docs tab: Server overview and Server routes.

isol8 login

isol8 login --host <url> --key <master-key> [options]

Authenticate with a remote isol8 server that has DB-backed auth enabled. This command exchanges the master key for a short-lived API token via POST /auth/login and stores the credentials locally.

--host <url> · string · required

Server URL to authenticate against (e.g. http://localhost:3000).

--key <key> · string · required

Master API key for the server. This is the same key passed to isol8 serve --key.

--name <name> · string

Optional human-readable name for the login token. Defaults to cli-login-<timestamp>.

--ttl <ms> · number

Token time-to-live in milliseconds. Defaults to 24 hours (86400000).

Once authenticated, credentials are saved to ~/.isol8/credentials.json (file permissions 0600). Subsequent isol8 run --host <url> commands automatically use the stored token without needing --key.

Credential resolution priority

When running remote commands (isol8 run --host ...), the CLI resolves the API key in this order:

1. --key flag (explicit, always wins)
2. ISOL8_API_KEY environment variable
3. Stored credentials from ~/.isol8/credentials.json (if host matches and token is not expired)

Examples

# Login to a local server
isol8 login --host http://localhost:3000 --key my-master-key

# Login with custom name and TTL
isol8 login \
  --host https://isol8.example.com \
  --key my-master-key \
  --name "dev-laptop" \
  --ttl 3600000

# After login, --key is no longer needed for this host
isol8 run -e "print('hello')" \
  --runtime python \
  --host http://localhost:3000

The server must have --auth-db enabled. If DB-backed auth is not active, isol8 login will fail with a 400 error.

isol8 logout

isol8 logout

Remove stored credentials from ~/.isol8/credentials.json. This does not revoke the token on the server — it only deletes the local credential file.

Examples

isol8 logout
# [OK] Credentials removed from ~/.isol8/credentials.json

isol8 session

Manage persistent sessions on a remote server.

isol8 session list

isol8 session list --host <url> [--key <key>] [--json]

Lists all active persistent sessions on the remote server.

--host <url> · string · required

Remote server URL.

--key <key> · string

API key (ISOL8_API_KEY fallback, or stored credentials from isol8 login).

--json · flag

Print raw JSON array instead of the formatted table.

Examples

# Table output
isol8 session list --host http://localhost:3000 --key my-key

# JSON output
isol8 session list --host http://localhost:3000 --key my-key --json

isol8 session stop

isol8 session stop <id> --host <url> [--key <key>]

Destroys a specific persistent session on the remote server and releases its resources.

<id> · argument · required

Session ID to destroy.

--host <url> · string · required

Remote server URL.

--key <key> · string

API key (ISOL8_API_KEY fallback, or stored credentials from isol8 login).

Examples

# Stop a named session
isol8 session stop my-session --host http://localhost:3000 --key my-key

isol8 build

Build a custom runtime image with pre-baked dependencies and/or a setup script.

isol8 build --base <runtime> [--install <package>] [--setup <command>] --tag <name> [options]

--base <runtime> · python | node | bun | deno | bash · required

Runtime base image to extend.

--install <package> · repeatable

Package to bake into the image. Supports repeated flags and comma-separated values.

--setup <command> · repeatable

Shell command or file path baked into the image. Runs automatically before every execution that uses this image. When an execution request also carries its own --setup, the image-level script runs first followed by the request-level script. If the value points to an existing file, its content is read; otherwise the value is treated as a literal shell command.

--tag <name> · string · required

Name/tag for the custom image (e.g. my-python-ml:latest). Metadata labels are embedded automatically.

--force · flag

Force rebuild even if current inputs resolve to an existing up-to-date image.

Examples

# Build a custom Python image with ML packages
isol8 build --base python --install numpy --install pandas --tag my-python-ml

# Build a custom Node.js image
isol8 build --base node --install express,lodash --tag my-node-api

# Build with a setup script that runs before every execution
isol8 build --base python --install numpy --setup "pip install -e /sandbox/mylib" --tag my-python-dev

# Build with setup only (no packages)
isol8 build --base bash --setup "echo ready" --tag my-bash-env

# Force rebuild
isol8 build --base python --install numpy --tag my-python-ml --force

isol8 list-custom

List all locally available custom isol8 images.

isol8 list-custom

Displays each custom image’s tag, runtime, pre-installed dependencies, and setup script (if any) based on embedded Docker labels.

isol8 config

isol8 config [options]

isol8 cleanup

isol8 cleanup [options]

--json · flag

Print resolved config as JSON.

isol8 cleanup

isol8 cleanup [options]

--force · flag

Skip confirmation prompt.

--images · flag

Also remove isol8 Docker images.

FAQ

What is the difference between `--persistent` and `--persist`?

--persistent sets execution mode to persistent (reuses container state across runs). --persist keeps the container alive after a run for inspection/debugging.

What is the difference between `--persistent` and `--session-id`?

--persistent creates a persistent session with an auto-generated ID that is destroyed when the CLI exits. --session-id assigns a user-chosen name and keeps the session alive on the server after the CLI exits, so you can reconnect later with the same ID.

Do I need `--key` for `isol8 serve` every time?

No. isol8 serve accepts --key, but it can also read the API key from ISOL8_API_KEY.

What is the difference between `--key` and `--auth-db`?

--key sets a single static API key (or master key). --auth-db enables database-backed key management (SQLite, PostgreSQL, or MySQL) where you can create, list, and revoke multiple keys via the /auth/* endpoints. Both can be used together — the --key becomes the master key when --auth-db is enabled.

Do I need to run `isol8 login` to use remote execution?

No. You can always pass --key explicitly or set ISOL8_API_KEY. isol8 login is a convenience that stores credentials locally so you don’t have to provide the key on every command.

Why does `isol8 run` print output in real time?

Streaming is the default behavior. Use --no-stream if you want buffered output only after the run completes.

What is the agent runtime?

The agent runtime runs the pi coding agent inside an isol8 sandbox. The -e value is treated as the prompt, not code. It requires --net filtered with an --allow entry for the LLM API, and an API key via --secret. The CLI automatically raises pidsLimit to 200 and sandboxSize to 2g for agent runs.

Troubleshooting quick checks

• [ERR] --session-id requires --host: --session-id is a server feature; add --host <url>.
• [ERR] API key required on serve or remote run: pass --key or set ISOL8_API_KEY.
• isol8 login fails with 400: the server does not have --auth-db enabled. Restart the server with --auth-db <path>.
• Stored credentials expired: run isol8 login again to re-authenticate.
• Runtime not detected from file extension: pass --runtime <name> explicitly.
• No output appears while command runs: check if --no-stream is enabled.
• Filtered mode still blocks host: verify --allow regex matches hostname exactly.
• Agent runtime fails with network error: ensure --net filtered and --allow are set. The agent runtime enforces filtered networking with at least one whitelist entry.
• Agent runtime out of disk space: increase --sandbox-size (default 2g for agent). Large repos may need 4g+.

See also

Option mapping

Map each CLI flag to config, API, and library equivalents.

Configuration reference

Full config schema, defaults, and precedence rules.

Troubleshooting

Diagnose and fix common CLI/runtime failures quickly.