solari-runloop-compat 0.1.0__tar.gz

solari_runloop_compat-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/

solari_runloop_compat-0.1.0/BLUEPRINTS.md

@@ -0,0 +1,84 @@
+# Blueprints (Runloop) on Solari: design and status
+
+A Runloop *blueprint* is a reusable devbox image built from a Dockerfile (plus setup commands, file mounts, a build
+context, launch parameters). A Solari *template* is a golden VM snapshot built by running ordered steps inside a VM
+cloned from a base golden (`POST /templates` with a `CompiledImage`: `{base|fromTemplate, packages, steps[]}`,
+`building -> ready|failed`, build logs at `GET /templates/{id}/logs`). So the mapping is "Dockerfile -> recipe", not
+"Dockerfile -> OCI image".
+
+## Level 1: shipped in this PR (client side, no gateway change)
+`solari_runloop/_dockerfile.py` compiles a Dockerfile subset into the existing recipe, and `client.blueprints.*` /
+`sdk.blueprint.*` drive `/templates`. Verified on staging: a Dockerfile + `system_setup_commands` + `file_mounts` blueprint
+builds in ~40 s, a devbox created from it sees the baked files, and the template is deleted afterwards.
+
+| Runloop | Solari |
+|---|---|
+| `dockerfile` `FROM ubuntu/debian[:tag]`, `base`, `workstation` | `base` golden |
+| `base_blueprint_name` / `base_blueprint_id` | `fromTemplate` (name resolved to `tpl_` id) |
+| `RUN` (shell or JSON form) | `{op:"run"}` step (ARGs exported into the command) |
+| `ENV` | `{op:"env"}` step |
+| `WORKDIR`, `ENTRYPOINT`, `CMD` | `{op:"workdir","dir"}`, `{op:"entrypoint"}`, `{op:"cmd"}` |
+| `ARG` + `build_args` | substituted / exported |
+| `system_setup_commands` | `run` steps after the Dockerfile |
+| `file_mounts {path: contents}` | `run` step that base64-writes each file (small files only) |
+| `launch_parameters` size | `cpu`/`memMb` on the template row, same size table as devboxes |
+| status `building / ready / failed` | `building / build_complete / failed` |
+| blueprint id | `templateId` (`tpl_...`); `create(template=)` takes the **id** or a built-in name |
+
+Rejected loudly (`SolariCompatUnsupported`): a `FROM` from a registry outside the allowlist, `FROM scratch`, multi-stage builds,
+`COPY`/`ADD`, `USER`, `VOLUME`, `HEALTHCHECK`, `ONBUILD`, `build_context`, `code_mounts`, `services`, `secrets`.
+
+Findings worth fixing in the gateway docs: `openapi.yaml` shows `{op:"workdir", path}` but the SDKs (and so the
+pipeline) use `{op:"workdir", dir}`; `localFiles` is rejected (`LocalFilesUnsupported`), which is why `COPY` is not in level 1.
+
+## Level 2: `COPY`/`ADD` and `build_context`
+**Shipped in the compat layer (staging-verified) for contexts up to ~700 KB**: `sdk.storage_object.upload_from_dir()` builds a deterministic tar.gz (honouring `.dockerignore`), `build_context=obj.as_build_context()` embeds it in the recipe, and `COPY`/`ADD` become `cp -a` steps from `/tmp/solari-context` (into `/srv/root/...` for imported images). The proper version below replaces the embedding with real objects.
+
+### Proper version (needs bug2's storage objects)
+1. Build context = a storage object (`.tar.gz`, `GET /objects/{id}/download-url`).
+2. New recipe field `contextObjectId` and a new step op `{op:"copy", src, dest, chown?}`; the build VM downloads and extracts the
+   object to `/tmp/build-context`, then `copy` is `cp -a` from there (`ADD` of a local tar = `tar -x`).
+3. Compat layer: `build_context={type:"object", object_id}` passes through; `COPY`/`ADD` translate to `copy` steps;
+   `.dockerignore` is applied client-side when the SDK uploads the directory (`storage_object.upload_from_dir`).
+Gateway work: `contextObjectId` validation (same org), the `copy` op in the build executor, ~2 days; tests for wrong-org objects.
+
+## Level 3a: any public `FROM <image>`, shipped in this PR (compat layer only, staging-verified)
+`FROM python:3.12-alpine`, `FROM node:20`, `FROM ghcr.io/org/img:tag`, and (with `build_args={"SOLARI_IMPORT": "1"}`) `FROM ubuntu`/`debian`
+**as an imported image** instead of the native base. How: the build steps (a) install `crane` (pinned `v0.20.3`, tarball sha256 checked
+at download, the binary's sha256 **re-checked before every use**, the build fails on a mismatch), (b) check the manifest size against
+the cap before downloading, (c) `crane export --platform linux/amd64 <image>` piped into `solari-extract`, a validating tar extractor,
+into `/srv/root`, (d) install `solari-run`, which chroots into `/srv/root` with the Dockerfile's `ENV` (`/etc/solari-env`) and `WORKDIR`
+(`/etc/solari-workdir`). The existing orchestrator snapshots the builder as a normal template. At runtime the compat layer sees
+`/etc/solari-rootdir` and runs `cmd.exec` through `solari-run`, and maps file paths under the root.
+Verified live: `python:3.12-alpine` (musl, `python --version` = 3.12), `debian:bookworm-slim`, `ubuntu:22.04`: the process sees the image's
+`/etc/os-release`, `ENV`, `WORKDIR`, baked files; file API reads are inside the root; a symlink out of the root is refused (403).
+
+| Guard | Where | Test |
+|---|---|---|
+| crane pinned by version + sha256, re-verified at use | `import_steps` | `test_crane_is_pinned_and_checked_at_use` |
+| registry allowlist (docker.io, ghcr.io, public.ecr.aws, gcr.io, quay.io, mcr.microsoft.com); no credentials (`DOCKER_CONFIG` is an empty temp dir) | `_resolve_from` | `test_other_registries_refused`, `..._pinned...` |
+| compressed-size cap 2 GiB (from the manifest, before download), extracted cap 4 GiB, 900 s timeout, 400k members | `solari_sizecheck.py`, `solari_extract.py` | `test_size_cap`, pinned test |
+| tar: absolute names, `..`, write through a symlink out of the root, hardlinks out of the root, device nodes (skipped), setuid/setgid/sticky (stripped) | `solari_extract.py` | `tests/test_extract.py` (10 tests, each fails without its check) |
+| file API never follows a symlink out of the root (guest `realpath` re-check) | `Gateway._abs` | live test |
+| `chroot` is **not** a security boundary here: it is a compatibility layer inside the customer's own microVM, which is the boundary | docs | n/a |
+
+**Loud limits** (also in COMPAT.md): the extractor writes an absolute symlink that points at a directory as a symlink but refuses to write *through* it, so a later member cannot land outside `/srv/root`; the image needs a `/bin/sh` (distroless images fail the build with a clear message); ~2 GB free in the builder
+VM today (the builder disk size is not configurable yet, so big images fail on disk); `ENTRYPOINT`/`CMD` are recorded in `/etc/solari-entrypoint` and
+`/etc/solari-cmd` but **not started**; public registries only; amd64 only; absolute symlinks inside the image resolve against the host in the file API,
+so reading such a path is refused (exec through `solari-run` resolves them correctly); processes from different `exec` calls share the chroot, but there is
+no PID 1/init in the image (no systemd), and a `RUN` that needs a running daemon fails.
+A warning is logged at compile time whenever import mode is used.
+
+## Level 3b: native, for every SDK (assigned to bug1; archi-sandbox's block list applies)
+guest-agent `rootDir` mode (exec chroots, fs ops use a symlink-safe join, rootDir immutable, capabilities dropped), `fromImage` on `POST /templates`
+(org-scoped, registry allowlist, digest pinned at build time and recorded), builder `diskGb` (bounded), the OCI config (Env, WorkingDir, Entrypoint, Cmd, User)
+applied at create. Needs a guest rebake + re-pin before prod. The marker-file contract above keeps 3a templates working.
+
+## Level 3c: real rootfs rebuild (fidelity; later)
+`Dockerfile.sandbox` with `ARG BASE_IMAGE` so a Debian-family image gets systemd as PID 1 and the Solari layer baked in. Only for images that need an init.
+The `python:X` -> `base` + install shortcut stays out unless opted in explicitly.
+
+## Risks
+Untrusted builds (egress, CPU time, disk) need quotas before this is exposed beyond staging; `RUN` steps that rely on BuildKit
+features (`--mount=type=cache`, heredocs) are not supported; blueprint *versioning* (Runloop's immutable ids per build) is
+`tpl_` ids here, so rebuilding under the same name creates a new id.

solari_runloop_compat-0.1.0/COMPAT.md

@@ -0,0 +1,125 @@
+# COMPAT.md: Runloop SDK compatibility (target: runloop_api_client 2.0.0)
+
+## At a glance (2026-10-21 night, verified against the staging integration build `desktop-gateway:staging-3015d4e085a1`)
+- **Works today**: devbox create / retrieve / list (paged) / update (name, metadata) / suspend / resume / keep-alive / shutdown; `cmd.exec` and `exec_async` (with streaming callbacks); file read / write / upload / download; disk snapshots (sync and async, update, create-from-snapshot); open and authenticated **tunnels**; **blueprints** from a Dockerfile (Ubuntu/Debian *or any public image*, `COPY`/`ADD` with a build context); storage objects and object mounts; devbox logs; sizes (capped at 8 vCPU / 16 GiB); Runloop's error classes, retries, pagination and env vars.
+- **Runloop's own example recipes**: 4 of 4 supported ones pass with only the import changed (`devbox_snapshots`, `devbox_snapshot_resume`, `devbox_from_blueprint_lifecycle`, `devbox_tunnel`): 19 checks, 0 failures, run repeatedly. The other three example recipes (`blueprint_with_build_context`, `secrets_with_devbox`, `mcp_github_tools`) need features Solari lacks (see below) and fail loudly with `SolariCompatUnsupported`.
+- **Live test suite** (`pytest -m live`, creates and deletes its own resources): 14 of 15 on the last full run; the one failure was a transient gateway `DependencyUnavailable` (503) on a devbox create, which the client now retries for ~45 s. 143 offline unit tests.
+- **Needs a gateway rollout or a key before it works**: named shells (`devbox.shell(name)`: the gateway is live but sandbox images need the new golden pin), durable executions and gateway-side logs (#570, waiting on a Firestore TTL), account secrets (#583: wired as `sdk.secret.*`, `client.secrets.*` and `devbox.create(secrets={ENV: secret_name})`; answers `SolariCompatUnsupported` while the gateway has no `ORG_SECRETS_KEY`).
+- **Not supported (raises `SolariCompatUnsupported`)**: agents, axons, gateways/MCP configs, network policies, restricted keys, SSH keys, PTY tunnels, multi-stage Dockerfiles, `FROM` private registries, `code_mounts`.
+
+Legend: **OK** works and is tested; **DIFF** works with a behaviour difference (explained); **GATEWAY** waits on a
+gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupported`.
+"Live" = exercised against staging by `tests/test_live_staging.py` with the staging nightly-verify key.
+
+## Setup and configuration
+| Runloop | Here |
+|---|---|
+| `Runloop(bearer_token=...)` / env `RUNLOOP_API_KEY` | OK, with a safety rule: sources are tried in order (argument, `SOLARI_API_KEY`, `RUNLOOP_API_KEY`) and **a key that does not start with `slr_` is never used or sent** (it is probably a Runloop secret): it is skipped with a warning that does not print it, and if no `slr_` key remains the constructor raises `RunloopError`. An `slr_` key is accepted from any source. |
+| `base_url` / env `RUNLOOP_BASE_URL` (default `https://api.runloop.ai`) | OK. Order: argument, `SOLARI_BASE_URL`, `RUNLOOP_BASE_URL`, default `https://api.getsolari.com`. |
+| `timeout`, `default_headers`, `http_client`, `with_options()` | Accepted, ignored. |
+| `max_retries` | OK (default 5), Solari's own policy: idempotent calls retry on network errors, 502/503/504/507 and `retryable` bodies. |
+| Sync and async (`Runloop`/`AsyncRunloop`, `RunloopSDK`/`AsyncRunloopSDK`) | OK. The sync API drives the async core on one background thread per client (`_loop.py`); don't call it from inside a callback it invoked. |
+
+## Object layer (`RunloopSDK`)
+| Call | Status | Notes |
+|---|---|---|
+| `devbox.create(**params)` | OK, live | Waits for `running` (Solari is already running when create returns). See create parameters below. |
+| `devbox.create_from_snapshot(id)`, `snapshot.create_devbox()` | OK, live | Maps to `fromSnapshot`. |
+| `devbox.create_from_blueprint_name(name)`, `create_from_blueprint_id(id)`, `blueprint.create_devbox()` | OK, live | A Solari template: a built-in name (`base`) or one built with `blueprint.create`. Custom names are resolved to the `tpl_` id for you. |
+| `devbox.from_id(id)`, `devbox.list(**)` | OK, live | |
+| `Devbox.get_info / await_running / await_suspended / shutdown / suspend / resume / keep_alive` | OK, live | `suspend`/`resume` = Solari pause/resume (RAM+disk). `keep_alive` re-arms the idle window the devbox was created with (default 30 min). |
+| `with ... as devbox` (sync) / `async with` | OK | Shuts the devbox down on exit. |
+| `devbox.cmd.exec(cmd, stdout=, stderr=, output=, last_n=)` | OK, live | Runs `bash -lc "<cmd>"` from `$HOME`. Callbacks receive lines. Output is never truncated (`*_truncated` is always false). `ExecutionResult.stdout(num_lines=)` etc. as in Runloop. |
+| `devbox.cmd.exec_async(...)` -> `Execution` | DIFF | `result()`, `get_state()`, `kill()`, `send_std_in()`, `join()` work **inside the creating process** (an in-memory registry). On a gateway with durable executions (pinetree-desktop#570, detected by probing `GET /sandboxes/{id}/executions`) every command runs through it, so `executions.retrieve / await_completed / kill / send_std_in` also work by `(devbox_id, execution_id)` from **another process**; callbacks are fed by polling the execution (~0.4 s). Against a gateway without it, the in-process registry above is used. `close_std_in` NO. |
+| `devbox.shell(name).exec / exec_async / delete`, `shell_name=` | DIFF | Wired to the gateway's named shells (pinetree-desktop#569): one persistent bash per name (cwd, env, functions, jobs persist). Output reaches `stdout=/stderr=/output=` callbacks when the command ends, not while it runs; a shell command cannot be killed or given stdin (end the shell with `shell.delete()`). Raises `SolariCompatUnsupported` on a gateway or sandbox image without shells (the guest image needs a new golden). Not yet run against staging: #569 is not deployed. |
+| `devbox.file.read / write / upload / download` | OK, live | Relative paths resolve against `$HOME`; parent dirs are created on write/upload. `upload(file=)` takes bytes, `Path`, str path or a file object. |
+| `devbox.snapshot_disk(name=, commit_message=, metadata=)` / `_async` | DIFF | Synchronous, returns a `Snapshot`. Snapshots are RAM+disk. `commit_message`/`metadata` are returned but not stored until GATEWAY (snapshot metadata). |
+| `snapshot.get_info / delete / await_completed`, `snapshot.list`, `snapshot.from_id` | OK, live | `snapshot.update(name=, metadata=)`: OK on a gateway with `PATCH /snapshots/{id}` (#566), else unsupported. Deleting a snapshot with live children is a 409 `ConflictError`. |
+| `devbox.get_tunnel()`, `get_tunnel_url(port)`, `net.enable_tunnel / get_tunnel / remove_tunnel`, create `tunnel={'auth_mode','wake_on_http','http_keep_alive'}` | DIFF, live | Real tunnel API (pinetree-desktop#575): one switch for every guest port, `https://<label>-<port>.<preview domain>`; `tunnel_key` is the `<label>`. `authenticated` (Solari's default) returns an `auth_token` that must be sent in the **`x-solari-preview-token`** header (Runloop uses `Authorization: Bearer`); `open` needs nothing. `get_tunnel()` returns `None` when no tunnel is enabled (as Runloop). **Difference:** Solari refuses `open` + `wake_on_http` (anonymous traffic could wake and bill a sandbox); the shim raises `SolariCompatUnsupported` for it, use `authenticated`. Verified on 2 gateway replicas: 40/40 requests succeed with the token, 20/20 are refused without it, revocation takes effect within 3 s. On a gateway without the tunnel API it falls back to an open per-port preview URL. |
+| `devbox.logs(execution_id=, shell_name=)` | DIFF | Uses the gateway's `GET /sandboxes/{id}/logs` when it exists (feat2's work); until then it returns the output of commands run through **this client instance** (in-process). |
+| `devbox.create_ssh_key()`, PTY tunnels, gateway/MCP tokens, `watch_evictions` | NO | Runloop platform features. |
+| `blueprint.create(name, dockerfile=, system_setup_commands=, file_mounts=, base_blueprint_name=/id=, build_args=, launch_parameters=)` | DIFF, live | Builds a Solari template from a **Dockerfile subset** and waits for it (`FROM` ubuntu/debian = the native base; **any other public image** (e.g. `python:3.12-alpine`) is imported into a chroot, see the limits below; `RUN ENV ARG WORKDIR ENTRYPOINT CMD`; `COPY`/`ADD` with a `build_context` (see below); not multi-stage, `USER`). See `BLUEPRINTS.md`. `build_context`, `code_mounts`, `services`, `secrets` NO. |
+| `blueprint.from_id / list`, `Blueprint.get_info / logs / delete` | OK, live | `list()` returns your org's custom templates only. `logs()` has no timestamps/levels (Solari returns plain lines). |
+| `storage_object.upload_from_dir/bytes/text/file`, `as_build_context()`, `from_id`, `delete` | DIFF, live | Not real storage objects: the context is a deterministic `.tar.gz` **held by this client** and embedded in the build recipe, capped at ~700 KB compressed (the template body limit is 1 MiB). Honours `.dockerignore`. `COPY`/`ADD` (incl. `--chown`, `--chmod`, globs, `ADD` of a local tar) copy from it; `COPY --from`, URLs, `../` sources are refused. A context uploaded by another process is `SolariCompatUnsupported`. Everything else on `storage_object` (create, list, download, mounts) -> GATEWAY (objects). |
+| `secret.create / from_name / from_id / update / list / delete`, `Secret.get_info / update / delete`, `client.secrets.*`, create `secrets={ENV: secret_name}` | DIFF | Solari account secrets (pinetree-desktop#583): **write-only** (no route returns a value), names `[A-Za-z][A-Za-z0-9_.-]{0,63}` double as ids, values up to 16 KiB, 200 per org, at most 20 per create, reserved env names (`LD_*`, `PATH`, `HOME`...) refused. Not exercised on staging yet: the gateway answers 501 until the org-secrets key exists, and the shim then raises `SolariCompatUnsupported`. |
+| `agent`, `axon`, `network_policy`, `gateway_config`, `mcp_config` | NO | Runloop platform features. |
+
+## REST layer (`client.devboxes.*`)
+`create`, `create_and_await_running`, `retrieve`, `list` (auto-paginating, awaitable or `async for`), `shutdown`, `suspend`,
+`resume`, `keep_alive`, `await_running`, `await_suspended`, `execute`, `execute_sync`, `execute_async`,
+`execute_and_await_completion`, `wait_for_command`, `read_file_contents`, `write_file_contents`, `upload_file`,
+`download_file`, `snapshot_disk`, `snapshot_disk_async`, `list_disk_snapshots`, `delete_disk_snapshot`, `executions.*`
+(retrieve, await_completed, kill, send_std_in), `disk_snapshots.list/delete`: **OK** (same caveats as above).
+`update(name=, metadata=)`: OK on a gateway with `PATCH /sandboxes/{id}` (pinetree-desktop#566), `SolariCompatUnsupported` on one without. `retrieve_resource_usage`, tunnels, ssh, tokens -> NO. `client.blueprints` (create, retrieve, list, delete, logs,
+await_build_complete, create_and_await_build_complete): OK (Dockerfile subset). `objects`, `agents`, ... -> NO. `with_raw_response` / `with_streaming_response` -> not provided.
+
+## Create parameters
+| Runloop param | Mapping |
+|---|---|
+| `name` | sent to the gateway's native `name` (#566, via a PATCH right after create); also stored as metadata key `runloop.name` (hidden from `metadata`) so it works on gateways without it |
+| `metadata` | `metadata` |
+| `environment_variables` | `envs` |
+| `blueprint_name` | `template` (custom names resolved to `tpl_` ids) |
+| `snapshot_id` | `fromSnapshot` |
+| `file_mounts` | files written after create |
+| `entrypoint` | started in the background after create |
+| `launch_parameters.launch_commands` | run in order after create; a non-zero exit fails the create (and shuts the devbox down) |
+| `launch_parameters.keep_alive_time_seconds` | `timeoutMs`, `lifecycle.onTimeout = "kill"` (Runloop's default is shutdown) |
+| `launch_parameters.after_idle {on_idle, idle_time_seconds}` | `timeoutMs`; `on_idle: "suspend"` -> `onTimeout: "pause"`, otherwise `"kill"` |
+| `launch_parameters.resource_size_request`, `custom_cpu_cores`, `custom_gb_memory`, `custom_disk_size` | see sizes |
+| `blueprint_id` | a Solari template id |
+| `code_mounts`, `mounts`, `gateways`, `mcp`, `secrets`, `tunnel`, `network_policy_id`, `user_parameters` | NO |
+| `architecture`, `available_ports` | ignored |
+
+### Sizes (James's rule: cap silently, never error)
+CPU is rounded **up** to a whole vCPU; the result is capped at Solari's limits, **8 vCPU / 16 GiB**, with a `WARNING` on the
+`solari_runloop` logger when a cap applies. Disk is only sent when `custom_disk_size` is given (Runloop's per-size disk
+figures are not forwarded). No size at all leaves Solari's defaults (2 vCPU / 2 GiB).
+
+| `resource_size_request` | Runloop documents | Sent to Solari |
+|---|---|---|
+| `X_SMALL` | 0.5 vCPU, 1 GiB | 1 vCPU, 1 GiB |
+| `SMALL` | 1 vCPU, 2 GiB | 1 vCPU, 2 GiB |
+| `MEDIUM` | 2 vCPU, 4 GiB | 2 vCPU, 4 GiB |
+| `LARGE` | 2 vCPU, 8 GiB | 2 vCPU, 8 GiB |
+| `X_LARGE` | 4 vCPU, 16 GiB | 4 vCPU, 16 GiB |
+| `XX_LARGE` | 8 vCPU, 32 GiB | 8 vCPU, **16 GiB (capped)** |
+| `CUSTOM_SIZE` | `custom_cpu_cores`, `custom_gb_memory` | ceil(cpu) capped at 8; memory x 1024 MiB capped at 16384 |
+
+### Image import limits (`FROM <image>`, BLUEPRINTS.md level 3a)
+The image needs a `/bin/sh` (distroless fails the build); about 2 GB of free disk in the builder; `ENTRYPOINT`/`CMD` are recorded, **not started**;
+public registries from an allowlist only, amd64 only, no credentials; the root is a chroot in your own microVM (not a security boundary); no init/systemd
+inside the image; absolute symlinks inside the image are refused by the file API (use `cmd.exec`). A warning is logged whenever import mode is used.
+
+## Status, errors, pagination
+- Status (Solari state -> `DevboxView.status`): `starting`->`initializing`, `running`->`running`, `paused`->`suspended`,
+  `archived`->`suspended`, `releasing`->`shutdown`, `gone`->`shutdown`; anything else `failure`.
+  `DevboxView` fields Solari does not have are synthesized: `create_time_ms` from `createdAt`, one `state_transitions`
+  entry, `launch_parameters` from the real `cpu`/`memMb`, `capabilities=[]`.
+- Errors: 400 `BadRequestError`, 401 `AuthenticationError`, 402 and 403 `PermissionDeniedError` (`status_code` keeps 402),
+  404 `NotFoundError`, 409 `ConflictError`, 422 `UnprocessableEntityError`, 429 `RateLimitError`, 5xx `InternalServerError`;
+  network -> `APIConnectionError`, timeouts -> `APITimeoutError`. `.body` is Solari's `{code,error,message,retryable}`.
+  Solari-specific: a **429 `ConcurrencyLimitExceeded`** is a `RateLimitError` that the client does NOT retry.
+- IDs are Solari's opaque signed strings (they contain `:` and `.`), not `dbx_...`. Snapshot ids are `snap_...`.
+- Pagination: `devboxes.list()` returns a page with `.devboxes`, `.has_more`, `.has_next_page()`, `.get_next_page()`;
+  iterating it (or `async for`) walks every page. `total_count` is always `None`. `starting_after` is sent as `startingAfter` to a gateway that supports it (#566, detected from `hasMore` in the list reply); on an older one it is treated as the opaque cursor from a previous page. `list` only returns sandboxes, never desktops.
+- Not retried-for-you: Runloop's long-poll `*_and_await_*` helpers poll with `PollingConfig` (re-exported from
+  `solari_runloop.lib.polling`; same fields).
+
+## Not compatible, by design
+Persistent 1:1 `dbx_` ids; `optimistic_timeout` (exec always waits); log streaming over SSE; anything under `agents`/`axons`/`gateways`/`mcp`/`secrets`.
+
+## Runloop's own examples (import swapped, run against staging by `tests/run_runloop_examples.sh`)
+Last run 2026-10-21 against the F15 integration build `desktop-gateway:staging-190c78afc3e2`: **4 of 4 supported recipes pass (19 checks, 0 failures)**, run twice. Live suite (`pytest -m live`) on the previous build: 14 of 15, the other one a list-lag flake now retried.
+| Example | Result |
+|---|---|
+| `devbox_snapshots` | PASS (suspend, resume, snapshot, two clones, isolation checks) |
+| `devbox_snapshot_resume` | PASS |
+| `devbox_from_blueprint_lifecycle` | PASS (Dockerfile blueprint, build logs, devbox logs from the in-process record) |
+| `devbox_tunnel` | PASS (open tunnel: `tunnel={'auth_mode':'open'}`, `get_tunnel()`, `get_tunnel_url(port)` = Solari's per-port preview URL; the HTTP request through it succeeds) |
+| `blueprint_with_build_context`, `secrets_with_devbox`, `mcp_github_tools` | not run: storage objects / secret store / MCP are not supported |
+
+## Test status
+- `tests/` offline: mappings, config, errors, sync/async surface over a fake gateway.
+- `tests/test_live_staging.py` (`pytest -m live`): quickstart, exec failure/stderr/tail, async exec streaming and kill, file round-trips,
+  list/retrieve/pagination, suspend/resume state, snapshot -> create from snapshot, errors, size capping. See the PR for the latest run.

solari_runloop_compat-0.1.0/GATEWAY-ENDPOINTS.md

@@ -0,0 +1,64 @@
+# Target gateway API for Runloop compatibility (proposal, v1)
+
+Build to these shapes and the compat packages (`solari_runloop`, `@solarisdk/runloop-compat`) will wire to them. Shapes follow
+the gateway's existing conventions: camelCase JSON, opaque signed ids, `Idempotency-Key` on creates, errors as
+`{code,error,message,retryable}`. If you must deviate, change this file in the same PR and tell feat1.
+Everything is scoped to the caller's org like the existing `/sandboxes/*` routes. "SandboxView" is the existing view.
+
+## 1. Durable executions + logs  (owner: feat2)
+Why: Runloop's `execute_async` returns an `execution_id` that is retrievable, waitable and killable from any process.
+Today `cmd.start` is a live WebSocket handle only.
+
+| Route | Body / query | Response |
+|---|---|---|
+| `POST /sandboxes/{id}/executions` | `{cmd, args?, cwd?, env?, user?, shellName?, attachStdin?}` (`cmd` = argv[0]; the compat layer sends `/bin/bash -lc "<string>"`) | `201 ExecutionView` |
+| `GET /sandboxes/{id}/executions/{eid}` | `?lastN=<lines>` | `ExecutionView` |
+| `GET /sandboxes/{id}/executions` | `?limit&cursor&status` | `{executions: ExecutionView[], nextCursor?}` |
+| `POST /sandboxes/{id}/executions/{eid}/wait` | `{timeoutMs?}` long-poll (cap 30 s per call) | `ExecutionView` (status `running` if the wait timed out) |
+| `POST /sandboxes/{id}/executions/{eid}/kill` | `{signal?}` | `ExecutionView` |
+| `POST /sandboxes/{id}/executions/{eid}/stdin` | `{data, eof?}` | `{ok:true}` |
+| `GET /sandboxes/{id}/executions/{eid}/stream` | `?stream=stdout\|stderr\|both&fromSeq=` SSE: `data: {"seq":n,"stream":"stdout","data":"..."}` then `event: exit` | stream |
+| `GET /sandboxes/{id}/logs` | `?executionId&source&lastN&cursor&limit` | `{logs:[{ts,source:"stdout"\|"stderr"\|"entrypoint"\|"system",executionId?,message}], nextCursor?}` |
+
+```
+ExecutionView = { executionId, sandboxId, status: "queued"|"running"|"completed", exitCode?: int,
+                  stdout: string, stderr: string, stdoutTruncated: bool, stderrTruncated: bool,
+                  shellName?: string, startedAt, finishedAt? }
+```
+Semantics: output is buffered server-side (suggest 1 MiB per stream, tail kept, `*Truncated` set) and survives the client
+disconnecting; records are kept >= 24 h after exit. A paused sandbox keeps its records. `status:"completed"` with
+`exitCode` absent means the sandbox died mid-run. The HTTP `POST /sandboxes/{id}/exec` fast path stays as is.
+
+**As built (feat2, pinetree-desktop#570):** routes and `ExecutionView` as above; list `limit<=100`, logs `limit<=1000`, wait capped at 30 s, stdin <=1 MiB per call,
+max 16 running executions per sandbox (429 `TooManyExecutions`, retryable); `kill` waits up to 2 s for the exit and returns the view; logs sources are
+`stdout|stderr|system` (+ `entrypoint`, always empty for now), `system` lines are "execution started: <cmd>" / "execution exited with code N", the cursor is an opaque
+numeric offset; shared-context sandboxes get 409 `NotSupported`; wait/kill/stdin only work on the pod that started the run, else 409 `ExecutionOnOtherInstance`
+(retryable: the compat layer retries); GET/list/logs work on any pod only once `EXECUTIONS_TABLE` (Firestore) is configured, otherwise records are in pod memory;
+`shellName` is accepted and echoed but is not a persistent shell yet (named shells are #569: `POST /sandboxes/{id}/shells/{name}/exec`); stdin `eof:true` needs the next guest image.
+
+## 2. Names, metadata, pagination, snapshots  (owner: bug3)
+- `PATCH /sandboxes/{id}` `{name?: string|null, metadata?: {string:string}}` -> `SandboxView` (metadata is replaced, not merged;
+  send `null` to clear a field). Add first-class `name?: string` and `template` to `SandboxView`/create (`name` in
+  `POST /sandboxes`). Until it ships the compat layer stores the name under metadata key `runloop.name`.
+- `GET /sandboxes` gains `startingAfter=<sandboxId>` (exclusive; fall back to 400 if unknown) and returns
+  `{sandboxes, nextCursor?, hasMore: bool, totalCount?: int}` (`includeTotalCount=true` to get it). Keep `cursor`.
+- Snapshots: `POST /sandboxes/{id}/snapshots` accepts `{name?, metadata?, commitMessage?}`; `SnapshotView` gains
+  `metadata`, `commitMessage?`, `sourceSandboxId`; `PATCH /snapshots/{id}` `{name?, metadata?, commitMessage?}`.
+  Optional `?wait=false` on create returns early with `status:"pending"` and `GET /snapshots/{id}` shows `status: pending|ready|failed`
+  (default stays synchronous).
+- Named persistent shells: `shellName` on execution create = one persistent bash per `(sandboxId, shellName)`; commands queue
+  one at a time, cwd/env persist (Runloop `devbox.shell("name")`). First use creates the shell.
+
+## 3. Storage objects, mounts, tunnels  (owner: bug2)
+- `POST /objects` `{name, contentType?, ttlMs?}` -> `{objectId, uploadUrl, uploadHeaders?}`; client PUTs the bytes;
+  `POST /objects/{id}/complete`; `GET /objects/{id}` -> `{objectId,name,contentType,sizeBytes,state:"uploading"|"ready",createdAt,expiresAt?}`;
+  `GET /objects/{id}/download-url` -> `{url, expiresAt}`; `DELETE /objects/{id}`; `GET /objects?limit&cursor&name&contentType`.
+- Mounts at create: `POST /sandboxes` accepts `mounts: [{objectId, path, extract?: bool}]` (a `.tar.gz` object with
+  `extract:true` is unpacked at `path`; otherwise placed as a file).
+- Tunnel: `POST /sandboxes/{id}/tunnel` `{authMode?: "open"|"authenticated", wakeOnHttp?: bool, keepAlive?: bool}` ->
+  `{urlTemplate: "https://{port}-<key>.<domain>", authToken?, authMode}`; `GET` same shape; `DELETE`. The existing
+  per-port `GET /sandboxes/{id}/ports/{port}` stays.
+
+## 4. Blueprints from a Dockerfile  (owner: feat1 to sketch, see BLUEPRINTS.md)
+`POST /templates` additionally accepts `{name, dockerfile, buildContext?: objectId, systemSetupCommands?: string[], launchCommands?: string[], baseTemplate?}`;
+`TemplateView`/`GET /templates/{id}/logs` unchanged (status `building|ready|failed`).

solari_runloop_compat-0.1.0/NOTICE

@@ -0,0 +1,25 @@
+solari-runloop-compat
+
+Not affiliated with, endorsed by, or sponsored by Runloop. "Runloop" and "Devbox" are used only to describe the
+interface this package is compatible with.
+
+Portions of solari_runloop/types/ are copied from runloop_api_client 2.0.0
+(https://github.com/runloopai/api-client-python), which is licensed under the MIT License:
+
+    Copyright 2026 runloop
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+    documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+    to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+    the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+    THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+    IN THE SOFTWARE.
+
+The copied files keep their "generated by Stainless" headers.

solari_runloop_compat-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: solari-runloop-compat
+Version: 0.1.0
+Summary: Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop.
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: MIT
+License-File: NOTICE
+Keywords: compatibility,runloop,sandbox,solari
+Requires-Python: >=3.9
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: solari-core>=0.3.1
+Requires-Dist: solari-sandbox>=0.2.4
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# solari-runloop-compat (Python)
+
+Run code written for the Runloop Python SDK on Solari Sandboxes by changing the import:
+
+```python
+# from runloop_api_client import RunloopSDK
+from solari_runloop import RunloopSDK
+
+runloop = RunloopSDK()   # SOLARI_API_KEY (or RUNLOOP_API_KEY) and, optionally, SOLARI_BASE_URL
+
+with runloop.devbox.create(name="my-devbox") as devbox:
+    devbox.file.write(file_path="main.py", contents="print('hello from a sandbox')")
+    result = devbox.cmd.exec("python3 main.py")
+    print(result.stdout())
+```
+
+`Runloop`, `AsyncRunloop`, `RunloopSDK`, `AsyncRunloopSDK`, the exception classes and the response types are exported
+under Runloop's names. **COMPAT.md** lists exactly what is supported, what differs, and what raises
+`SolariCompatUnsupported`. Unsupported features never fail silently.
+
+*Not affiliated with Runloop.* Package and module names are provisional (see `solari_runloop/_branding.py`).
+Do not publish: this is a draft for review.
+
+## Develop
+```
+pip install -e ../python-core -e ../python-sandbox -e '.[test]'
+pytest                                   # offline unit tests
+SOLARI_API_KEY=... SOLARI_BASE_URL=https://api-sta.getsolari.com pytest -m live   # staging; deletes what it creates
+```

solari_runloop_compat-0.1.0/README.md

@@ -0,0 +1,29 @@
+# solari-runloop-compat (Python)
+
+Run code written for the Runloop Python SDK on Solari Sandboxes by changing the import:
+
+```python
+# from runloop_api_client import RunloopSDK
+from solari_runloop import RunloopSDK
+
+runloop = RunloopSDK()   # SOLARI_API_KEY (or RUNLOOP_API_KEY) and, optionally, SOLARI_BASE_URL
+
+with runloop.devbox.create(name="my-devbox") as devbox:
+    devbox.file.write(file_path="main.py", contents="print('hello from a sandbox')")
+    result = devbox.cmd.exec("python3 main.py")
+    print(result.stdout())
+```
+
+`Runloop`, `AsyncRunloop`, `RunloopSDK`, `AsyncRunloopSDK`, the exception classes and the response types are exported
+under Runloop's names. **COMPAT.md** lists exactly what is supported, what differs, and what raises
+`SolariCompatUnsupported`. Unsupported features never fail silently.
+
+*Not affiliated with Runloop.* Package and module names are provisional (see `solari_runloop/_branding.py`).
+Do not publish: this is a draft for review.
+
+## Develop
+```
+pip install -e ../python-core -e ../python-sandbox -e '.[test]'
+pytest                                   # offline unit tests
+SOLARI_API_KEY=... SOLARI_BASE_URL=https://api-sta.getsolari.com pytest -m live   # staging; deletes what it creates
+```

solari_runloop_compat-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solari-runloop-compat"
+version = "0.1.0"
+description = "Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Solari" }]
+keywords = ["solari", "sandbox", "runloop", "compatibility"]
+dependencies = ["solari-sandbox>=0.2.4", "solari-core>=0.3.1", "pydantic>=2,<3"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://getsolari.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["solari_runloop"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["live: runs against a real Solari gateway (needs SOLARI_API_KEY + SOLARI_BASE_URL)"]
+addopts = "-m 'not live'"

solari_runloop_compat-0.1.0/solari_runloop/__init__.py

@@ -0,0 +1,42 @@
+"""Runloop-compatible interface over the Solari sandbox gateway.
+
+Not affiliated with Runloop. See COMPAT.md for exactly which parts of the Runloop SDK are supported.
+Change ``from runloop_api_client import RunloopSDK`` to ``from solari_runloop import RunloopSDK``.
+"""
+
+from __future__ import annotations
+
+from . import types
+from ._branding import TARGET_RUNLOOP_VERSION
+from ._client import AsyncRunloop, Runloop
+from ._exceptions import (
+    APIError,
+    APIStatusError,
+    ConflictError,
+    NotFoundError,
+    RateLimitError,
+    RunloopError,
+    BadRequestError,
+    APITimeoutError,
+    APIConnectionError,
+    AuthenticationError,
+    InternalServerError,
+    PermissionDeniedError,
+    SolariCompatUnsupported,
+    UnprocessableEntityError,
+    APIResponseValidationError,
+)
+from .lib.polling import PollingConfig, PollingTimeout
+from .sdk import AsyncRunloopSDK, RunloopSDK
+
+__version__ = "0.1.0"
+Client = Runloop
+AsyncClient = AsyncRunloop
+
+__all__ = [
+    "Runloop", "AsyncRunloop", "RunloopSDK", "AsyncRunloopSDK", "Client", "AsyncClient",
+    "RunloopError", "APIError", "APIStatusError", "APIConnectionError", "APITimeoutError",
+    "APIResponseValidationError", "BadRequestError", "AuthenticationError", "PermissionDeniedError",
+    "NotFoundError", "ConflictError", "UnprocessableEntityError", "RateLimitError", "InternalServerError",
+    "SolariCompatUnsupported", "PollingConfig", "PollingTimeout", "types", "TARGET_RUNLOOP_VERSION",
+]

solari_runloop_compat-0.1.0/solari_runloop/_branding.py

@@ -0,0 +1,10 @@
+"""Every name that might change after the naming/legal review lives here."""
+
+PACKAGE_NAME = "solari-runloop-compat"
+MODULE_NAME = "solari_runloop"
+#: Runloop SDK release whose public surface this layer mirrors (see COMPAT.md).
+TARGET_RUNLOOP_VERSION = "2.0.0"
+DEFAULT_BASE_URL = "https://api.getsolari.com"
+KEY_ENV_VARS = ("SOLARI_API_KEY", "RUNLOOP_API_KEY")
+BASE_URL_ENV_VARS = ("SOLARI_BASE_URL", "RUNLOOP_BASE_URL")
+KEY_PREFIX = "slr_"

solari_runloop_compat-0.1.0/solari_runloop/_client.py

@@ -0,0 +1,107 @@
+"""``Runloop`` / ``AsyncRunloop``: the REST-style client (``client.devboxes.*``)."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from . import _config
+from ._gateway import Gateway
+from ._loop import LoopThread
+from ._resources import AsyncBlueprints, AsyncDevboxes, AsyncSecrets, _Unsupported
+from ._sync import SyncMirror
+
+DEFAULT_MAX_RETRIES = 5
+
+_UNSUPPORTED_RESOURCES = {
+    "objects": "Storage objects have no Solari equivalent yet.",
+    "agents": "Agents are a Runloop platform feature.",
+    "axons": "Axons are a Runloop platform feature.",
+    "network_policies": "Network policies have no Solari equivalent.",
+    "gateway_configs": "Agent gateways are a Runloop platform feature.",
+    "mcp_configs": "MCP configs are a Runloop platform feature.",
+    "accounts": "Accounts are a Runloop platform feature.",
+    "apikeys": "API keys are managed in the Solari console.",
+    "restricted_keys": "Restricted keys are a Runloop platform feature.",
+    "pty": "PTY tunnels are not exposed through the compat layer.",
+}
+
+
+class AsyncRunloop:
+    """Async REST client. Accepts Runloop's constructor arguments; ``timeout``/``default_headers``/
+    ``http_client`` are accepted for source compatibility and not used."""
+
+    _solari_mirror = False
+
+    def __init__(
+        self,
+        *,
+        bearer_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Any = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        default_query: Optional[Mapping[str, object]] = None,
+        http_client: Any = None,
+        **_ignored: Any,
+    ) -> None:
+        token, url = _config.resolve(bearer_token, base_url)
+        self.bearer_token = token
+        self.base_url = url
+        self.max_retries = max_retries
+        self._gw = Gateway(token=token, base_url=url, max_retries=max_retries)
+        self.devboxes = AsyncDevboxes(self._gw)
+        self.blueprints = AsyncBlueprints(self._gw)
+        self.secrets = AsyncSecrets(self._gw)
+        for name, hint in _UNSUPPORTED_RESOURCES.items():
+            setattr(self, name, _Unsupported(name, hint))
+
+    def with_options(self, **_: Any) -> "AsyncRunloop":
+        return self
+
+    async def close(self) -> None:
+        await self._gw.aclose()
+
+    async def __aenter__(self) -> "AsyncRunloop":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()
+
+
+class Runloop:
+    """Sync REST client: the async client driven from a background event loop (see ``_loop.py``)."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._attach(AsyncRunloop(**kwargs), LoopThread())
+
+    @classmethod
+    def _wrapping(cls, inner: AsyncRunloop, loop: LoopThread) -> "Runloop":
+        """A sync view of an existing async client (used by ``RunloopSDK`` so both share one loop)."""
+        self = cls.__new__(cls)
+        self._attach(inner, loop)
+        return self
+
+    def _attach(self, inner: AsyncRunloop, loop: LoopThread) -> None:
+        self._loop = loop
+        self._inner = inner
+        self.bearer_token = self._inner.bearer_token
+        self.base_url = self._inner.base_url
+        self.max_retries = self._inner.max_retries
+        self.devboxes = SyncMirror(self._inner.devboxes, self._loop)
+        self.blueprints = SyncMirror(self._inner.blueprints, self._loop)
+        self.secrets = SyncMirror(self._inner.secrets, self._loop)
+        for name in _UNSUPPORTED_RESOURCES:
+            setattr(self, name, getattr(self._inner, name))
+
+    def with_options(self, **_: Any) -> "Runloop":
+        return self
+
+    def close(self) -> None:
+        self._loop.run(self._inner.close())
+        self._loop.close()
+
+    def __enter__(self) -> "Runloop":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()