Tools Lifecycle

Islo automatically detects and installs development tools when creating a sandbox. This page explains the detection process, installation phases, and how to customize tool configuration.

Tool Detection

When you run islo use, Islo scans your project to detect which tools you need. Detection happens in layers, with higher-priority sources overriding lower ones:

Tools defined in islo.yaml always take precedence, allowing you to override auto-detected versions.

Installation Phases

Tool installation happens in distinct phases during sandbox creation:

islo use (new sandbox)
    │
    ├── Phase 0: setup_mise
    │     Write mise.islo.toml, configure cache directories
    │
    ├── Phase 1: mise install
    │     Install runtimes (node, python, ruby, etc.)
    │
    ├── [File sync happens in parallel]
    │
    ├── Phase 3: install_tasks
    │     Custom install scripts (e.g., download binaries, npm install)
    │
    ├── Phase 4: setup_tasks
    │     Post-install setup (e.g., poetry install, bundle install)
    │
    └── Phase 5: start_tasks
          Start services (e.g., pg_ctl start, redis-server)

Phase Details

Phase 0: Setup Mise

Writes mise.islo.toml to the sandbox with your tool configuration. This file tells mise which tools to install and how.

Phase 1: Runtime Installation

Runs mise install to install language runtimes and tools. This includes:

• Node.js, Python, Ruby, Go, Rust
• CLI tools available via mise (ripgrep, jq, etc.)

Phase 3: Install Tasks

Runs custom installation scripts defined in install_tasks. Use this for:

• Downloading pre-built binaries
• Building tools from source
• Running npm install or pip install

Phase 4: Setup Tasks

Runs post-install configuration defined in setup_tasks. Examples:

• poetry install - Install Python dependencies
• bundle install - Install Ruby gems
• uv sync - Sync Python environment

Phase 5: Start Tasks

Runs service startup scripts defined in start_tasks. Examples:

• pg_ctl start - Start PostgreSQL
• redis-server --daemonize yes - Start Redis
• mongod --fork - Start MongoDB

Task Configuration

Each tool can define custom tasks in islo.yaml:

1
tools:
2
  postgres:
3
    version: "16"
4
    setup_tasks:
5
      - initdb -D /workspace/.islo/pgdata
6
    start_tasks:
7
      - pg_ctl -D /workspace/.islo/pgdata -l /workspace/.islo/pg.log start
8
9
  python:
10
    version: "3.12"
11
    setup_tasks:
12
      - poetry install --no-interaction

Task Types

Failure Handling

If a phase fails, you’ll see a yellow warning message but can still use the sandbox. You can re-run failed phases manually:

$
# Inside the sandbox
$
mise install                    # Re-run Phase 1
$
mise run install               # Re-run Phase 3
$
mise run setup                 # Re-run Phase 4
$
mise run start                 # Re-run Phase 5

Adding Tools to Existing Sandboxes

Important: Adding tools to islo.yaml does not automatically update existing sandboxes.

When you run islo use <name> and the sandbox already exists, it simply connects to it without re-provisioning.

Options for Adding Tools

Option 1: Recreate the sandbox

$
islo rm my-sandbox
$
islo use my-sandbox  # Creates fresh with new tools

Option 2: Install manually inside the sandbox

$
# Connect to sandbox
$
islo use my-sandbox
$
$
# Edit mise.islo.toml or run mise commands
$
mise use node@20
$
mise install

islo add vs Editing islo.yaml

Both methods add tools to your configuration, but they work differently:

islo add

$
islo add python 3.12
$
islo add node 20
$
islo add          # Interactive selection

• Applies sensible defaults from Islo’s built-in registry
• Automatically adds common setup_tasks (e.g., poetry install for Python)
• Safer for beginners

Manual Editing

1
tools:
2
  python:
3
    version: "3.12"
4
    setup_tasks:
5
      - pip install -e .

• Full control over all settings
• Required for tools not in the registry
• Must specify backend or install_tasks for unknown tools

When user config is provided, it fully replaces registry defaults - there’s no partial merge. If you override a tool, you need to include all the tasks you want.

Version Management

Islo uses mise as the runtime version manager inside sandboxes.

Version Sources

Versions are resolved from (highest to lowest priority):

1. islo.yaml - Explicit version field
2. Mise/asdf config - .mise.toml, .tool-versions
3. Project files - .nvmrc, pyproject.toml [tool.poetry.dependencies]
4. Registry defaults - Built-in sensible defaults

Supported Formats

1
# islo.yaml
2
tools:
3
  node:
4
    version: "20"        # Major version
5
  python:
6
    version: "3.12.0"    # Exact version
7
  ruby:
8
    version: "latest"    # Latest stable

.tool-versions Support

If your project uses asdf-style .tool-versions, Islo respects it:

python 3.12.0
nodejs 20.10.0
ruby 3.3.0

Tool Registry

Islo includes a built-in registry of common tools with sensible defaults:

For the full list, run islo status in a project directory to see detected tools.

Caching

Islo caches installed tools to speed up sandbox creation. When you create a sandbox:

1. Islo computes a cache key from your image + mise.toml content
2. If a cached VM with matching tools exists, it’s cloned (fast)
3. If not, tools are installed from scratch and the result is cached

This means second sandbox creation with the same tools is much faster.