> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# islo.yaml Configuration

> Complete reference for the islo.yaml project configuration file schema.

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:

```bash
islo init
```

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

## Full Schema

```yaml
# Sandbox name (optional - server generates if not set)
sandbox: my-project

# Container image
image: ghcr.io/islo-labs/islo-runner:latest

# Resource allocation
cpu: 2
memory_mb: 2048
disk_gb: 10

# Working directory in sandbox
workdir: /workspace/app

# Environment variables
env:
  MY_VAR: value
  ANOTHER_VAR: another-value

# Git repositories to clone
sources:
  - github://owner/repo
  - github://owner/other-repo:feature-branch
  - https://github.com/owner/private-repo.git

# Gateway profile for network policy and credential injection
gateway_profile: my-gateway

# Named reusable environment for sandbox env vars and gateway-injected secrets
environment: production

# Setup — use ONE of these forms (if both are set, setup_scripts wins and a warning is logged).
# Form A: a single shell block.
setup_script: |
  uv sync
```

Or use named, ordered steps instead of `setup_script`:

```yaml
setup_scripts:
  - name: Install Python deps
    script: uv sync
  - name: Install Node deps
    script: npm install
```

## Configuration Fields

### sandbox

**Type:** `string`
**Required:** No

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

```yaml
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.

```yaml
image: ghcr.io/islo-labs/islo-runner:latest
```

**Pre-pulled images (recommended for fast startup):**

| Image                                  | Description                                             |
| -------------------------------------- | ------------------------------------------------------- |
| `ghcr.io/islo-labs/islo-runner:latest` | Default Islo runner with common dev tools (recommended) |

### cpu

**Type:** `integer`
**Required:** No

Number of virtual CPUs allocated to the sandbox.

```yaml
cpu: 2
```

### memory_mb

**Type:** `integer`
**Required:** No

Memory allocation in megabytes.

```yaml
memory_mb: 2048
```

### disk_gb

**Type:** `integer`
**Required:** No

Disk space allocation in gigabytes.

```yaml
disk_gb: 10
```

### workdir

**Type:** `string`
**Required:** No

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

```yaml
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.

```yaml
# Shorthand
sources:
  - github://owner/repo
  - github://owner/repo:branch-name
  - https://github.com/owner/repo.git

# Structured (equivalent)
sources:
  - url: https://github.com/owner/repo
    branch: main
  - url: github://owner/other-repo
```

**Shorthand formats:**

| Format                       | Description                      |
| ---------------------------- | -------------------------------- |
| `github://owner/repo`        | Clone default branch from GitHub |
| `github://owner/repo:branch` | Clone specific branch            |
| `https://...`                | Clone from any HTTPS Git URL     |

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. Omit this to use your workspace default profile.

```yaml
gateway_profile: production-apis
```

With a gateway profile (the workspace default or a custom one):

* 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](/cli/gateways/) for more details.

### environment

**Type:** `string`
**Required:** No

Named reusable environment to apply when creating a sandbox. Environments can provide sandbox env vars and environment-owned gateway-injected secrets.

```yaml
environment: production
```

Use environment names in config and CLI flows.

### env

**Type:** `object`
**Required:** No

Environment variables to set in the sandbox.

> **Do not commit secrets here.** `islo.yaml` is checked into git (see [How Islo Works](/concepts/how-islo-works/)). Use non-secret config in `env:` — feature flags, URLs without credentials, debug settings. For API keys and passwords, use [`islo login --tool`](/cli/authentication/), or pass values via [`--env-file`](/cli/sandbox-commands/) pointing at a gitignored `.env` file.

```yaml
env:
  DATABASE_URL: postgres://localhost/mydb
  DEBUG: "true"
```

### user

**Type:** `string`
**Required:** No

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

```yaml
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`.

```yaml
setup_script: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  export PATH="$HOME/.local/bin:$PATH"
  uv sync
```

Use this for simple projects where one block of setup is enough. For ordered, named steps, use [`setup_scripts`](#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`.

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

| Field    | Description                                               |
| -------- | --------------------------------------------------------- |
| `name`   | Human-readable step name (shown in setup output and logs) |
| `script` | Shell snippet for the step                                |

`islo add` writes entries into this list. See [Setup Scripts](/concepts/tools-lifecycle/) for execution details and recipes.

## Example Configurations

### Minimal project

```yaml
sandbox: simple-python
image: ghcr.io/islo-labs/islo-runner:latest
```

### Full CI Environment

```yaml
sandbox: ci-runner
image: ghcr.io/islo-labs/islo-runner:latest
cpu: 4
memory_mb: 4096
disk_gb: 50
env:
  CI: "true"
```

### Web Development

```yaml
sandbox: web-dev
image: ghcr.io/islo-labs/islo-runner:latest
cpu: 2
memory_mb: 2048
disk_gb: 20
env:
  NODE_ENV: development
```

### Git-Based Workflow

```yaml
sandbox: my-feature
sources:
  - github://myorg/backend:feature-branch
  - github://myorg/shared-libs
workdir: /workspace/backend
setup_scripts:
  - name: Install backend deps
    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:

| Variable            | Description     |
| ------------------- | --------------- |
| `ISLO_IMAGE`        | Container image |
| `ISLO_SANDBOX_NAME` | Sandbox name    |
| `ISLO_CPU`          | CPU count       |
| `ISLO_MEMORY_MB`    | Memory in MB    |
| `ISLO_DISK_GB`      | Disk size in GB |

## Validation

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

| Symptom                                                     | Cause                                             | Fix                                                                                                                                                                           |
| ----------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid sandbox name                                        | Special characters in `sandbox:`                  | Use alphanumeric characters and hyphens only                                                                                                                                  |
| YAML parse error (mapping / indentation / unexpected token) | YAML syntax issue                                 | Check indentation — use spaces, not tabs; keep nested keys aligned                                                                                                            |
| "unknown field" parse error                                 | Field not in the schema (e.g., `tools:`, `cpus:`) | Compare against the field list above; common stale fields are `tools:` and `tools_auto_detect:` (replaced by `setup_script` / `setup_scripts`) and `cpus:` (renamed to `cpu`) |

### Validate Configuration

Check your configuration with:

```bash
islo status
```

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