Quick Start

This guide walks you through the complete workflow from installation to running your first secure command.

1. Install Islo

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

2. Authenticate

$ islo login

This command:

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

3. Initialize Your Project

Set up Islo for your project:

$ islo init

This interactive wizard:

Creates an islo.yaml configuration file
Detects tools in your project (Python, Node, etc.)
Installs IDE hooks for Cursor or Claude Code

4. Use a Sandbox

Create and connect to a sandbox with a single command:

$ islo use my-sandbox

This will:

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

Options:

Option	Default	Description
`-i, --image`	`python:3.12-slim`	Container image to use
`--cpus`	(none)	Number of vCPUs
`--memory`	(none)	Memory in MB
`--disk`	(none)	Disk size in GB

Example with custom image:

$ islo use dev-sandbox -i docker.io/library/python:3.13-slim

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

6. Cleanup

When you’re done, remove the sandbox:

$ islo rm my-sandbox -f

The -f flag forces removal without confirmation.

Complete 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

7. Use the SDK

Prefer driving Islo from your own code? Install the official SDK and authenticate with an API key from the dashboard.

$ uv add islo

$ export ISLO_API_KEY="your-api-key"

The synchronous client is the default:

1 from islo import Islo
2 
3 client = Islo()  # picks up ISLO_API_KEY from the environment
4 
5 sandbox = client.sandboxes.create_sandbox(
6     name="my-sandbox",
7     image="python:3.12-slim",
8 )
9 result = client.sandboxes.exec_in_sandbox(
10     sandbox_name=sandbox.name,
11     command=["echo", "Hello from sandbox"],
12 )
13 print(result.exit_code)
14 
15 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="python:3.12-slim",
10     )
11     result = await client.sandboxes.exec_in_sandbox(
12         sandbox_name=sandbox.name,
13         command=["echo", "Hello from sandbox"],
14     )
15     print(result.exit_code)
16 
17     await client.sandboxes.delete_sandbox(sandbox_name=sandbox.name)
18 
19 asyncio.run(main())

A TypeScript SDK is also available — npm install @islo-labs/sdk.