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 workflows, start with islo-labs/skills. It is the maintained agent-readable reference for Islo sandboxes, automations, gateway integrations, SDK usage, and templates.

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

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.