Lizard SDK for Python
Run commands, work with files and execute code in Linux sandboxes (Firecracker microVMs). The SDK also manages Lizard apps, databases, storage and projects.
Install
Requires Python 3.10+. The Python client is synchronous.
pip install lizard-sdk
Create an API key and project at lizard.build, then set:
export LIZARD_API_KEY="your-api-key"
Create a sandbox
Save this as quickstart.py. Replace my-project with your project's ID, slug or unique name, then run python quickstart.py.
from lizard import Lizard
lizard = Lizard(project="my-project")
with lizard.create("base", timeout_ms=300_000) as sandbox:
sandbox.fs.write("/tmp/hello.txt", "Hello from Lizard!")
result = sandbox.process.exec_("cat /tmp/hello.txt")
if result.exit_code != 0:
raise RuntimeError(result.stderr)
print(result.stdout)
The context manager kills the sandbox when the block ends, including when it raises an error. If you create a sandbox without with, call sandbox.kill() in a finally block.
Machine size
Sandboxes come in three sizes: small (2 vCPU / 4 GB, $0.0162/h), medium (4 vCPU / 8 GB, $0.0324/h, the default) and large (8 vCPU / 16 GB, $0.0648/h). Billing is flat by size, per second while the sandbox runs; measured CPU/RAM are not charged, egress is free, and volumes bill separately.
sandbox = lizard.create("base", size="large")
Stream command output
Inside the with block above:
result = sandbox.process.exec_(
'printf "hello\\n"',
timeout_ms=30_000,
on_stdout=lambda chunk: print(chunk, end=""),
on_stderr=lambda chunk: print(chunk, end=""),
)
if result.exit_code != 0:
raise RuntimeError(result.stderr)
Desktop (computer use)
The desktop template runs XFCE and Chromium you can watch in a browser and an agent can drive:
from lizard import Sandbox
with Sandbox.create("desktop", project="my-project") as sandbox:
info = sandbox.desktop.start() # open info.url in a browser
sandbox.desktop.open_url("https://example.com")
sandbox.desktop.click(640, 400)
sandbox.desktop.type("hello")
sandbox.desktop.press("Return")
png: bytes = sandbox.desktop.screenshot()
Treat info.url like a credential: anyone with it can see and control the desktop. Share info.view_only_url when someone only needs to watch. See the desktop guide.
Run Python
Run Python with the interpreter template. Each process command starts a separate Python process, so Python variables do not survive between calls; use CodeSandbox (below) when they should.
from lizard import Sandbox
sandbox = Sandbox.create("interpreter", project_id="proj_123", timeout_ms=300_000)
try:
result = sandbox.process.exec_("python -c 'print(2 ** 10)'")
print(result.stdout, result.stderr, result.exit_code)
finally:
sandbox.kill()
To run code snippets with state carried between calls, use CodeSandbox (runCode / run_code): it boots the interpreter template and runs Python in a persistent Jupyter kernel inside the sandbox. See Run code.
Run code with state (CodeSandbox)
CodeSandbox boots the interpreter template and runs Python in a persistent Jupyter kernel inside the sandbox: variables survive between calls, the value of the last expression and matplotlib charts come back in results, and exceptions in error.
from lizard import CodeSandbox
with CodeSandbox.create(project_id="proj_123") as sandbox:
sandbox.run_code("x = 21")
run = sandbox.run_code("x * 2")
print(run.results[0].data) # "42"
language="bash" (and "javascript" where node is installed; the interpreter template does not ship it) runs each call as a fresh process with no shared state.
Configuration
The SDK reads LIZARD_API_KEY and, optionally, LIZARD_API_URL (default: https://lizard.build). You can also pass api_key and api_url to the constructor or static sandbox methods.
Pass timeout_ms to create() to set the sandbox lifetime. The default is five minutes. timeout_ms on process.exec_() or run_code() controls that call, not the sandbox lifetime.
Runtime limits
Each sandbox is a Firecracker microVM with its own kernel. Use volumes mounted at /workspace to keep files after a sandbox ends. pause()/resume() keep memory and running processes; snapshot() is ready in about 2 s and Sandbox.restore() starts a copy in about 0.4 s; fork() clones a running sandbox. File watching and sandbox log streaming are not available on Firecracker sandboxes yet, volumes cannot be resized yet, and a sandbox with a volume attached cannot be forked. See the snapshot guide.
get_host() returns a hostname without https://; the port is private, so send sandbox.access_token as the X-Lizard-Access-Token header (or use expose_port(), which also returns a browser url carrying the token). File writes accept text or bytes (binary is sent exactly); read_bytes() supports binary downloads.
Current command and lifetime limits
Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The command options envs, workdir and user apply to that command; create-time envs apply to every command, and create-time metadata is returned by getInfo() / get_info().
The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: timeoutMs: 0 at creation disables expiration; a positive value sets a deadline. setTimeout accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
Learn more
1 maintainer
Metadata
1 maintainer
Release files for lizard-sdk 0.1.59
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| lizard_sdk-0.1.59.tar.gz | 58.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| lizard_sdk-0.1.59-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 119.5 kB
Release files / lizard_sdk-0.1.59.tar.gz
| Download URL | lizard_sdk-0.1.59.tar.gz |
|---|---|
| Size | 58.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
40d84df523eb222b97ac8333d49cfa3aa68b98c607ab483fc8e73c9a06b3e5fa
|
|
BLAKE2b-256 checksum How to use checksums |
dcf4707e506b79ba6bef752b7b7b91fefa978584628d1b8fd0cbe27045c6687d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logRelease files / lizard_sdk-0.1.59-py3-none-any.whl
| Download URL | lizard_sdk-0.1.59-py3-none-any.whl |
|---|---|
| Size | 61.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2088fffd8ee4993a1f50835f8041a293a38b7165cedfadb98ddd27ceb43bb5cd
|
|
BLAKE2b-256 checksum How to use checksums |
6d63df5e429adb54c212350a6213aede32d171f47a0d0b1904e1cd0ca0a163ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency log
