islo.yaml Configuration

The islo.yaml file defines project-level sandbox configuration. Place it in your project root.

Create Configuration

Generate a configuration file with the setup wizard:

$
islo init

This interactive wizard creates islo.yaml and seeds setup scripts for tools it detects in your project.

Full Schema

1
# Sandbox name (optional - server generates if not set)
2
sandbox: my-project
3
4
# Container image
5
image: ghcr.io/islo-labs/islo-runner:latest
6
7
# Resource allocation
8
cpu: 2
9
memory_mb: 2048
10
disk_gb: 10
11
12
# Working directory in sandbox
13
workdir: /workspace/app
14
15
# Environment variables
16
env:
17
  MY_VAR: value
18
  ANOTHER_VAR: another-value
19
20
# Git repositories to clone
21
sources:
22
  - github://owner/repo
23
  - github://owner/other-repo:feature-branch
24
  - https://github.com/owner/private-repo.git
25
26
# Gateway profile for network policy and credential injection
27
gateway_profile: my-gateway
28
29
# Setup — use ONE of these forms (if both are set, setup_scripts wins and a warning is logged).
30
# Form A: a single shell block.
31
setup_script: |
32
  uv sync

Or use named, ordered steps instead of setup_script:

1
setup_scripts:
2
  - name: Install Python deps
3
    script: uv sync
4
  - name: Install Node deps
5
    script: npm install

Configuration Fields

sandbox

Type: string Required: No

Unique identifier for the sandbox. If not provided, the server generates a name.

1
sandbox: my-project

Constraints:

• Alphanumeric characters and hyphens only
• Must be unique across your sandboxes
• Case-sensitive

image

Type: string Required: No (defaults to ghcr.io/islo-labs/islo-runner:latest)

Docker image to use for the sandbox. Should be a fully qualified image reference.

1
image: ghcr.io/islo-labs/islo-runner:latest

Pre-pulled images (recommended for fast startup):

cpu

Type: integer Required: No

Number of virtual CPUs allocated to the sandbox.

1
cpu: 2

memory_mb

Type: integer Required: No

Memory allocation in megabytes.

1
memory_mb: 2048

disk_gb

Type: integer Required: No

Disk space allocation in gigabytes.

1
disk_gb: 10

workdir

Type: string Required: No

Working directory inside the sandbox. Commands and agent sessions start in this directory.

1
workdir: /workspace/my-app

If not specified, defaults to /workspace or the root of the cloned repository.

sources

Type: array Required: No

Git repositories to clone into the sandbox. Each entry can be a shorthand string or a structured {url, branch} object.

1
# Shorthand
2
sources:
3
  - github://owner/repo
4
  - github://owner/repo:branch-name
5
  - https://github.com/owner/repo.git
6
7
# Structured (equivalent)
8
sources:
9
  - url: https://github.com/owner/repo
10
    branch: main
11
  - url: github://owner/other-repo

Shorthand formats:

Repositories are cloned during sandbox creation. Use islo init to detect and add sources from your current directory.

gateway_profile

Type: string Required: No

Gateway profile name for network policy and authentication. Gateways control how your sandbox connects to external services.

1
gateway_profile: production-apis

When a gateway profile is configured:

• Network policies control which external endpoints your sandbox can reach
• Authentication is handled transparently at the host level (credentials are never exposed in the sandbox)
• Traffic can be routed through specific endpoints

See Gateways for more details.

env

Type: object Required: No

Environment variables to set in the sandbox.

1
env:
2
  DATABASE_URL: postgres://localhost/mydb
3
  DEBUG: "true"

user

Type: string Required: No

Username to run sandbox commands as. Defaults to islo (non-root).

1
user: root

setup_script

Type: string Required: No

A single shell script that runs inside the sandbox after sources are cloned. Runs as the islo user in /workspace.

1
setup_script: |
2
  curl -LsSf https://astral.sh/uv/install.sh | sh
3
  export PATH="$HOME/.local/bin:$PATH"
4
  uv sync

Use this for simple projects where one block of setup is enough. For ordered, named steps, use setup_scripts instead.

setup_scripts

Type: array of { name, script } Required: No

Named setup steps that run in order after sources are cloned. Each step runs as the islo user in /workspace.

1
setup_scripts:
2
  - name: Install Claude Code
3
    script: curl -fsSL https://claude.ai/install.sh | DISABLE_AUTOUPDATER=1 bash
4
  - name: Install Rust stable
5
    script: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable

islo add writes entries into this list. See Setup Scripts for execution details and recipes.

Example Configurations

Minimal project

1
sandbox: simple-python
2
image: ghcr.io/islo-labs/islo-runner:latest

Full CI Environment

1
sandbox: ci-runner
2
image: ghcr.io/islo-labs/islo-runner:latest
3
cpu: 4
4
memory_mb: 4096
5
disk_gb: 50
6
env:
7
  CI: "true"

Web Development

1
sandbox: web-dev
2
image: ghcr.io/islo-labs/islo-runner:latest
3
cpu: 2
4
memory_mb: 2048
5
disk_gb: 20
6
env:
7
  NODE_ENV: development

Git-Based Workflow

1
sandbox: my-feature
2
sources:
3
  - github://myorg/backend:feature-branch
4
  - github://myorg/shared-libs
5
workdir: /workspace/backend
6
setup_scripts:
7
  - name: Install backend deps
8
    script: pip install -e .

This configuration clones two repositories, sets the working directory to the backend repo, and runs pip install -e . after the clones complete.

Configuration Precedence

Configuration is resolved in this order (later overrides earlier):

1. Default values
2. islo.yaml in project directory
3. Environment variables (ISLO_*)
4. CLI flags (--cpu, --memory, etc.)

Environment Variables

These environment variables override islo.yaml settings:

Validation

Islo validates islo.yaml when the CLI loads it. Common problems:

Validate Configuration

Check your configuration with:

$
islo status

This shows your current auth state and configuration from islo.yaml.