Solari

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

PackageProductClasses
solari-browserCloud browsersSolari, BrowserSession
solari-desktopVMs (GUI desktops)DesktopClient, Desktop
solari-sandboxSandboxes (headless)SandboxClient, Sandbox
pip install solari-desktop     # desktops (computer-use)
pip install solari-sandbox     # code sandboxes
pip install solari-browser     # browsers

solari-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.

solari-browser needs Python 3.10 or newer
The package metadata says 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.
One key across every package
The same slr_live_… key authenticates solari-desktop, solari-sandbox, and solari-browser, all against https://api.getsolari.com.
Why the patchright pin looks wrong
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.

OptionTypeDefaultClientNotes
api_keystrrequiredallSent as Authorization: Bearer. Raises if empty.
base_urlstrsee notesallSolari: 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.
regionstr"us-west"SolariOnly "us-west" today. Unknown region raises.
timeout_msint90_000SolariPer attempt, not per call.
max_attemptsint2SolariTotal attempts. 2 means one retry.
backoff_msint500SolariFixed sleep between attempts, not exponential.
call_timeout_msint300_000DesktopClient, SandboxClientPer-RPC timeout given to handles this client creates.
httphttpx.AsyncClientown clientDesktopClient, SandboxClientReuse an existing client. When omitted, one is created and owned by the SDK.
kind"sandbox" | "desktop""sandbox"SandboxClientThe flavour create() makes.
No environment variables are read
No constructor reads 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.
Async first, with sync wrappers
Every client is async, built on 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).
The two packages retry differently
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

ClassPackagePurpose
Solarisolari-browserBrowser entry point: sessions, profiles, replays.
BrowserSessionsolari-browserA live browser + its session. Returned by launch().
DesktopClientsolari-desktopVM entry point: create, connect, pause, resume, destroy.
Desktopsolari-desktopA live GUI session: mouse, keyboard, screenshots, apps.
SandboxClientsolari-sandboxSandbox entry point: create, list, snapshots, volumes.
TemplateClient, Imagesolari-core (re-exported by solari-sandbox and solari-desktop)Build custom templates from a declarative image recipe.
Sandboxsolari-sandboxA live headless session: commands, code, files, git. Shared base of Desktop.