Python SDK
The official Python clients for the three Solari products: browsers (a connected Playwright Browser in the cloud), VMs (GUI desktops you drive with mouse, keyboard, and screenshots), and sandboxes (headless microVMs for commands, code, and files). Browsers ship as solari-browser, VMs as solari-desktop, and sandboxes as solari-sandbox (both depending on solari-core).
Installation
| Package | Product | Classes |
|---|---|---|
solari-browser | Cloud browsers | Solari, BrowserSession |
solari-desktop | VMs (GUI desktops) | DesktopClient, Desktop |
solari-sandbox | Sandboxes (headless) | SandboxClient, Sandbox |
pip install solari-desktop # desktops (computer-use)
pip install solari-sandbox # code sandboxes
pip install solari-browser # browserssolari-desktop and solari-sandbox need Python >=3.9; solari-browser needs Python 3.10 or newer (see the callout below). solari-browser depends on httpx and patchright. solari-desktop and solari-sandbox each depend on solari-core (the shared transport, session handles, and types), which pip installs automatically, mirroring npm’s @solarisdk/core + @solarisdk/desktop + @solarisdk/sandbox split.
Requires-Python >=3.9, but its patchright dependency needs Python 3.10+. On Python 3.9, pip silently resolves to the old solari-browser 0.1.2, which the browser pool rejects with HTTP 428 on every launch(). Use Python 3.10 or newer for solari-browser, and check with pip show solari-browser that you got the current release.slr_live_… key authenticates solari-desktop, solari-sandbox, and solari-browser, all against https://api.getsolari.com.solari-browser pins patchright>=1.62,<1.63, a range rather than ==1.62.2. That is deliberate: the pool’s wire-protocol gate compares major.minor only, so any 1.62.x client talks to its 1.62.2 server (the Node and Python patchright release trains can differ at the patch level). A mismatched major.minor makes every launch() fail with HTTP 428. You do not need patchright install chromium, because the browser runs remotely.Getting Started
Launch a browser
import asyncio
from solari_browser import Solari
async def main():
async with Solari(api_key="slr_live_...") as solari:
async with await solari.launch(stealth=True, proxy="us") as browser:
page = await browser.new_page()
await page.goto("https://example.com")
print(await page.title())
# browser exit releases the session; solari exit closes the client
asyncio.run(main())Create a VM
import asyncio
from solari_desktop import DesktopClient
async def main():
async with DesktopClient(api_key="slr_live_...") as client:
vm = await client.create(template="workstation", resolution="1280x720")
# the control channel opens on the first call; no connect() needed
await vm.keyboard.type("hello")
png = await vm.screenshot()
await vm.kill()
asyncio.run(main())Create a sandbox
import asyncio
from solari_sandbox import SandboxClient
async def main():
async with SandboxClient(api_key="slr_live_...") as client:
sbx = await client.create(template="base")
# the control channel opens on the first call; no connect() needed
r = await sbx.commands.run("echo", args=["hi"])
print(r.stdout) # "hi"
await sbx.kill()
asyncio.run(main())VMs and sandboxes at once
There is no unified client, mirroring @solarisdk/desktop and @solarisdk/sandbox on npm, each package exposes its own client. Import DesktopClient from solari-desktop and SandboxClient from solari-sandbox; both accept the same slr_live_… key and re-export the shared handles and types from solari-core.
from solari_desktop import DesktopClient
from solari_sandbox import SandboxClient
desktops = DesktopClient(api_key="slr_live_...")
sandboxes = SandboxClient(api_key="slr_live_...")
vm = await desktops.create(template="workstation")
sbx = await sandboxes.create(template="base")Configuration
Every client takes keyword-only constructor arguments. api_key is always required.
| Option | Type | Default | Client | Notes |
|---|---|---|---|---|
api_key | str | required | all | Sent as Authorization: Bearer. Raises if empty. |
base_url | str | see notes | all | Solari: resolved from region; setting it ignores region. DesktopClient / SandboxClient (and their sync flavours): optional, default https://api.getsolari.com; pass https://api-sta.getsolari.com for staging. TemplateClient and VolumeClient (built on their own) still require it. |
region | str | "us-west" | Solari | Only "us-west" today. Unknown region raises. |
timeout_ms | int | 90_000 | Solari | Per attempt, not per call. |
max_attempts | int | 2 | Solari | Total attempts. 2 means one retry. |
backoff_ms | int | 500 | Solari | Fixed sleep between attempts, not exponential. |
call_timeout_ms | int | 300_000 | DesktopClient, SandboxClient | Per-RPC timeout given to handles this client creates. |
http | httpx.AsyncClient | own client | DesktopClient, SandboxClient | Reuse an existing client. When omitted, one is created and owned by the SDK. |
kind | "sandbox" | "desktop" | "sandbox" | SandboxClient | The flavour create() makes. |
os.environ. Pass api_key explicitly. base_url defaults to production on the sandbox, desktop and browser clients; only TemplateClient and VolumeClient have no default, so pass it there.httpx. solari-sandbox ships SyncSandboxClient and solari-desktop ships SyncDesktopClient; both also re-export SyncVolumeClient and SyncTemplateClient from solari-core. These drive a private event loop and return synchronous handles: every method of the Desktop / Sandbox they hand back (and of commands, files, git, …) runs to completion and returns its result, so there is nothing to await. Output callbacks such as on_stdout fire while a call is running, not between calls, and async with is not supported on a sync handle (use with).solari-browser retries 502, 503, 504, and 507, with a fixed backoff_ms pause and max_attempts total tries. 507 is included although the browser gateway never emits one; it’s the desktop gateway’s transient InsufficientCapacity, kept so the client is correct regardless of which gateway build it reaches. solari-desktop retries only idempotent requests (GET, DELETE, or anything carrying an idempotency key) on network errors, on 502, 503, 504 and 507, or when the error body says retryable: true. A plain 500 is not retried: only the listed statuses are, not “any 5xx”. It retries up to 5 times with exponential backoff plus jitter. A 429 is retried only when the gateway marks it errorType: "rate_limited" (it waits out Retry-After, up to 30 s); a quota_exceeded 429 such as ConcurrencyLimitError is never retried. The browser client does not retry a 429 unless the gateway marks it retryable on a request that is safe to replay.Reference
| Class | Package | Purpose |
|---|---|---|
Solari | solari-browser | Browser entry point: sessions, profiles, replays. |
BrowserSession | solari-browser | A live browser + its session. Returned by launch(). |
DesktopClient | solari-desktop | VM entry point: create, connect, pause, resume, destroy. |
Desktop | solari-desktop | A live GUI session: mouse, keyboard, screenshots, apps. |
SandboxClient | solari-sandbox | Sandbox entry point: create, list, snapshots, volumes. |
TemplateClient, Image | solari-core (re-exported by solari-sandbox and solari-desktop) | Build custom templates from a declarative image recipe. |
Sandbox | solari-sandbox | A live headless session: commands, code, files, git. Shared base of Desktop. |

