Documentation

Quickstart

Get a computer-use agent controlling FreeCAD in under 5 minutes.

1. Install the SDK

pip install isle-sdk

2. Get an API key

export ISLE_API_KEY=isle_...

3. Create a sandbox

from isle import Client

isle = Client()

sandbox = isle.sandboxes.create("freecad")
sandbox.wait_until_ready()

print(f"Sandbox ready: {sandbox.id}")
print(f"Stream: {sandbox.stream_url}")

4. Control the environment

Use familiar computer-use primitives — screenshots, mouse, keyboard, and file transfer.

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

# Mouse control
sandbox.mouse.click(500, 300)
sandbox.mouse.move(200, 400)
sandbox.mouse.scroll(0, -500)

# Keyboard control
sandbox.keyboard.type("8 mm")
sandbox.keyboard.keypress(["CTRL", "S"])

# File transfer
sandbox.files.upload("input.step")
sandbox.files.download("/output/result.step")

5. Stop and resume

# Stop archives the sandbox — files persist, billing pauses
sandbox.stop()

# Resume restores the sandbox on fresh hardware
sandbox.resume()  # blocks until running

Full example

A complete script that creates a FreeCAD sandbox, uploads a file, performs some operations, and downloads the result.

from isle import Client

isle = Client()  # uses ISLE_API_KEY env var

# Create environment
sandbox = isle.sandboxes.create("freecad")
sandbox.wait_until_ready()

# Upload input
sandbox.files.upload("part.step")

# Your agent takes over here
# Use sandbox.screen.screenshot() to see the screen
# Use sandbox.mouse and sandbox.keyboard to interact

# Download result
sandbox.files.download("/output/part.step", "output.step")

# Stop when done — resume later with sandbox.resume()
sandbox.stop()

Available environments

freecadCAD

FreeCAD environment for 3D modeling, parametric design, and engineering tasks. Supports STEP, IGES, STL, OBJ, and native FreeCAD formats.

libreofficeOffice

LibreOffice environment for document processing, spreadsheets, and presentations. Includes Writer, Calc, and Impress.

Checkpoints & recovery

Isle automatically checkpoints your working artifact every 30 seconds. If the application crashes, the UI gets stuck, or the agent escapes the intended workflow, Isle restores the last known-safe state and restarts the application.

# Manual checkpoint
sandbox.checkpoint()

# Check monitor health
status = sandbox.monitor_status()
print(status)  # {"status": "running", "checkpoints": 5, ...}

# List checkpoints
checkpoints = sandbox.checkpoints()

# Manually trigger recovery
sandbox.recover()  # restores last safe checkpoint + restarts app

Automatic recovery triggers

Application crashed or disappeared
UI stuck (no visual change for ~60s)
Agent escaped to a blocked application

Application containment

Each environment is scoped to its intended application. Terminal, browser, package manager, and system settings are blocked to keep the agent focused on the task.

API reference

Method	Description
`sandboxes.create(env)`	Create a new sandbox
`sandboxes.list()`	List all sandboxes
`sandboxes.get(id)`	Get a sandbox by ID
`sandbox.wait_until_ready()`	Wait for sandbox to start
`sandbox.screen.screenshot()`	Capture screenshot (PNG bytes)
`sandbox.mouse.click(x, y)`	Click at coordinates
`sandbox.mouse.move(x, y)`	Move cursor
`sandbox.mouse.scroll(x, y)`	Scroll
`sandbox.keyboard.type(text)`	Type text
`sandbox.keyboard.keypress(["CTRL", "S"])`	Press key combo
`sandbox.files.upload(path)`	Upload a file
`sandbox.files.download(path)`	Download a file
`sandbox.checkpoint()`	Create a safe checkpoint of the artifact
`sandbox.recover()`	Restore last safe checkpoint and restart app
`sandbox.checkpoints()`	List all checkpoints
`sandbox.download_checkpoint(id)`	Get presigned download URL for a checkpoint
`sandbox.events()`	List command trace events
`sandbox.recording_url()`	Get presigned URL for session recording
`sandbox.monitor_status()`	Get monitor/health status
`sandbox.stop()`	Stop and archive sandbox
`sandbox.resume()`	Resume a stopped sandbox

Need help?

Email us at [email protected]