Skip to main content
Dependency management is crucial for robust code execution. isol8 offers two strategies:
  1. On-the-fly Installation: Install packages before each execution. Flexible but slower.
  2. Custom Images: Bake packages into the Docker image. Fast and reproducible.

​
Strategy 1: On-the-Fly Installation

Great for prototyping or when you need different packages for every run.
Use --install <package> (can be repeated).
# Python
isol8 run \
  -e "import numpy" \
  --runtime python \
  --install numpy

# Node.js
isol8 run \
  -e "require('lodash')" \
  --runtime node \
  --install lodash
Installation happens inside the container before code execution. This adds overhead (seconds to minutes depending on package size). For frequently used packages, prefer custom images.
Runtime installs are written under /sandbox (for example /sandbox/.local, /sandbox/.npm-global, /sandbox/.bun-global). This is intentional because /tmp is mounted noexec.
Bake your dependencies into a custom Docker image (isol8:python-custom-<hash>, etc.). This eliminates installation time during execution.

​
Creating Custom Images

Run isol8 setup with package flags. 
# Bake numpy and pandas into the Python image
isol8 setup --python numpy,pandas

# Bake lodash into the Node.js image
isol8 setup --node lodash
This creates a deterministic hashed tag (for example isol8:python-custom-a1b2c3d4e5f6) that extends the base isol8:python image.

​
Using Custom Images

Once built, isol8 automatically prefers the custom image. You don’t need any special flags. 
# Automatically uses the hashed custom image for your configured dependencies
isol8 run \
  -e "import numpy; print(numpy.__version__)" \
  --runtime python

​
Config File (isol8.config.json)

Define dependencies in your config file to ensure consistent environments across your team. 
{
  "dependencies": {
    "python": ["numpy", "pandas", "scikit-learn"],
    "node": ["lodash", "express"],
    "bun": ["zod"],
    "bash": ["jq", "curl"]
  }
}
Run isol8 setup to apply changes.

​
Image Architecture

Understanding how images are built helps optimize your setup.

​
Base Images

  • isol8:python: Python 3.x + pip
  • isol8:node: Node.js LTS + npm
  • isol8:bun: Bun runtime
  • isol8:deno: Deno runtime
  • isol8:bash: Bash + apk
Built from a minimal Alpine 3.21 base for security and speed.

​
Custom Images

Custom images extend the base image. For example, a hashed Python custom image is built like this: 
FROM isol8:python
RUN pip install --no-cache-dir numpy pandas scikit-learn
This ensures your custom image inherits all security features (non-root user, proxy, etc.) from the base image.

​
Smart Rebuilds

isol8 setup is intelligent. It avoids unnecessary work by tracking build state using Docker labels.
  1. Change Detection: It computes SHA256 hashes of your docker/ directory (for base images) and your dependency lists (for custom images).
  2. Metadata: These hashes are stored in the image labels org.isol8.build.hash and org.isol8.deps.hash.
  3. Fast Path: If the hashes match the existing image, the build is skipped instantly.
  4. Auto-Cleanup: When a rebuild is necessary, isol8 automatically removes the old image version to prevent “dangling images” from clogging your disk.
# Up to date - skips build (0s)
isol8 setup

# Add a package - triggers rebuild & cleanup
isol8 setup \
  --python requests
Use --force to bypass this check and rebuild unconditionally.

​
FAQ

Use --install for ad-hoc experimentation. Use custom images for repeatable production workloads and lower execution latency.
Native modules often need executable mount points. isol8 installs runtime packages under /sandbox because /tmp is mounted with noexec.
Yes. isol8 setup merges dependency flags (--python, --node, etc.) with configured dependencies before building custom images.

​
Troubleshooting quick checks

  • Install step is too slow: pre-bake dependencies with isol8 setup and dependencies config.
  • Package import still fails after install: verify runtime/package pairing (for example Python package in Python runtime).
  • Custom image not updating: rerun isol8 setup --force.
  • Disk usage growing from images: run isol8 cleanup --images to remove isol8 images.

​
Reference

How to CLI

All isol8 setup options and flags.

Configuration

Full schema for dependencies in isol8.config.json.

Execution guide

See install behavior in the full execution lifecycle.

Troubleshooting

Diagnose setup, install, and runtime issues.