# Isle

> Application-ready desktop environments for AI computer-use agents.

Isle provides managed sandbox environments running real desktop applications (KiCad and FreeCAD) that AI agents can control via screenshots, mouse, keyboard, and file transfer. Each sandbox includes automatic checkpointing, crash recovery, and application containment.

## Links

- [Documentation](https://www.tryisle.com/docs)
- [REST API reference](https://www.tryisle.com/docs/rest)
- [Astra integration](https://www.tryisle.com/docs#astra)
- [Execution endpoint reference](https://www.tryisle.com/docs/rest#execution)
- [Full LLM context](https://www.tryisle.com/llms-full.txt)

## REST API

Use any HTTP client with base URL `https://www.tryisle.com/api` and
`Authorization: Bearer isle_...`. No SDK is required. Create with
`POST /sandboxes`, JSON `{"environment":"kicad","retain":true}`, and a required
`Idempotency-Key` header. Reuse the key and body after a lost response; poll
`GET /sandboxes/{id}` until `status="running"` before input or files.
Screenshots return PNG bytes from `GET /sandboxes/{id}/screenshot`.
`DELETE /sandboxes/{id}` stops; `POST /sandboxes/{id}/resume` resumes;
`DELETE /sandboxes/{id}/destroy` permanently deletes after stopping.
See the REST reference and full LLM context for curl examples, schemas,
file transfer, checkpoints, recordings, deletion tracking, and safe retries.

## Persistent execution

These features are available on newly created KiCad and FreeCAD environments. Existing environments retain their original image.
The execution API is model-neutral and works with any HTTP-capable agent.

On execution-enabled API/image versions, `GET /sandboxes/{id}/capabilities`
discovers persistent Python support. `POST /sandboxes/{id}/executions` submits
a bounded cell with a UUID execution ID and the current generation;
`GET /sandboxes/{id}/executions/{executionId}?generation=...` retrieves it.
Cancel with `POST /sandboxes/{id}/executions/{executionId}/cancel` and
`{"expected_generation":"ORIGINAL_GENERATION"}`.
`GET /sandboxes/{id}/observation` returns PNG data with dimensions and generation.
Check capabilities first: older images do not support these endpoints. After
an uncertain submission, inspect its original ID before sending more work.

The `default` namespace includes PyAutoGUI, time, log(), and display(). Combine
short GUI action sequences with Python imports, project files in
`/home/user/work`, installed CLI commands, and screenshots. Variables persist;
Python descendants pause between cells. Code is limited to 64 KiB and 120
seconds; inspect capability limits and output_truncated. Only one desktop
operation runs at a time. Cancellation/timeouts verify process and held-input
cleanup, reset Python state, and leave completed edits intact. Refresh
capabilities after a generation change; a client wait timeout is not cancellation.

Observations include timestamp, screen/screenshot dimensions, scale factor,
and active_document=null. Retained observations use screenshot storage;
Python-emitted images remain in bounded runtime records. Keep model-provider
credentials in the client process and send PNGs as model image inputs.

## Repository shell bridge

From a repository checkout with Isle SDK 0.2.0 or later,
Codex or any agent with shell access can use examples/codex/desktop.py against
an existing execution-enabled sandbox. Start with:
`python examples/codex/desktop.py --sandbox-id SANDBOX_ID capabilities`
and `python examples/codex/desktop.py --sandbox-id SANDBOX_ID observe`.
The bridge uses host-side ISLE_API_KEY, makes no model API calls, saves actual
PNG/text/result files, and records execution IDs and generations before writes.
See examples/codex/README.md in the checkout for run/poll/get/cancel/download
and independent KiCad/FreeCAD verification. It is not a command installed by
the published SDK. Unknown submissions must be inspected without replay.

Bounded KiCad and FreeCAD mechanical tasks have been validated through Codex
using the deployed API, independent saved-file checks, and visual review.
See examples/kicad/README.md and examples/freecad/README.md for application workflows.

## Astra example

The source examples combine Astra Responses with saved-copy KiCad CLI ERC,
DRC, and schematic-parity checks. New KiCad environments include the official
kipy IPC client through execution cells; check for kicad_ipc in capabilities
and see examples/kicad/README.md. An Isle MCP connector is not included. Keep OPENAI_API_KEY in the client, outside desktop scripts and files.
After SDK installation, install examples/astra/requirements.txt and
run examples/astra/run.py with a sandbox ID. This optional Responses API adapter
has offline coverage; its own live API run remains pending. Codex-driven
application checks do not establish this adapter's live behavior.

## Python SDK

Install from PyPI (Python 3.9 or later):
`python -m pip install isle-sdk`

Use isle-sdk 0.2.0 or later for capabilities(), execution, and screen.observe().
Existing environments retain their original image; create a new environment
and check capabilities before submitting code.

```python
from isle import Client

isle = Client()  # uses ISLE_API_KEY env var
sandbox = isle.sandboxes.create(
    "kicad", name="My project", idempotency_key="my-project-v1"
)
sandbox.wait_until_ready()

image = sandbox.screen.screenshot()
sandbox.mouse.click(500, 300)
sandbox.keyboard.type("100nF")
sandbox.keyboard.keypress(["CTRL", "S"])

sandbox.files.upload("input.kicad_sch")
sandbox.files.download("/home/user/work/board.kicad_pcb")

sandbox.stop()
sandbox.wait_until_stopped()
deletion = sandbox.destroy()
tracking_id = deletion["provider_deletion_tracking_id"]
erasure = isle.provider_deletions.wait(tracking_id, timeout=300)
```

## Environments

- `kicad` -- EDA: schematic capture, PCB layout, electronics design
- `freecad` -- CAD: 3D modeling, parametric design, engineering

## Key Concepts

Save GUI projects and transfer files through `/home/user/work` on current
images. KiCad uses `project.kicad_pro`; checkpoints bundle the workspace's
project, schematic, PCB, and local assets in `project.kicad.zip`. Save all
editors first. An unsaved project returns `artifact_not_found` with its expected
path. Legacy settings-only checkpoints remain downloadable but are labeled
non-restorable. See the full reference for limits and excluded transient files.

- **Sandbox**: A running desktop environment with a specific application. Create, control, stop, and resume.
- **Checkpoints**: Automatic snapshots every 30 seconds. Used for crash recovery and safe rollback.
- **Recovery**: The monitor handles application failures using the latest safe checkpoint. On execution-enabled images, an unchanged screenshot alone is not treated as a hung application; process failures and cell deadlines still apply.
- **Containment**: Each sandbox is scoped to its application. Terminal, browser, and system-settings windows are blocked. Execution-enabled images permit Python and installed CLI tools inside the restricted worker, without external network access.
- **Deletion**: `destroy()` starts durable cleanup and returns immediately when
  provider erasure is still pending. Use `provider_deletions.get()` or
  `provider_deletions.wait()` to distinguish verified completion, failure, and
  a result that requires manual verification.