> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Quick Start

> Get up and running with Islo in 5 minutes. Install, authenticate, create a sandbox, and run your first command.

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

> **Tip**
>
> Working with an AI agent? Install the [Islo skills](https://github.com/islo-labs/skills) with `npx skills add islo-labs/skills`. Use **factory-lines** for factory automations and **platform** for sandboxes, snapshots, gateways, and the SDK.

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

```bash
uv add islo
```

```bash
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:

```python
import time
from islo import Islo

client = Islo()  # picks up ISLO_API_KEY from the environment

sandbox = client.sandboxes.create_sandbox(
    name="my-sandbox",
    image="ghcr.io/islo-labs/islo-runner:latest",
)

started = client.sandboxes.exec_in_sandbox(
    sandbox_name=sandbox.name,
    command=["echo", "Hello from sandbox"],
)

while True:
    result = client.sandboxes.get_exec_result(
        sandbox_name=sandbox.name,
        exec_id=started.exec_id,
    )
    if result.status in {"completed", "failed", "timeout"}:
        break
    time.sleep(1)

print(result.exit_code, result.stdout)

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:

```python
import asyncio
from islo import AsyncIslo

async def main():
    client = AsyncIslo()  # picks up ISLO_API_KEY from the environment

    sandbox = await client.sandboxes.create_sandbox(
        name="my-sandbox",
        image="ghcr.io/islo-labs/islo-runner:latest",
    )

    started = await client.sandboxes.exec_in_sandbox(
        sandbox_name=sandbox.name,
        command=["echo", "Hello from sandbox"],
    )

    while True:
        result = await client.sandboxes.get_exec_result(
            sandbox_name=sandbox.name,
            exec_id=started.exec_id,
        )
        if result.status in {"completed", "failed", "timeout"}:
            break
        await asyncio.sleep(1)

    print(result.exit_code, result.stdout)

    await client.sandboxes.delete_sandbox(sandbox_name=sandbox.name)

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:

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

### Authenticate

Log in to Islo using your browser:

```bash
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:

```bash
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:

```bash
islo use my-sandbox
```

This will:

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

**Options:**

| Option        | Default                                | Description            |
| ------------- | -------------------------------------- | ---------------------- |
| `-i, --image` | `ghcr.io/islo-labs/islo-runner:latest` | Container image to use |
| `--cpu`       | (none)                                 | Number of vCPUs        |
| `--memory`    | (none)                                 | Memory in MB           |
| `--disk`      | (none)                                 | Disk size in GB        |

**Example with custom image:**

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

### Execute commands

Run a command directly in the sandbox:

```bash
islo use my-sandbox -- echo "Hello from sandbox"
```

**Output:**

```
Hello from sandbox
```

Run Python code:

```bash
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:

```bash
islo rm my-sandbox -f
```

The `-f` flag forces removal without confirmation.

### Complete CLI example

```bash
# 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](/configuration/islo-yaml/) with `islo.yaml`
* [Use factory lines](/concepts/automations/) for multi-stage, scheduled, and event-triggered work
* [Learn all CLI commands](/cli/)
* Point your AI agent at [islo-labs/skills](https://github.com/islo-labs/skills) — **factory-lines** for automations, **platform** for sandboxes and gateways
* [Troubleshoot common issues](/cli/troubleshooting/)