solari-sandbox (Python)

Python SDK for Solari Sandboxes — fast, ephemeral code sandboxes (micro-VMs) with a code interpreter, filesystem, ports, and git. Mirrors the TypeScript @solarisdk/sandbox package.

Capabilities and limits at a glance: https://docs.getsolari.com/sdk-capabilities.

Install

pip install solari-sandbox

Quickstart

import asyncio, os
from solari_sandbox import SandboxClient

async def main():
    client = SandboxClient(api_key=os.environ["SOLARI_API_KEY"])
    sb = await client.create(template="base")
    try:
        await sb.connect()
        result = await sb.run_code("print(6 * 7)")
        print("".join(r.text or "" for r in result.results if r.type == "stdout"))   # -> 42
    finally:
        await sb.kill()
        await client.aclose()

asyncio.run(main())

SandboxClient(...) accepts api_key, base_url (default https://api.getsolari.com; pass https://api-sta.getsolari.com for staging), and call_timeout_ms. The same slr_live_… key authenticates against both the browser and desktop/sandbox APIs. run_code returns a RunCodeResult: its results list holds items of type "stdout", "stderr" or "result" (plus charts and error).

Releasing sandboxes

A sandbox keeps running (and billing) until its idle timeout unless you release it. kill() does that; async with (or with, for the synchronous client) calls it for you on every exit path:

async with await sandboxes.create() as sbx:
    await sbx.commands.run("echo", args=["hi"])
# killed here

A process that ends with a sandbox it never killed or closed prints a one-line reminder at exit. Timeouts are in milliseconds: idle_timeout_ms is the rolling idle window, and commands.run(..., timeout_ms=) the deadline for one command (result.timedOut says it was cut off; the default is 600 000 ms).

Idle policy

One setting says what happens as a sandbox sits idle. Offsets run from the last activity and must increase:

sbx = await sandboxes.create(idle_policy="park@30s,hibernate@2m,pause@5m,delete@1d")
# or: format_idle_policy(park="30s", pause="5m", delete="1d")

park freezes the sandbox (free, wakes in milliseconds), hibernate checkpoints it and frees the slot, pause snapshots it and frees the slot (connect resumes it), and delete destroys it (a paused sandbox is deleted at most 27 days after the pause). A policy with park or hibernate and nothing after gets a pause added 24 hours later; the sandbox view's idlePolicy shows what was applied. Do not combine it with idle_timeout_ms or the idle keys of lifecycle (the gateway answers 400); autoResume still applies.

Synchronous use

Not running asyncio? SyncSandboxClient takes the same arguments and hands back synchronous handles: every method runs to completion on the client's own event loop and returns its value (create, connect, start and create_desktop all return such handles).

import os
from solari_sandbox import SyncSandboxClient

with SyncSandboxClient(api_key=os.environ["SOLARI_API_KEY"]) as client:
    sb = client.create(template="base")
    try:
        sb.connect()
        result = sb.run_code("print(6 * 7)")
        print("".join(r.text or "" for r in result.results if r.type == "stdout"))   # -> 42
        print(sb.files.list("/")[0].name, sb.metrics().cpuPct)
    finally:
        sb.kill()

One consequence of sharing one loop: output callbacks such as on_stdout fire while a call is running on the handle (for example inside handle.wait()), not between calls; async with on a sync handle is not supported.

Restarting a stopped sandbox

When the guest powers itself off the sandbox goes to state stopped; the host keeps its disk. start() boots it again (a cold boot: processes and memory are gone, files on disk are kept) and returns a live handle on the fresh control URL:

sb = await client.start(sandbox_id)       # sync client: sb = client.start(sandbox_id) (a sync handle)
await sb.connect()

Calling it on an already-running sandbox is fine. Errors carry .status and .code: 409 NotStopped (a paused sandbox needs resume), 409 StartInProgress (poll get until it is running), 409 StoppedDiskMissing / StoppedDiskUnsafe / GoldenMismatch / DiskPlatformMismatch / DiskShaMismatch / DiskExceedsSpec / DiskOwnerMismatch (the host cannot start this disk), 409 HostCapabilityMissing (the host pool is not armed for start; not retryable), 500 StartFailed (the sandbox stays stopped with its disk, so calling again is safe), 502 StartHostError (host unreachable, retryable), NoCapacityError (503 NoCapacity or StartTimeout, retryable) and ConcurrencyLimitError (429). A stopped sandbox reports state == "stopped" from get; every other route on it answers 409 SandboxStopped (only get and kill still work). start() is not retried automatically. The gateway route is POST /sandboxes/:id/start.

Docs: https://getsolari.com