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

# Agent Integration

> Run AI coding agents in Islo sandboxes with islo use --agent.

Islo provides first-class support for AI coding agents. There are two ways to get an agent into your sandbox:

* **Out of the box** — sandboxes created from Islo's default image already have **Claude Code**, **Cursor CLI**, and **Codex CLI** installed. Just run `claude`, `cursor`, or `codex` inside the sandbox.
* **On demand** — for any other [supported agent](#supported-agents), pass `--agent <agent>` and Islo installs and configures it for you. For an agent Islo doesn't support, add it to the sandbox with a [setup script](/cli/islo-yaml#setup_script).

Either way, the agent needs an API key — see [API Key Management](#api-key-management).

For agent setup and agent-authored islo automations, start with [islo-labs/skills](https://github.com/islo-labs/skills) (**factory-lines** for lines and jobs, **platform** for sandboxes, snapshots, gateways, and the SDK).

## Basic Usage

```bash
islo use --agent claude              # Interactive Claude Code session
islo use --agent cursor              # Interactive Cursor agent
islo use my-sandbox --agent claude   # Use specific sandbox with agent
```

When you specify `--agent`, Islo:

1. Ensures the agent's CLI tool is available in the sandbox
2. Configures the correct environment variables
3. Uses the agent's entrypoint instead of a plain shell
4. Sets up API key authentication

## Supported Agents

| Agent    | CLI Tool    | Authentication                              |
| -------- | ----------- | ------------------------------------------- |
| `claude` | claude-code | `islo login --tool claude` (or `anthropic`) |
| `cursor` | cursor-cli  | `islo login --tool cursor`                  |
| `codex`  | codex       | `islo login --tool openai`                  |

Other agents can be added with a [setup script](/cli/islo-yaml#setup_script).

## API Key Management

### Connecting Integrations

Use `islo login --tool` to connect an agent provider. Once connected, sandbox sessions pick up the integration automatically — no local key file and no `islo.yaml` change.

```bash
islo login --tool claude      # Anthropic API key (alias for anthropic)
islo login --tool anthropic   # Anthropic API key
islo login --tool cursor      # Cursor API key
islo login --tool openai      # OpenAI API key
```

Anthropic and Cursor use **API key** integrations (not OAuth). Credentials are held server-side; the sandbox never sees the raw API key when gateway injection is active.

### Key Precedence

When starting an agent session, credentials are resolved in this order:

1. **Connected integrations** (from `islo login --tool`) — server-side, transparent to the sandbox
2. **Environment variables** (from your shell)
3. **`islo.yaml` `env:` section**

### Passing Keys via Environment (fallback)

If you are not using integrations, pass keys per session:

```bash
ANTHROPIC_API_KEY=sk-... islo use --agent claude
```

Or load from a gitignored file:

```bash
islo use --agent claude --env-file .env
```

`islo.yaml` does **not** expand shell-style `${VAR}` placeholders. Values in `env:` are used literally. Do not commit API keys in `islo.yaml` — use `--env-file` or integrations instead. See [islo.yaml configuration](/configuration/islo-yaml/).

## Running Background Tasks

Use `--task` to run an agent with a prompt in the background:

```bash
islo use --agent claude --task "Refactor the auth module to use JWT"
islo use --agent cursor --task "Add unit tests for the API endpoints"
```

This:

1. Creates/connects to the sandbox
2. Starts the agent in a persistent session
3. Passes the task prompt to the agent
4. Returns control to your terminal (agent runs in background)

### Checking Task Progress

Reconnect to see agent progress:

```bash
islo use my-sandbox --agent claude
```

If the agent supports session resume, it will continue the previous session.

## Session Resume

Some agents support resuming previous sessions. When you reconnect with `--agent`, Islo checks for saved session state and resumes if available.

### Claude Code

Claude Code sessions are automatically saved to `/workspace/.islo/session.json`. When you reconnect:

```bash
islo use my-sandbox --agent claude
```

Islo detects the saved session and resumes it. To start fresh, recreate the sandbox under a different name or remove the existing one with `islo rm <name>` before running `islo use` again.

## Port Forwarding

Some agents expose web interfaces. Islo automatically forwards their ports:

| Agent          | Port | Description |
| -------------- | ---- | ----------- |
| `opencode-web` | 4096 | Web UI      |

Access forwarded ports via the URL shown when connecting.

## Examples

### Daily Development with Claude

```bash
# Connect the integration once
islo login --tool claude

# Start working (creates sandbox if needed)
islo use my-project --agent claude

# Later, reconnect and resume
islo use my-project --agent claude
```

### Overnight Refactoring Task

```bash
# Start a long-running task
islo use backend --agent claude --task "Migrate all database queries to use the new ORM. Update tests accordingly."

# Check progress later
islo use backend --agent claude
```

### Multiple Agents

```bash
# Use different agents for different sandboxes
islo use frontend --agent cursor
islo use backend --agent claude
```

## Troubleshooting

See [Troubleshooting → Agents](/cli/troubleshooting/#agents) for `--task requires an agent profile…` and authentication failures.

### Session Not Resuming

Session state lives inside the sandbox under `/workspace/.islo/`. If the sandbox was recreated, that state is gone. Use a consistent sandbox name across runs to preserve sessions.