Leap0 Python SDK

Python SDK for Leap0, enterprise-grade cloud sandboxes for AI agents.

Launch isolated sandboxes in ~200ms. Give every agent its own compute, filesystem, and network boundary while your agents run safely.

Installation

pip install leap0

Or install from source:

git clone https://github.com/leap0dev/leap0-python.git
cd leap0-python
pip install .

Requirements

• Python >= 3.10
• A Leap0 API key

Getting an API key

1. Sign up at app.leap0.dev.
2. Copy your API key from the dashboard.
3. Set it as an environment variable:

export LEAP0_API_KEY="your-api-key"

Alternatively, pass it directly when creating a client:

from leap0 import Leap0Client

client = Leap0Client(api_key="your-api-key")

Quick Start

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()

try:
    result = sandbox.process.execute(command="echo hello from leap0")
    print(result.stdout.strip())
finally:
    sandbox.delete()
    client.close()

Or use the client as a context manager:

from leap0 import Leap0Client

with Leap0Client(api_key="your-api-key") as client:
    sandbox = client.sandboxes.create()
    result = sandbox.process.execute(command="echo hello from the sandbox")
    print(result.stdout.strip())
    sandbox.delete()

Features

Code Interpreter

Stateful REPL sessions for Python and TypeScript. Variables persist across calls, with Matplotlib charts auto-captured as PNG and SVG.

from leap0 import DEFAULT_CODE_INTERPRETER_TEMPLATE_NAME

sandbox = client.sandboxes.create(template_name=DEFAULT_CODE_INTERPRETER_TEMPLATE_NAME)
result = sandbox.code_interpreter.execute(code="x = 42", language="python")

# Stream output in real-time
for event in sandbox.code_interpreter.execute_stream(
    code="for i in range(5): print(i)", language="python"
):
    print(event.type, event.data)

Filesystem

Full filesystem access inside every sandbox. List, read, write, edit, search, and more.

sandbox.filesystem.write_file(path="/workspace/hello.txt", content="Hello!")
content = sandbox.filesystem.read_file(path="/workspace/hello.txt")
tree = sandbox.filesystem.tree(path="/workspace", max_depth=2)
matches = sandbox.filesystem.grep(path="/workspace", pattern="TODO")

Git

Clone repos, create branches, stage files, commit, push, and pull, all inside the sandbox.

sandbox.git.clone(url="https://github.com/user/repo.git", path="/workspace/repo")
status = sandbox.git.status(path="/workspace/repo")
sandbox.git.add(path="/workspace/repo", files=["README.md"])
sandbox.git.commit(path="/workspace/repo", message="Update README")
sandbox.git.push(path="/workspace/repo")

Process Execution

Execute one-shot shell commands inside a running sandbox.

result = sandbox.process.execute(command="ls -la /workspace")
print(result.stdout)

interpolated = sandbox.process.execute(
    command="echo $NAME from ${PLACE}",
    cwd="/workspace/$NAME",
    env={"NAME": "leap0", "PLACE": "sandbox"},
)
print(interpolated.stdout)

Interactive Terminal (PTY)

Interactive terminal sessions over WebSocket with persistent state.

session = sandbox.pty.create(cols=120, rows=30, cwd="/home/user")
conn = sandbox.pty.connect(session.id)
conn.send("ls -la\n")
print(conn.recv().decode())
conn.close()

Language Server Protocol (LSP)

Start language servers for Python and TypeScript to get completions, symbols, and document lifecycle events.

sandbox.lsp.start(language_id="python", path_to_project="/workspace")
sandbox.lsp.did_open(
    language_id="python",
    path_to_project="/workspace",
    uri="file:///workspace/main.py",
)
completions = sandbox.lsp.completions(
    language_id="python",
    path_to_project="/workspace",
    uri="file:///workspace/main.py",
    line=10,
    character=5,
)

SSH Access

Generate and manage time-bound SSH credentials for direct sandbox access.

ssh = sandbox.ssh.create_access()
print(ssh.hostname, ssh.port, ssh.username)

Desktop Automation

Control a graphical desktop inside the sandbox. Take screenshots, move the pointer, click, type, and record the screen.

from leap0 import DEFAULT_DESKTOP_TEMPLATE_NAME

sandbox = client.sandboxes.create(template_name=DEFAULT_DESKTOP_TEMPLATE_NAME)
sandbox.desktop.move_pointer(x=500, y=300)
sandbox.desktop.click(button=1)
screenshot = sandbox.desktop.screenshot(image_format="png")

Snapshots

Save and restore sandbox state at any point.

snapshot = client.snapshots.create(sandbox, name="my-checkpoint")
paused_snapshot = client.snapshots.pause(sandbox, name="paused-checkpoint")
restored = client.snapshots.resume(snapshot_name="my-checkpoint")

Custom Templates

Create reusable sandbox templates from any container image.

template = client.templates.create(
    name="my-template",
    image="my-registry.com/my-image:latest",
)
sandbox = client.sandboxes.create(template_name="my-template")

Network Controls

Fine-grained egress control per sandbox. Allow-list specific domains or IP ranges, or block all outbound traffic entirely.

sandbox = client.sandboxes.create(
    network_policy="custom",
    allowed_domains=["api.example.com"],
)

API Reference

The SDK is organized into service clients accessible from the top-level Leap0Client:

Client	Description
client.sandboxes	Create, get, pause, and delete sandboxes
client.snapshots	Create snapshots, pause a sandbox into a snapshot, resume from a snapshot, and delete snapshots
client.templates	Create, rename, and delete templates
client.filesystem	File operations (read, write, edit, search, tree, etc.)
client.git	Git operations (clone, commit, push, pull, branch, etc.)
client.process	Execute shell commands
client.pty	Interactive terminal sessions over WebSocket
client.lsp	Language Server Protocol for code intelligence
client.ssh	SSH credential management
client.code_interpreter	Code execution with streaming support
client.desktop	Graphical desktop control and screen recording

Configuration

For most cases, use Leap0Client() and let it read LEAP0_API_KEY from the environment.

Use Leap0Config when you want a reusable validated config object:

from leap0 import Leap0, Leap0Config

config = Leap0Config(
    api_key="your-api-key",  # or set LEAP0_API_KEY env var
    base_url="https://api.leap0.dev",
    timeout=300,
)
client = Leap0(config)

Option	Default	Description
api_key	LEAP0_API_KEY env var	API key for authentication
base_url	https://api.leap0.dev	API base URL
sandbox_domain	sandbox.leap0.dev	Domain for sandbox-scoped endpoints
timeout	300	HTTP client timeout in seconds

Examples

See the examples/ directory for complete usage examples:

• quickstart.py - Basic code execution
• async_quickstart.py - Async client quickstart
• async_filesystem_and_git.py - Async file and Git operations
• async_code_interpreter_stream.py - Async streaming code execution output
• async_pty.py - Async interactive terminal session
• code_interpreter_stream.py - Streaming code execution output
• filesystem_and_git.py - File and Git operations
• pty.py - Interactive terminal session
• desktop.py - Desktop GUI automation
• snapshots.py - Save and restore sandbox state
• ssh.py - Generate and validate SSH access

Development

pip install -e ".[dev]"
pytest

Documentation

Full documentation is available at leap0.dev/docs.

License

Apache License 2.0. See LICENSE for details.