Mesh Storage
Python SDK
Upload files, query ingested data, and read Mesh files from Python
The Alloy Python SDK gives you a normal Python path into Mesh Storage. Use it from notebooks, scripts, backend jobs, CI checks, and internal tools that need to upload recordings or work with data that is already in Mesh.
Mesh still does the same work behind the scenes: files land in object storage and Alloy processes MCAPs into queryable tables. Replay and Inspect work once a file lands. SQL and external tools can read its data once the file shows Ingested.
The SDK is for Python code. If you want to browse files, replay MCAPs, or run ad-hoc SQL without writing code, use the Mesh Storage page and SQL Workbench instead.
What you can do
Quickstart
Install the SDK, upload a run, query rows, and download a file
Upload files
Upload MCAPs and metadata sidecars into uploads/sdk-uploads
Query Mesh data
Run hosted SQL and return rows, Arrow, pandas, Polars, or DuckDB
List and download files
Read Mesh keys and prefixes from Python
The public modules
The SDK exposes two customer-facing modules:
| Module | Use it for |
|---|---|
alloy.storage | Upload files, list Mesh files, and download Mesh files |
alloy.sql | Query ingested Mesh data through hosted SQL |
Keep imports explicit:
from alloy import storage, sqlKeep using the module names in application code. The package root keeps SQL convenience exports, but storage client names stay under alloy.storage so Client and AsyncClient do not collide.
How uploads fit Mesh Storage
SDK uploads land under:
uploads/sdk-uploads/<path>/You choose the <path> part:
from alloy import storage
with storage.connect() as store:
result = store.upload_folder("runs/run-001", path="flights/run-001")
print(result.prefix)
# uploads/sdk-uploads/flights/run-001/After upload, files show up in Mesh Storage like any other uploaded file. Replay and Inspect are available once the file lands. SQL is available after the file shows Ingested.
Sync and async
Both storage and hosted SQL have sync and async clients. Use sync for scripts and notebooks. Use async for services, workers, and tools that already run on an event loop.
from alloy import storage
with storage.connect() as store:
store.upload_file("run.mcap", path="flights/run-001")from alloy import storage
async with storage.async_connect() as store:
await store.upload_file("run.mcap", path="flights/run-001")