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, detects tools in your project, and optionally installs IDE hooks.

Full Schema

1
# Sandbox name (optional - server generates if not set)
2
sandbox: my-project
3
4
# Container image
5
image: docker.io/library/python:3.12-slim
6
7
# Resource allocation
8
cpus: 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

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 python:3.12-slim)

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

1
image: docker.io/library/python:3.12-slim

Pre-pulled images (recommended for fast startup):

cpus

Type: integer Required: No

Number of virtual CPUs allocated to the sandbox.

1
cpus: 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. Supports GitHub shorthand and HTTPS URLs.

1
sources:
2
  - github://owner/repo
3
  - github://owner/repo:branch-name
4
  - https://github.com/owner/repo.git

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

tools

Type: object Required: No

Development tools to install in the sandbox. Each tool can specify version and lifecycle tasks.

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

Tool configuration options:

For details on how tools are detected and installed, see Tools Lifecycle.

tools_auto_detect

Type: boolean Required: No (defaults to true)

Whether to auto-detect tools from project files. Set to false to only use explicitly configured tools.

1
tools_auto_detect: false

Adding Tools

Use islo add to manage development tools:

$
# Detect tools interactively
$
islo add
$
$
# Add specific tool
$
islo add python 3.13
$
islo add node 20

Example Configurations

Minimal Python Project

1
sandbox: simple-python
2
image: docker.io/library/python:3.12-slim

Full CI Environment

1
sandbox: ci-runner
2
image: docker.io/library/incredibuild-runner:latest
3
cpus: 4
4
memory_mb: 4096
5
disk_gb: 50
6
env:
7
  CI: "true"

Web Development

1
sandbox: web-dev
2
image: docker.io/library/incredibuild-runner:latest
3
cpus: 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
tools:
7
  python:
8
    version: "3.12"
9
    setup_tasks:
10
      - pip install -e .

This configuration clones two repositories and sets the working directory to the backend repo.

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 (--cpus, --memory, etc.)

Environment Variables

These environment variables override islo.yaml settings:

Validation

Islo validates configuration on sandbox creation. Common errors:

Validate Configuration

Check your configuration with:

$
islo status

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