islo.yaml configuration

islo.yaml can select the project factory. The settings below configure direct sandbox use and the environment that factory Machines may rely on.

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

# Project factory selection, saved by islo factory set <key> --project
factory_id: 00000000-0000-0000-0000-000000000000
# 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:

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

Configuration Fields

factory_id

Type: factory UUID Required: No

islo factory set <key> --project writes this field. The CLI uses it to select the factory for Line, Agent, Machine, Job, and Knowledge commands in this project. Use islo factory current to inspect the selection.

sandbox

Type: string Required: No

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

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.

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.

cpu: 2

memory_mb

Type: integer Required: No

Memory allocation in megabytes.

memory_mb: 2048

disk_gb

Type: integer Required: No

Disk space allocation in gigabytes.

disk_gb: 10

workdir

Type: string Required: No

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

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.

# 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.

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

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 sandbox lifecycle). Use non-secret config in env: — feature flags, URLs without credentials, debug settings. For API keys and passwords, use islo login --tool, or pass values via --env-file pointing at a gitignored .env file.

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

user

Type: string Required: No

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

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.

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

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 for execution details and recipes.

Example Configurations

Minimal project

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

Full CI Environment

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

Web Development

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

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):

Default values
islo.yaml in project directory
Environment variables (ISLO_*)
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:

islo status

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