Agent Integration

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

Either way, the agent needs an API key — see API Key Management.

For agent setup and agent-authored islo automations, start with islo-labs/skills (factory-lines for lines and jobs, platform for sandboxes, snapshots, gateways, and the SDK).

Basic Usage

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

Other agents can be added with a 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.

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:

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

Or load from a gitignored file:

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.

Running Background Tasks

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

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:

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:

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:

Access forwarded ports via the URL shown when connecting.

Examples

Daily Development with Claude

# 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

# 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

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

Troubleshooting

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