Isle Python SDK

Application environments for AI agents.

Install

Requires Python 3.9 or later.

python -m pip install isle-sdk

The package is named isle-sdk on PyPI and imported as isle. Get an API key from the Isle dashboard.

The SDK automatically generates an idempotency key and reuses it for one transport retry. Pass idempotency_key= when the same create operation may be retried by a different process.

Quickstart

from isle import Client, IsleAPIError

isle = Client(api_key="isle_...")

# Create a KiCad sandbox
sandbox = isle.sandboxes.create(
    "kicad",
    name="Power supply board",
    idempotency_key="power-supply-board-v1",
)
sandbox.wait_until_ready()

# Upload a file
sandbox.files.upload("schematic.kicad_sch")

# Take a screenshot
image = sandbox.screen.screenshot()

# Control the mouse and keyboard
sandbox.mouse.click(500, 300)
sandbox.keyboard.type("100nF")
sandbox.keyboard.keypress(["CTRL", "S"])

# Download results
sandbox.files.download("/home/user/work/board.kicad_pcb")

# Stop (archives the sandbox, can be resumed later)
sandbox.stop()
sandbox.wait_until_stopped()

# Resume a stopped sandbox
sandbox.resume()

# Lifecycle failures are returned by the API and retained on the environment
sandbox.refresh()
if sandbox.last_error:
    print(sandbox.last_error, sandbox.last_error_at)

# Retrieve timestamped error history (newest first)
for error in sandbox.errors():
    print(error["source"], error["message"], error["created_at"])

# Recording metadata distinguishes a complete recording from the bounded
# 512 MiB / six-hour / low-disk partial recording policy.
recording = sandbox.recording_info()
print(recording["url"], recording["truncated"], recording["truncation_reason"])

# Permanently delete a stopped sandbox and its retained data
sandbox.stop()
sandbox.wait_until_stopped()
sandbox.destroy(timeout=120)

API failures raise IsleAPIError. Its status_code, error, and metadata attributes can be used to handle failures without parsing an exception string. For example, a provisioning failure includes its recoverable metadata["environment_id"] when the API created a record before the remote environment failed to start.

Environments

• kicad - EDA environment with KiCad
• freecad - CAD environment with FreeCAD

Development

From an authorized Isle repository checkout:

python -m pip install -e ./sdk/python
python -m unittest discover -s sdk/python/tests