axilio 0.1.1__tar.gz

axilio-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish to PyPI
+
+# Fires when a backend/vX.Y.Z tag lands on the repo. Builds the wheel
+# + sdist for that revision and uploads them to PyPI.
+#
+# Tag origin: the tag-on-merge.yml workflow creates the tag on every
+# push to main that moves pyproject.toml's version (AXI-590). The
+# version was itself stamped by the regen workflow from
+# backend/internal/version/version.go via the spec — so by the time
+# this workflow fires, SDK version, tag, and the backend revision
+# that produced the spec are all in lockstep.
+#
+# Auth: `PYPI_API_TOKEN` repo secret. Generated at
+# pypi.org/manage/account/token, scoped to the `axilio` project.
+# The first publish (0.1.0) registers the project name on PyPI; once
+# that's done, subsequent uploads inherit project-scope.
+#
+# If the secret is unset, the upload step fails — visible failure
+# beats a silent skip that masks a broken publish path forever.
+
+on:
+  push:
+    tags:
+      - 'backend/v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build + upload ${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v4
+        with:
+          # The push event targets the tag itself; checkout@v4 reads
+          # `github.ref` by default which is `refs/tags/backend/vX.Y.Z`.
+          # No extra config needed — just verify.
+          ref: ${{ github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify tag version matches pyproject.toml
+        # Belt-and-braces: tag-on-merge.yml derives the tag FROM
+        # pyproject.toml, so they should always agree. If a future
+        # workflow change breaks that invariant we'd rather fail
+        # loudly here than ship a mis-versioned wheel.
+        run: |
+          # Tag is like `backend/v0.1.0`; strip the prefix.
+          TAG_VERSION="${GITHUB_REF_NAME#backend/v}"
+          FILE_VERSION=$(awk -F'"' '/^version = ".+"/{print $2; exit}' pyproject.toml)
+          if [[ "$TAG_VERSION" != "$FILE_VERSION" ]]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml ($FILE_VERSION)"
+            exit 1
+          fi
+          echo "tag $GITHUB_REF_NAME matches pyproject.toml $FILE_VERSION ✓"
+
+      - name: Install build tools
+        run: pip install --upgrade build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Validate artifacts
+        run: twine check dist/*
+
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        # twine returns nonzero if PyPI rejects (incl. duplicate file
+        # uploads — re-tagging the same version is operator error,
+        # not silent-success territory). Caller can re-run the
+        # workflow after fixing the underlying issue.
+        run: twine upload --non-interactive dist/*

axilio-0.1.1/.github/workflows/quality.yml

@@ -0,0 +1,53 @@
+name: Quality
+
+# Black + ruff + mypy with versions pinned in pyproject.toml's [dev]
+# extras. Versions match axilioai/axilio's python_checks.yml so a PR
+# that's clean here is clean there and vice versa — bumping in one
+# place without the other will drift; see AXI-588's ticket body for
+# why we mirror manually rather than sharing a script.
+#
+# Generated code under src/axilio/_generated/ is excluded from all
+# three tools via pyproject.toml — the regen workflow replaces it
+# wholesale on each backend deploy, so any formatting opinions we
+# inflict on it get reverted next regen.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Black + Ruff + MyPy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dev deps
+        run: pip install -e '.[dev]'
+
+      # No --auto-fix in CI; humans run the fixer locally and commit.
+      # All three checks run even if an earlier one fails (`if: always()`)
+      # so a single CI run surfaces every category at once instead of
+      # forcing the contributor to push-fix-push-fix once per tool.
+
+      - name: black --check
+        run: black --check src/axilio tests
+
+      - name: ruff check
+        if: always()
+        run: ruff check src/axilio tests
+
+      - name: mypy
+        if: always()
+        run: mypy src/axilio tests

axilio-0.1.1/.github/workflows/regen.yml

@@ -0,0 +1,171 @@
+name: SDK Regenerate
+
+# Fires when the axilio monorepo's publish-sdk-spec job lands a new
+# *production* spec. Steps:
+#
+#   1. Pull the just-committed specs/production/openapi.json.
+#   2. Run scripts/regen.sh against it — replaces src/axilio/_generated/
+#      with the freshly regenerated package.
+#   3. Stamp pyproject.toml's version field from info.version.
+#   4. If anything moved, open a PR. Merging it tags + publishes
+#      via tag-on-merge.yml + publish.yml.
+#
+# Staging dispatches are intentionally ignored. The publish-sdk-spec
+# job on axilio still PUTs specs/staging/openapi.json on each staging
+# deploy for audit + visibility, but no regen PR opens — staging may
+# carry endpoints prod doesn't have yet, and publishing a staging-
+# driven SDK would give customers types for endpoints that 404 in
+# production. The SDK should reflect what's actually live behind
+# api.axilio.ai, which is the production deploy.
+#
+# Two triggers reach this workflow on each spec sync:
+#   - The Contents-API push from axilio commits a file under specs/**,
+#     which surfaces here as a normal push.
+#   - The explicit repository_dispatch openapi-spec-updated arrives
+#     immediately after, carrying axilio_sha for the regen PR.
+#
+# We listen for the dispatch only and ignore the push — the dispatch
+# carries the upstream SHA we want in the PR title / body. Without it
+# the PR would just say "spec changed" with no link back to which
+# backend revision drove the change.
+
+on:
+  repository_dispatch:
+    types: [openapi-spec-updated]
+  # Manual trigger only allows production. Local staging regen is
+  # `bash scripts/regen.sh staging` on a developer laptop — useful for
+  # eyeballing what's coming, doesn't produce a PR or publish.
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  regenerate:
+    name: Regenerate production SDK
+    # Skip everything when the dispatch carries any environment other
+    # than production. Job-level `if` short-circuits before the rest
+    # of the workflow consumes any minutes.
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      github.event.client_payload.environment == 'production'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dev deps
+        run: pip install -e '.[dev]'
+
+      - name: Regenerate SDK
+        run: bash scripts/regen.sh production
+
+      - name: Stamp pyproject.toml version from spec
+        id: stamp
+        # Reads info.version from specs/production/openapi.json (driven
+        # by backend/internal/version/version.go via axilio's wireRoutes
+        # — see AXI-589) and writes it into pyproject.toml so the SDK
+        # version matches the backend revision that produced the spec.
+        #
+        # Reads from the file rather than from client_payload.backend_version
+        # so manual workflow_dispatch runs work without needing the
+        # dispatch payload — the spec on disk is the source of truth.
+        run: |
+          BACKEND_VERSION=$(jq -r '.info.version' "specs/production/openapi.json")
+          if [[ "$BACKEND_VERSION" == "null" || -z "$BACKEND_VERSION" ]]; then
+            echo "::error::Could not read info.version from specs/production/openapi.json"
+            exit 1
+          fi
+          python3 - <<PY
+          import pathlib, re
+          v = "$BACKEND_VERSION"
+          p = pathlib.Path("pyproject.toml")
+          text = p.read_text()
+          # Use subn so we can tell "regex didn't match" (count == 0,
+          # an error — file lost its version line somehow) apart from
+          # "regex matched but replacement was a no-op" (count == 1,
+          # `new == text`, which is the common case where the spec's
+          # version equals what's already in pyproject.toml and there's
+          # nothing to do).
+          new, count = re.subn(r'^version = ".*"$', f'version = "{v}"', text, count=1, flags=re.MULTILINE)
+          if count == 0:
+              raise SystemExit("pyproject.toml has no top-level version line to stamp")
+          if new != text:
+              p.write_text(new)
+          PY
+          echo "backend_version=$BACKEND_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Stamped pyproject.toml version = $BACKEND_VERSION"
+
+      - name: Detect changes
+        id: diff
+        # Open a PR if EITHER the generated code OR the stamped version
+        # moved. pyproject.toml-only changes happen when the backend's
+        # version constant bumped without altering the public surface
+        # (rare but possible — e.g. a meaningful internal refactor the
+        # engineer wanted to mark). Still worth a release.
+        run: |
+          if git diff --quiet src/axilio/_generated/ pyproject.toml; then
+            echo "Generated code + version unchanged; nothing to PR."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Changes detected; opening PR."
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open regen PR
+        if: steps.diff.outputs.changed == 'true'
+        # peter-evans/create-pull-request finds an existing PR on the
+        # same branch and updates it instead of opening duplicates, so
+        # successive dispatches for the same backend version don't
+        # accumulate PRs. Branch name keys on the backend version
+        # because the merged regen PR will be tagged backend/vX.Y.Z
+        # and a second commit on top would tag the same version —
+        # confusing.
+        uses: peter-evans/create-pull-request@v6
+        env:
+          BACKEND_VERSION: ${{ steps.stamp.outputs.backend_version }}
+          AXILIO_SHA: ${{ github.event.client_payload.axilio_sha || 'manual' }}
+          AXILIO_REF: ${{ github.event.client_payload.axilio_ref || 'manual' }}
+        with:
+          branch: regen/v${{ env.BACKEND_VERSION }}
+          base: main
+          title: "chore(sdk): regenerate from backend v${{ env.BACKEND_VERSION }}"
+          commit-message: |
+            chore(sdk): regenerate from backend v${{ env.BACKEND_VERSION }}
+
+            Auto-generated by .github/workflows/regen.yml.
+            Source: axilio@${{ env.AXILIO_SHA }} (${{ env.AXILIO_REF }})
+          body: |
+            Auto-generated by the SDK regen pipeline. Merging this PR
+            tags `backend/v${{ env.BACKEND_VERSION }}` on main and
+            publishes that tag to PyPI via publish.yml.
+
+            | | |
+            |---|---|
+            | Backend version | `${{ env.BACKEND_VERSION }}` |
+            | Axilio source SHA | `${{ env.AXILIO_SHA }}` |
+            | Axilio source ref | `${{ env.AXILIO_REF }}` |
+            | Spec path | `specs/production/openapi.json` |
+            | Generator | `openapi-python-client` |
+
+            ## What changed
+
+            The production OpenAPI spec moved since the last regen.
+            `src/axilio/_generated/` and `pyproject.toml`'s version
+            field have been updated to match. Nothing hand-written
+            changed in this PR.
+
+            ## What still needs human attention
+
+            Resource methods in `src/axilio/billing/`,
+            `src/axilio/devices/`, etc. don't change automatically
+            when the spec moves — those are the hand-written wrappers
+            around the generated typed call functions. If this regen
+            surfaces new endpoints (or removes some), the corresponding
+            resource wrapper needs to be updated by hand in a
+            follow-up PR.

axilio-0.1.1/.github/workflows/tag-on-merge.yml

@@ -0,0 +1,67 @@
+name: Tag on Version Bump
+
+# Fires when a push to main moves pyproject.toml. Reads the version
+# out of the file and creates an annotated `backend/vX.Y.Z` tag
+# pointing at the merge commit.
+#
+# The receiver workflow (regen.yml) stamps pyproject.toml's version
+# field to match the backend revision that produced the spec. Each
+# merged regen PR is therefore a single deterministic version bump,
+# and this workflow turns that into a tag — the PyPI publish workflow
+# (AXI-591) hooks the tag to ship to PyPI.
+#
+# Idempotent: if a tag for the current version already exists, the
+# workflow skips quietly. Important because someone might land a
+# README-only PR that re-touches pyproject.toml's body without moving
+# the version line — we don't want to fail those.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    name: Tag backend/vX.Y.Z
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Read version from pyproject.toml
+        id: ver
+        run: |
+          # awk over a regex is enough for the single canonical
+          # `version = "..."` line. Avoids depending on tomllib /
+          # tomlkit and works on every runner Python.
+          VERSION=$(awk -F'"' '/^version = ".+"/{print $2; exit}' pyproject.toml)
+          if [[ -z "$VERSION" ]]; then
+            echo "::error::Could not read version from pyproject.toml"
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Read version: $VERSION"
+
+      - name: Create + push tag (idempotent)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          TAG="backend/v${VERSION}"
+
+          # Check remote first — local clone post-checkout may or may
+          # not have fetched all tags depending on the runner cache.
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q "${TAG}"; then
+            echo "tag ${TAG} already exists on origin; nothing to do"
+            exit 0
+          fi
+
+          git config user.name "axilio-bot"
+          git config user.email "bot@axilio.ai"
+          git tag -a "${TAG}" -m "Backend version ${VERSION}"
+          git push origin "${TAG}"
+          echo "tagged ${TAG} on $(git rev-parse HEAD)"

axilio-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[dev]'
+      - name: Test
+        run: pytest -q

axilio-0.1.1/.gitignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build / dist
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/

axilio-0.1.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: axilio
+Version: 0.1.1
+Summary: Axilio Python SDK — manage workflows, runs, devices, usage, and control devices remotely
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: black==25.1.0; extra == 'dev'
+Requires-Dist: mypy==1.16.0; extra == 'dev'
+Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff==0.12.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Axilio Python SDK
+
+The official Python SDK for [Axilio](https://axilio.ai). One pip package covers account management, device discovery, allocation, and the full remote control surface (tap, swipe, OCR, screenshot, ...).
+
+## Installation
+
+```bash
+pip install axilio
+```
+
+## Quick start
+
+```python
+from axilio import Client
+
+# Reads AXILIO_API_KEY from the environment.
+client = Client()
+
+# One-shot device session — allocate, connect, control, clean up.
+with client.devices.session(platform="android") as device:
+    device.tap(540, 1200)
+    device.type("hello world")
+    device.screenshot("after.png")
+```
+
+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
+
+```bash
+export AXILIO_API_KEY=ax_live_...
+```
+
+Or pass explicitly:
+
+```python
+client = Client(api_key="ax_...")
+client = Client(api_key="ax_...", base_url="https://staging-api.axilio.ai")
+```
+
+Generate keys from the [Axilio dashboard](https://app.axilio.ai/settings/api-keys). 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.devices` | `available()`, `locations()`, `supported_apps()`, `allocate()`, `connect()`, `deallocate()`, `session()` | Sandbox mode 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](https://github.com/axilioai/axilio/blob/main/.docs/sdk-design.md) in the monorepo.
+
+## Errors
+
+All errors raised by the SDK subclass `axilio.AxilioError`:
+
+```python
+from axilio 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.

axilio-0.1.1/README.md

@@ -0,0 +1,113 @@
+# Axilio Python SDK
+
+The official Python SDK for [Axilio](https://axilio.ai). One pip package covers account management, device discovery, allocation, and the full remote control surface (tap, swipe, OCR, screenshot, ...).
+
+## Installation
+
+```bash
+pip install axilio
+```
+
+## Quick start
+
+```python
+from axilio import Client
+
+# Reads AXILIO_API_KEY from the environment.
+client = Client()
+
+# One-shot device session — allocate, connect, control, clean up.
+with client.devices.session(platform="android") as device:
+    device.tap(540, 1200)
+    device.type("hello world")
+    device.screenshot("after.png")
+```
+
+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
+
+```bash
+export AXILIO_API_KEY=ax_live_...
+```
+
+Or pass explicitly:
+
+```python
+client = Client(api_key="ax_...")
+client = Client(api_key="ax_...", base_url="https://staging-api.axilio.ai")
+```
+
+Generate keys from the [Axilio dashboard](https://app.axilio.ai/settings/api-keys). 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.devices` | `available()`, `locations()`, `supported_apps()`, `allocate()`, `connect()`, `deallocate()`, `session()` | Sandbox mode 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](https://github.com/axilioai/axilio/blob/main/.docs/sdk-design.md) in the monorepo.
+
+## Errors
+
+All errors raised by the SDK subclass `axilio.AxilioError`:
+
+```python
+from axilio 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.