axilio 0.2.0

Axilio Python SDK — manage workflows, runs, devices, usage, and control devices remotely

Axilio Python SDK

The official Python SDK for Axilio. One pip package covers account management, device discovery, allocation, and the full remote control surface (tap, swipe, OCR, screenshot, ...).

Installation

pip install axilio

Quick start

from axilio.platform import Client
from axilio.drivers import MobileDriver

# Reads AXILIO_API_KEY from the environment.
client = Client()

# One-shot device session — allocate, drive, clean up.
with client.mobile.session(platform="android") as device:
    driver = MobileDriver(device)
    driver.find_text("Sign in").tap()
    driver.type("hello world")
    driver.screenshot("after.png")

client.mobile.allocate() (or session()) gives you a DeviceHandle; you wrap it with a driver from axilio.drivers to control it. The platform SDK acquires the device, the driver drives it.

The same code runs unmodified inside an Axilio sandbox VM — when you schedule a workflow in the dashboard, Hephaestus injects scoped auth and the paired Atlas endpoint at boot, and the Client auto-detects sandbox mode. No if local: ... else: ... branches in your code.

Authentication

export AXILIO_API_KEY=ax_live_...

Or pass explicitly:

client = Client(api_key="ax_...")
client = Client(api_key="ax_...", base_url="https://staging-api.axilio.ai")

Generate keys from the Axilio dashboard. API keys are scoped to one organization — multi-org users mint one key per org.

Resources

Resource	Methods	Notes
client.billing	balance(), subscription(), invoices(), upgrade(), downgrade()	Reads everywhere; upgrade/downgrade local-only
client.usage	metrics(), sessions()	Both modes
client.api_keys	list(), create(), revoke()	Local-only
client.org	current(), members(), invite(), remove_member()	Reads everywhere; member writes local-only
client.mobile	available(), locations(), supported_apps(), allocate(), deallocate(), session()	Returns a DeviceHandle; wrap with axilio.drivers.MobileDriver. Sandbox short-circuits allocate()
client.workflows	list(), get(), create(), update(), delete()	Both modes
client.runs	list(), get(), create(), cancel()	Both modes

For the full method surface, type signatures, and the device control vocabulary, see the SDK design doc in the monorepo.

Errors

All errors raised by the SDK subclass axilio.AxilioError:

from axilio.platform import Client, NotFoundError, RateLimitError, SandboxPermissionError

client = Client()

try:
    run = client.runs.get("run_does_not_exist")
except NotFoundError:
    print("run not found")
except RateLimitError:
    # backoff + retry
    ...
except SandboxPermissionError:
    # tried a local-only write from inside a sandbox VM
    ...

Exception	HTTP	Notes
UnauthorizedError	401	API key missing, malformed, or rejected
NotFoundError	404	Resource doesn't exist or isn't visible
RateLimitError	429	Retry after backoff
ServerError	5xx	Transient; safe to retry
SandboxPermissionError	—	Local-only operation attempted from sandbox
AllocationMismatchError	—	Sandbox kwargs don't match the bound allocation
AxilioError	other	Catch-all

Configuration

Env var	Description
AXILIO_API_KEY	API key for authentication. Required in local mode.
AXILIO_BASE_URL	Override the API host (defaults to https://api.axilio.ai).
AXILIO_SANDBOX_TOKEN	Scoped sandbox token. Injected by Hephaestus inside a sandbox VM; not set in local mode.
AXILIO_ATLAS_ENDPOINT	Paired Atlas endpoint inside a sandbox VM. Injected by Hephaestus.

Constructor kwarg	Default	Description
api_key	AXILIO_API_KEY env, then AXILIO_SANDBOX_TOKEN (sandbox mode)	Bearer token
base_url	AXILIO_BASE_URL env, then https://api.axilio.ai	API host
timeout	30.0	Request timeout in seconds
max_retries	3	Retry budget for 429 + 5xx (TODO: wire)
retry_base_delay	0.5	Exponential backoff base

Status

This is the v0 scaffold. The public surface (Client + resource classes) matches the design doc; method bodies are stubs (NotImplementedError) until codegen lands the typed wire calls. The codegen pipeline is driven by repository_dispatch from the monorepo's publish-sdk-spec job on each backend deploy — see .github/workflows/sdk-regenerate.yml (landing next).

What's not here

• Async client — sync only for v0.
• In-sandbox device drivers (the implementation that actually drives a phone screen) — those live inside Atlas + the runner image, not in this SDK.
• SSE / WebSocket subscriptions for live run events — REST only; SSE lands when a consumer needs it.