Metadata-Version: 2.3
Name: islo
Version: 0.2.0
Summary: Typed Python SDK for the Islo sandbox platform
Keywords: islo,sdk,sandbox,ai-agents,api-client
Author: Islo Labs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.21.2
Requires-Dist: pydantic>=1.9.2
Requires-Dist: typing-extensions>=4.0.0
Requires-Python: >=3.10
Project-URL: Homepage, https://islo.dev
Project-URL: Repository, https://github.com/islo-labs/islo-sdk
Project-URL: Documentation, https://docs.islo.dev
Project-URL: Issues, https://github.com/islo-labs/islo-sdk/issues
Description-Content-Type: text/markdown

# Islo Python SDK

Typed Python SDK for the [Islo](https://islo.dev) sandbox platform. Create, manage, and execute code in isolated VM-based sandboxes.

## Installation

```bash
pip install islo
```

## Quick Start

```python
from islo import Islo

# Automatically reads ISLO_API_KEY from environment
client = Islo()

# Create a sandbox
sandbox = client.sandboxes.create_sandbox(
    name="my-sandbox",
    image="ubuntu:22.04",
    vcpus=2,
    memory_mb=4096,
)

# Execute a command
result = client.sandboxes.exec_in_sandbox(
    sandbox_name=sandbox.name,
    command=["echo", "hello world"],
)
print(result.exit_code)

# Clean up
client.sandboxes.delete_sandbox(sandbox_name=sandbox.name)
```

## Authentication

### Environment variable (recommended)

```bash
export ISLO_API_KEY="your-api-key"
```

```python
client = Islo()  # Picks up ISLO_API_KEY automatically
```

### Explicit token

```python
client = Islo(token="your-api-key")
```

### Auto-refreshing token provider

```python
from islo import Islo
from islo.custom import SyncTokenProvider

provider = SyncTokenProvider(
    base_url="https://api.islo.dev",
    access_key="your-access-key",
)
client = Islo(token=provider)
```

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ISLO_API_KEY` | Bearer token for authentication | — |
| `ISLO_BASE_URL` | API base URL | `https://api.islo.dev` |

## Async Support

```python
import asyncio
from islo import AsyncIslo

async def main():
    client = AsyncIslo()
    sandboxes = await client.sandboxes.list_sandboxes()
    print(f"Found {len(sandboxes.items)} sandboxes")

asyncio.run(main())
```

## Development

```bash
# Install dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check .
uv run ruff format --check .
```

### Regenerating the SDK

The SDK is generated from the Islo API's OpenAPI spec using [Fern](https://buildwithfern.com/):

```bash
# Export fresh OpenAPI spec from islo-web-api
cd ../islo-web-api
uv run python -c "import json; from src.api import app; json.dump(app.openapi(), open('../islo-sdk/fern/openapi/openapi.json', 'w'), indent=2)"

# Regenerate
cd ../islo-sdk
fern generate --group python-sdk

# Run tests to verify
uv run pytest tests/ -v
```

Custom code in `src/islo/client.py` and `src/islo/custom/` is preserved across regenerations via `.fernignore`.
