Agent Integration

Islo provides first-class support for AI coding agents. Use --agent to automatically configure your sandbox for agents like Claude Code, Cursor, Codex, and more.

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. Installs the agent’s CLI tool 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

API Key Management

Storing Keys

Use islo login --agent to store API keys securely:

$
islo login --agent claude    # Prompts for ANTHROPIC_API_KEY
$
islo login --agent openai    # Prompts for OPENAI_API_KEY
$
islo login --agent cursor    # Prompts for CURSOR_API_KEY

Keys are stored in ~/.islo/agent_keys.json and automatically injected into sandbox sessions.

Server-Side Integrations

For some agents, you can use server-side integrations instead of storing API keys locally:

$
islo login --tool claude     # OAuth-based Anthropic integration
$
islo login --tool cursor     # OAuth-based Cursor integration

With integrations, sandbox tasks use server-side API access. This is more secure and enables team-wide agent access without sharing API keys.

Key Precedence

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

1. Stored keys (from islo login --agent) - highest priority
2. Environment variables (from your shell)
3. islo.yaml env section

Passing Keys via Environment

You can also pass keys directly:

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

Or set them in islo.yaml:

1
env:
2
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

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

$
islo use my-sandbox --agent claude --no-resume

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

$
# Store your API key once
$
islo login --agent 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

”API key not found”

$
# Check if key is stored
$
islo status
$
$
# Store the key
$
islo login --agent claude

Agent Not Starting

Check that the agent tool was installed:

$
islo use my-sandbox
$
which claude  # or cursor, codex, etc.

If missing, the install phase may have failed. Check mise install output and retry.

Session Not Resuming

Session files are stored in /workspace/.islo/. If the sandbox was recreated, session state is lost. Use a consistent sandbox name to preserve sessions.