Quick Start

Two ways to drive Islo: the SDK from your code, or the CLI from your terminal. Pick whichever fits.

Use the SDK

The fastest way to drive Islo from your code is the official SDK. Grab an API key from the dashboard, then install:

$
uv add islo

$
export ISLO_API_KEY="your-api-key"

Commands run asynchronously inside the sandbox: exec_in_sandbox returns an exec_id with status: "started", and you poll get_exec_result until the status reaches a terminal value (completed, failed, or timeout).

The synchronous client is the default:

1
import time
2
from islo import Islo
3
4
client = Islo()  # picks up ISLO_API_KEY from the environment
5
6
sandbox = client.sandboxes.create_sandbox(
7
    name="my-sandbox",
8
    image="ghcr.io/islo-labs/islo-runner:latest",
9
)
10
11
started = client.sandboxes.exec_in_sandbox(
12
    sandbox_name=sandbox.name,
13
    command=["echo", "Hello from sandbox"],
14
)
15
16
while True:
17
    result = client.sandboxes.get_exec_result(
18
        sandbox_name=sandbox.name,
19
        exec_id=started.exec_id,
20
    )
21
    if result.status in {"completed", "failed", "timeout"}:
22
        break
23
    time.sleep(1)
24
25
print(result.exit_code, result.stdout)
26
27
client.sandboxes.delete_sandbox(sandbox_name=sandbox.name)

Async client

For asyncio-based code, import AsyncIslo instead — the method surface is identical, but every call is awaitable:

1
import asyncio
2
from islo import AsyncIslo
3
4
async def main():
5
    client = AsyncIslo()  # picks up ISLO_API_KEY from the environment
6
7
    sandbox = await client.sandboxes.create_sandbox(
8
        name="my-sandbox",
9
        image="ghcr.io/islo-labs/islo-runner:latest",
10
    )
11
12
    started = await client.sandboxes.exec_in_sandbox(
13
        sandbox_name=sandbox.name,
14
        command=["echo", "Hello from sandbox"],
15
    )
16
17
    while True:
18
        result = await client.sandboxes.get_exec_result(
19
            sandbox_name=sandbox.name,
20
            exec_id=started.exec_id,
21
        )
22
        if result.status in {"completed", "failed", "timeout"}:
23
            break
24
        await asyncio.sleep(1)
25
26
    print(result.exit_code, result.stdout)
27
28
    await client.sandboxes.delete_sandbox(sandbox_name=sandbox.name)
29
30
asyncio.run(main())

SDKs are also available for TypeScript (npm install @islo-labs/sdk) and Go (go get github.com/islo-labs/go-sdk).

Use the CLI

Prefer driving Islo from your terminal? Install the CLI:

$
curl -fsSL https://islo.dev/install.sh | bash

Authenticate

Log in to Islo using your browser:

$
islo login

This command:

1. Starts a local server on port 9876
2. Opens your browser to the authentication page
3. Completes OAuth authentication via Descope
4. Stores tokens securely in your OS keychain

Initialize your project

Set up Islo for your project:

$
islo init

This interactive wizard:

1. Creates an islo.yaml configuration file (or use --template <name> for a starter).
2. Detects languages and dependencies in your project (Python, Node, etc.) and proposes setup_scripts entries for them.

Use a sandbox

Create and connect to a sandbox with a single command:

$
islo use my-sandbox

This will:

1. Create a sandbox if it doesn’t exist
2. Open an interactive shell session

Options:

Example with custom image:

$
islo use dev-sandbox -i ghcr.io/islo-labs/islo-runner:latest

Execute commands

Run a command directly in the sandbox:

$
islo use my-sandbox -- echo "Hello from sandbox"

Output:

Hello from sandbox

Run Python code:

$
islo use my-sandbox -- python3 -c "print('Safe execution!')"

The -- separator tells Islo that everything after it is the command to run.

Cleanup

When you’re done, remove the sandbox:

$
islo rm my-sandbox -f

The -f flag forces removal without confirmation.

Complete CLI example

$
# Install
$
curl -fsSL https://islo.dev/install.sh | bash
$
$
# Login
$
islo login
$
$
# Initialize project (optional but recommended)
$
islo init
$
$
# Use sandbox (creates if needed, opens shell)
$
islo use my-sandbox
$
$
# Or run commands directly
$
islo use my-sandbox -- echo "Hello from sandbox"
$
islo use my-sandbox -- python3 -c "print('Safe execution!')"
$
$
# List sandboxes
$
islo ls
$
$
# Cleanup
$
islo rm my-sandbox -f

Next Steps

• Configure your project with islo.yaml
• Learn all CLI commands
• Browse Islo Recipes for copy-paste SDK and agent examples (gateway allowlists, Playwright, S3 mounts, Claude Code in a sandbox, and more)
• Troubleshoot common issues