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.

For runnable Python SDK examples (Claude Code, Codex, Claude Agent SDK), see Islo Recipes on GitHub.

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

Connecting Integrations

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

$
islo login --tool claude     # Connect Anthropic via OAuth
$
islo login --tool cursor     # Connect Cursor via OAuth

The OAuth flow runs in your browser through Islo’s web app. Credentials are held server-side; the sandbox never sees the raw API key, and the team-wide connection means other members don’t need their own keys.

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

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