Lizard SDK
Firecracker microVM sandboxes for AI agents — boot a full Linux environment in milliseconds, run code, write files, and expose ports, all from your agent or CI pipeline.
Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be snapshotted and resumed instantly, so long-running agent sessions survive restarts without re-running setup.
Install
# JavaScript / TypeScript
npm install @lizard-build/sdk
# Python
pip install lizard-sdk
Quickstart
JavaScript / TypeScript
import { Sandbox } from '@lizard-build/sdk'
// Boot a microVM from the 'base' template (Debian + Node.js 20)
const sandbox = await Sandbox.create('base')
// Write a file directly into the microVM filesystem
await sandbox.fs.write('/app/server.js', `
const http = require('http')
http.createServer((_, res) => res.end('hello from Lizard')).listen(3000)
`)
// Execute a process inside the microVM
await sandbox.process.exec('node /app/server.js &')
// Get a public HTTPS URL for port 3000 inside the sandbox
const url = sandbox.getHost(3000)
console.log(`Live at https://${url}`)
// Tear down the microVM when done
await sandbox.kill()
Python
from lizard import Sandbox
# Boot a Python microVM from the 'code-interpreter-v1' template
sandbox = Sandbox.create("code-interpreter-v1")
# Write a script into the microVM filesystem
sandbox.fs.write("/app/main.py", """
import http.server, socketserver
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.end_headers()
self.wfile.write(b"hello from Lizard")
with socketserver.TCPServer(("", 3000), Handler) as httpd:
httpd.serve_forever()
""")
# Execute a process inside the microVM
sandbox.process.exec_("python /app/main.py &")
print(f"Live at https://{sandbox.get_host(3000)}")
sandbox.kill()
Pause and Resume
Sandboxes can be snapshotted mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to checkpoint and continue across separate invocations.
// Boot and set up the environment once
const sandbox = await Sandbox.create('code-interpreter-v1')
await sandbox.process.exec('pip install numpy pandas scikit-learn')
const id = sandbox.sandboxId
await sandbox.pause()
// Later — resume instantly from the snapshot (no reinstall needed)
const resumed = await Sandbox.connect(id)
const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
console.log(result.stdout)
await resumed.kill()
from lizard import Sandbox
sandbox = Sandbox.create("code-interpreter-v1")
sandbox.process.exec_("pip install numpy pandas scikit-learn")
sandbox_id = sandbox.sandbox_id
sandbox.pause()
# Resume later — environment is exactly as left
resumed = Sandbox.connect(sandbox_id)
result = resumed.process.exec_("python -c 'import sklearn; print(sklearn.__version__)'")
print(result.stdout)
resumed.kill()
API
Sandbox.create(template?, opts?)
Boot a new Lizard microVM. Built-in templates: base (Debian + Node.js 20) and code-interpreter-v1 (Python 3.11 + Node.js 20). Custom templates can be pushed via lizard push.
const sandbox = await Sandbox.create('base')
const sandbox = await Sandbox.create('code-interpreter-v1', { timeoutMs: 10 * 60 * 1000 })
Sandbox.connect(sandboxId, opts?)
Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed from its last snapshot.
Sandbox.list(opts?)
List all running sandboxes for the authenticated account.
sandbox.fs
Read and write files inside the microVM filesystem.
| Method | Description |
|---|---|
fs.write(path, data) |
Write a file (string or bytes) |
fs.read(path) |
Read a file as a string |
fs.list(path) |
List directory contents |
fs.remove(path) |
Delete a file or directory |
fs.makeDir(path) |
Create a directory and parents |
sandbox.process
Execute commands inside the microVM.
| Method | Description |
|---|---|
process.exec(cmd, opts?) |
Run a command and wait for it to finish |
exec returns { stdout, stderr, exitCode } (JS) or ProcessResult (Python). In Python the method is named exec_ because exec is a reserved keyword.
sandbox.getHost(port)
Returns a public HTTPS URL for a port listening inside the microVM — no tunneling required.
await sandbox.process.exec('npx -y serve -p 3000 &')
const url = sandbox.getHost(3000)
// https://{sandboxId}-3000.sandbox.{region}.onlizard.com
sandbox.pause() / sandbox.resume()
Snapshot and restore the microVM state. Useful for checkpointing long agent sessions.
sandbox.kill()
Terminate the sandbox and release all resources.
sandbox.setTimeout(ms)
Extend or reduce the sandbox timeout.
Environment Variables
| Variable | Description |
|---|---|
LIZARD_API_KEY |
API key (required — get one at lizard.build) |
LIZARD_API_URL |
Override the API base URL (default: https://lizard.build) |
The X-API-Key header is used for all authenticated requests.
Deploy What You Build
Once your agent has produced a working app inside a sandbox, deploy it as a persistent Lizard service — no Dockerfile needed:
lizard up
Your sandbox template becomes the base, your code ships as a layer on top, and Lizard manages the Firecracker microVM fleet from there.
License
Apache-2.0
1 maintainer
Metadata
1 maintainer
Release files for lizard-sdk 0.1.20
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.20.tar.gz | 9.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| lizard_sdk-0.1.20-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 23.2 kB
Release files / lizard_sdk-0.1.20.tar.gz
| Download URL | lizard_sdk-0.1.20.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
481ec5abe693ca913b236d11229c82996bd1389196431133af7ebe18bc2a9fe5
|
|
BLAKE2b-256 checksum How to use checksums |
e192b2e30c83507e3a32a8ae2fc23baa1f38d8f6c34f7b82146648844629e62c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Jul 27, 2026.
Transparency logRelease files / lizard_sdk-0.1.20-py3-none-any.whl
| Download URL | lizard_sdk-0.1.20-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
db6a6c7ba32a17500068730e63d911838844729a1b063d38a0b0cab86186093b
|
|
BLAKE2b-256 checksum How to use checksums |
fdbb1e2bb1aafeae8381458201fd2635914d784e5494d998fdd145647db88745
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Jul 27, 2026.
Transparency log
