solari-runloop-compat 0.2.1__tar.gz → 0.2.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/COMPAT.md +33 -12
  2. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/PKG-INFO +2 -2
  3. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/pyproject.toml +6 -2
  4. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/__init__.py +1 -1
  5. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_exceptions.py +5 -2
  6. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_gateway.py +56 -14
  7. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_mapping.py +31 -2
  8. solari_runloop_compat-0.2.4/solari_runloop/_redact.py +12 -0
  9. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_resources.py +5 -4
  10. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_sync.py +2 -0
  11. solari_runloop_compat-0.2.4/solari_runloop/_vendor_user.py +45 -0
  12. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/sdk.py +4 -4
  13. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_gateway_wire.py +111 -3
  14. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_live_staging.py +2 -2
  15. solari_runloop_compat-0.2.1/BLUEPRINTS.md +0 -84
  16. solari_runloop_compat-0.2.1/GATEWAY-ENDPOINTS.md +0 -64
  17. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/.gitignore +0 -0
  18. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/LICENSE +0 -0
  19. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/NOTICE +0 -0
  20. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/README.md +0 -0
  21. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_branding.py +0 -0
  22. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_client.py +0 -0
  23. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_config.py +0 -0
  24. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_context.py +0 -0
  25. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_dockerfile.py +0 -0
  26. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_loop.py +0 -0
  27. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/_models.py +0 -0
  28. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/lib/__init__.py +0 -0
  29. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/lib/polling.py +0 -0
  30. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/pagination.py +0 -0
  31. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/__init__.py +0 -0
  32. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/blueprint_build_log.py +0 -0
  33. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/blueprint_build_logs_list_view.py +0 -0
  34. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/blueprint_build_parameters.py +0 -0
  35. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/blueprint_view.py +0 -0
  36. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devbox_async_execution_detail_view.py +0 -0
  37. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devbox_execution_detail_view.py +0 -0
  38. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devbox_snapshot_list_view.py +0 -0
  39. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devbox_snapshot_view.py +0 -0
  40. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devbox_view.py +0 -0
  41. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devboxes/__init__.py +0 -0
  42. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/devboxes/devbox_logs_list_view.py +0 -0
  43. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/secret_view.py +0 -0
  44. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/__init__.py +0 -0
  45. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/after_idle.py +0 -0
  46. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/code_mount_parameters.py +0 -0
  47. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/launch_parameters.py +0 -0
  48. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/lifecycle_configuration.py +0 -0
  49. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/lifecycle_hooks.py +0 -0
  50. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/shared/resume_triggers.py +0 -0
  51. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/solari_runloop/types/tunnel_view.py +0 -0
  52. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/run_runloop_examples.sh +0 -0
  53. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_config.py +0 -0
  54. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_context.py +0 -0
  55. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_dockerfile.py +0 -0
  56. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_mapping.py +0 -0
  57. {solari_runloop_compat-0.2.1 → solari_runloop_compat-0.2.4}/tests/test_surface.py +0 -0
@@ -4,7 +4,7 @@
4
4
  - **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.
5
5
  - **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`.
6
6
  - **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.
7
- - **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`).
7
+ - **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 (waiting on a Firestore TTL), account secrets (: wired as `sdk.secret.*`, `client.secrets.*` and `devbox.create(secrets={ENV: secret_name})`; answers `SolariCompatUnsupported` while the gateway has no `ORG_SECRETS_KEY`).
8
8
  - **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`.
9
9
 
10
10
  Legend: **OK** works and is tested; **DIFF** works with a behaviour difference (explained); **GATEWAY** waits on a
@@ -30,18 +30,18 @@ gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupp
30
30
  | `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). |
31
31
  | `with ... as devbox` (sync) / `async with` | OK | Shuts the devbox down on exit. |
32
32
  | `devbox.cmd.exec(cmd, stdout=, stderr=, output=, last_n=)` | OK, live | Runs `bash -lc "<cmd>"` from `$HOME`; on a devbox built from an image (`FROM <image>`) it runs a non-login `bash -c` when the image has `/bin/bash` and `sh -c` when it does not (Alpine), so the image's own `PATH` survives (a login shell would reset it). As a consequence `~/.profile` and `/etc/profile.d` are not read on image devboxes. Callbacks receive lines. Output is never truncated (`*_truncated` is always false). `ExecutionResult.stdout(num_lines=)` etc. as in Runloop. |
33
- | `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. |
34
- | `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. |
33
+ | `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 (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. |
34
+ | `devbox.shell(name).exec / exec_async / delete`, `shell_name=` | DIFF | Wired to the gateway's named shells: 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: is not deployed. |
35
35
  | `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. |
36
36
  | `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). |
37
- | `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`. |
38
- | `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. |
39
- | `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). |
37
+ | `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}`, else unsupported. Deleting a snapshot with live children is a 409 `ConflictError`. |
38
+ | `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: 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`. Checked 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. |
39
+ | `devbox.logs(execution_id=, shell_name=)` | DIFF | Uses the gateway's `GET /sandboxes/{id}/logs` when it exists; until then it returns the output of commands run through **this client instance** (in-process). |
40
40
  | `devbox.create_ssh_key()`, PTY tunnels, gateway/MCP tokens, `watch_evictions` | NO | Runloop platform features. |
41
41
  | `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 built natively by the gateway (`compiled.fromImage`), 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. |
42
42
  | `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). |
43
43
  | `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). |
44
- | `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`. |
44
+ | `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: **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`. |
45
45
  | `agent`, `axon`, `network_policy`, `gateway_config`, `mcp_config` | NO | Runloop platform features. |
46
46
 
47
47
  ## REST layer (`client.devboxes.*`)
@@ -50,13 +50,13 @@ gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupp
50
50
  `execute_and_await_completion`, `wait_for_command`, `read_file_contents`, `write_file_contents`, `upload_file`,
51
51
  `download_file`, `snapshot_disk`, `snapshot_disk_async`, `list_disk_snapshots`, `delete_disk_snapshot`, `executions.*`
52
52
  (retrieve, await_completed, kill, send_std_in), `disk_snapshots.list/delete`: **OK** (same caveats as above).
53
- `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,
53
+ `update(name=, metadata=)`: OK on a gateway with `PATCH /sandboxes/{id}`, `SolariCompatUnsupported` on one without. `retrieve_resource_usage`, tunnels, ssh, tokens -> NO. `client.blueprints` (create, retrieve, list, delete, logs,
54
54
  await_build_complete, create_and_await_build_complete): OK (Dockerfile subset). `objects`, `agents`, ... -> NO. `with_raw_response` / `with_streaming_response` -> not provided.
55
55
 
56
56
  ## Create parameters
57
57
  | Runloop param | Mapping |
58
58
  |---|---|
59
- | `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 |
59
+ | `name` | sent to the gateway's native `name` (via a PATCH right after create); also stored as metadata key `runloop.name` (hidden from `metadata`) so it works on gateways without it |
60
60
  | `metadata` | `metadata` |
61
61
  | `environment_variables` | `envs` |
62
62
  | `blueprint_name` | `template` (custom names resolved to `tpl_` ids) |
@@ -68,10 +68,10 @@ await_build_complete, create_and_await_build_complete): OK (Dockerfile subset).
68
68
  | `launch_parameters.after_idle {on_idle, idle_time_seconds}` | `timeoutMs`; `on_idle: "suspend"` -> `onTimeout: "pause"`, otherwise `"kill"` |
69
69
  | `launch_parameters.resource_size_request`, `custom_cpu_cores`, `custom_gb_memory`, `custom_disk_size` | see sizes |
70
70
  | `blueprint_id` | a Solari template id |
71
- | `code_mounts`, `mounts`, `gateways`, `mcp`, `secrets`, `tunnel`, `network_policy_id`, `user_parameters` | NO |
71
+ | `code_mounts`, `mounts`, `gateways`, `mcp`, `secrets`, `tunnel`, `network_policy_id` | NO |
72
72
  | `architecture`, `available_ports` | ignored |
73
73
 
74
- ### Sizes (James's rule: cap silently, never error)
74
+ ### Sizes (cap silently, never error)
75
75
  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
76
76
  `solari_runloop` logger when a cap applies. Disk is only sent when `custom_disk_size` is given (Runloop's per-size disk
77
77
  figures are not forwarded). No size at all leaves Solari's defaults (2 vCPU / 2 GiB).
@@ -108,7 +108,7 @@ import) keep working but still lack the image's `ENV`: rebuild them.
108
108
  Solari-specific: a **429 `ConcurrencyLimitExceeded`** is a `RateLimitError` that the client does NOT retry.
109
109
  - IDs are Solari's opaque signed strings (they contain `:` and `.`), not `dbx_...`. Snapshot ids are `snap_...`.
110
110
  - Pagination: `devboxes.list()` returns a page with `.devboxes`, `.has_more`, `.has_next_page()`, `.get_next_page()`;
111
- 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.
111
+ 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 (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.
112
112
  - Not retried-for-you: Runloop's long-poll `*_and_await_*` helpers poll with `PollingConfig` (re-exported from
113
113
  `solari_runloop.lib.polling`; same fields).
114
114
 
@@ -129,3 +129,24 @@ Last run 2026-10-21 against the F15 integration build `desktop-gateway:staging-1
129
129
  - `tests/` offline: mappings, config, errors, sync/async surface over a fake gateway.
130
130
  - `tests/test_live_staging.py` (`pytest -m live`): quickstart, exec failure/stderr/tail, async exec streaming and kill, file round-trips,
131
131
  list/retrieve/pagination, suspend/resume state, snapshot -> create from snapshot, errors, size capping. See the PR for the latest run.
132
+
133
+ ## Default user and home directory (matching Runloop)
134
+ **Today's sandboxes run as `root` in `/home/root`. Runloop's own run as `user` in `/home/user`; this arrives with a Solari server update, and this package already asks for it** (below).
135
+
136
+ Once the gateway supports it, Runloop sandboxes run as `user` in `/home/user`; commands, code and files all start there, and relative paths resolve against it. This package
137
+ asks the gateway for exactly that at create time (`user: "user"`, `cwd: "/home/user"`; the gateway creates the user at first boot with passwordless
138
+ sudo). Restores from a snapshot keep the snapshot's own user.
139
+ - **Gateway that predates `user` / `cwd`** (it answers 400 naming them, or ignores them): the plain create is used and the sandbox runs as **root in
140
+ `/home/root`**, which is what this package did before. Check `whoami` if code depends on it.
141
+ - **Template or snapshot made before user support** (the server answers 400 naming `user`): the plain create is used, the sandbox runs as **root**, and one warning says so. Rebuild templates and snapshots to get the vendor user.
142
+ - Shared isolation is commands and code only and takes no `user` / `cwd`; the compat packages never create shared sandboxes. (Runloop's own docs: the default user is `user` with home `/home/user`.)
143
+
144
+ ## Snapshots and output (0.2.2)
145
+ - `listDiskSnapshots` / `list_disk_snapshots` (`devbox_id` or `source_devbox_id`, `limit`, `starting_after`, `name`): with `devbox_id` it returns only that devbox's
146
+ snapshots and never the org's. A snapshot counts as the devbox's when the gateway reports its `sourceSandboxId` or when this client made it; a snapshot
147
+ made by another process on a gateway that does not report the source is left out rather than risk listing someone else's. Pages are followed until `limit`
148
+ matches are found, so `has_more` is right. Each snapshot carries `source_devbox_id`, `metadata` and `commit_message` when the gateway has them.
149
+ - Error messages carry only the first 8 characters of a sandbox id.
150
+ - `list_disk_snapshots` returns a list that also has `.snapshots`, `.has_more` and `.total_count`, the same shape as the TypeScript package.
151
+ - `devboxes.execute_sync` / `execute_and_await_completion` run over the control channel, so output is never truncated (the gateway's durable executions keep only the last 256 KiB, and are still used by `execute_async`).
152
+ - `launch_parameters.user_parameters` `{username, uid}` sets the create user (`username`, home `/home/<username>`, `/root` for `root`); the gateway picks the uid, so a uid other than root's is noted and ignored. On a gateway without user support this raises `SolariCompatUnsupported` instead of running as root.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: solari-runloop-compat
3
- Version: 0.2.1
3
+ Version: 0.2.4
4
4
  Summary: Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop.
5
5
  Project-URL: Homepage, https://getsolari.com
6
6
  Author: Solari
@@ -11,7 +11,7 @@ Keywords: compatibility,runloop,sandbox,solari
11
11
  Requires-Python: >=3.9
12
12
  Requires-Dist: pydantic<3,>=2
13
13
  Requires-Dist: solari-core>=0.4.0
14
- Requires-Dist: solari-sandbox>=0.3.0
14
+ Requires-Dist: solari-sandbox>=0.6.1
15
15
  Provides-Extra: test
16
16
  Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
17
17
  Requires-Dist: pytest>=7; extra == 'test'
@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "solari-runloop-compat"
7
- version = "0.2.1"
7
+ version = "0.2.4"
8
8
  description = "Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
11
11
  license = { text = "MIT" }
12
12
  authors = [{ name = "Solari" }]
13
13
  keywords = ["solari", "sandbox", "runloop", "compatibility"]
14
- dependencies = ["solari-sandbox>=0.3.0", "solari-core>=0.4.0", "pydantic>=2,<3"]
14
+ dependencies = ["solari-sandbox>=0.6.1", "solari-core>=0.4.0", "pydantic>=2,<3"]
15
15
 
16
16
  [project.optional-dependencies]
17
17
  test = ["pytest>=7", "pytest-asyncio>=0.23"]
@@ -22,6 +22,10 @@ Homepage = "https://getsolari.com"
22
22
  [tool.hatch.build.targets.wheel]
23
23
  packages = ["solari_runloop"]
24
24
 
25
+ # The gateway-endpoint design notes are internal working documents: they stay in the repository, not in the sdist.
26
+ [tool.hatch.build.targets.sdist]
27
+ exclude = ["GATEWAY-ENDPOINTS.md", "BLUEPRINTS.md"]
28
+
25
29
  [tool.pytest.ini_options]
26
30
  asyncio_mode = "auto"
27
31
  testpaths = ["tests"]
@@ -29,7 +29,7 @@ from ._exceptions import (
29
29
  from .lib.polling import PollingConfig, PollingTimeout
30
30
  from .sdk import AsyncRunloopSDK, RunloopSDK
31
31
 
32
- __version__ = "0.2.1"
32
+ __version__ = "0.2.4"
33
33
  Client = Runloop
34
34
  AsyncClient = AsyncRunloop
35
35
 
@@ -8,6 +8,8 @@ from __future__ import annotations
8
8
 
9
9
  from typing import Any, Optional
10
10
 
11
+ from ._redact import redact_ids
12
+
11
13
  __all__ = [
12
14
  "RunloopError",
13
15
  "APIError",
@@ -28,7 +30,8 @@ __all__ = [
28
30
 
29
31
 
30
32
  class RunloopError(Exception):
31
- pass
33
+ def __init__(self, *args: Any) -> None:
34
+ super().__init__(*(redact_ids(a) if isinstance(a, str) else a for a in args))
32
35
 
33
36
 
34
37
  class APIError(RunloopError):
@@ -38,7 +41,7 @@ class APIError(RunloopError):
38
41
 
39
42
  def __init__(self, message: str, request: Optional[Any] = None, *, body: Optional[object] = None) -> None:
40
43
  super().__init__(message)
41
- self.message = message
44
+ self.message = redact_ids(message)
42
45
  self.request = request
43
46
  self.body = body
44
47
 
@@ -24,6 +24,7 @@ from solari_core.sandbox import Sandbox
24
24
  from solari_sandbox import SandboxClient
25
25
 
26
26
  from . import _exceptions as ex
27
+ from ._vendor_user import create_as_vendor_user
27
28
  from . import _mapping as mp
28
29
  from .lib.polling import PollingConfig, PollingTimeout
29
30
  from .types import SecretView, BlueprintBuildLogsListView, BlueprintView, DevboxLogsListView, DevboxAsyncExecutionDetailView, DevboxExecutionDetailView, DevboxSnapshotView, DevboxView
@@ -128,11 +129,12 @@ class Gateway:
128
129
  self._home: Dict[str, Tuple[str, Optional[str], str]] = {}
129
130
  self._snapshot_of: Dict[str, str] = {}
130
131
  self._starting_after: Optional[bool] = None
131
- self._objects: Optional[bool] = None # gateway has /objects (#574)
132
+ self._objects: Optional[bool] = None # gateway has /objects
132
133
  self._native: set = set() # devboxes whose guest agent chroots into an imported image itself
133
134
  self._plain: set = set() # devboxes known NOT to be a native image build
134
- self._tunnel_api: Optional[bool] = None # gateway has /sandboxes/{id}/tunnel (#575)
135
- self._durable: Optional[bool] = None # gateway has /sandboxes/{id}/executions (pinetree-desktop#570)
135
+ self._tunnel_api: Optional[bool] = None # gateway has /sandboxes/{id}/tunnel
136
+ self._snapshot_sources: Dict[str, str] = {} # snapshot id -> devbox it was made from (the gateway's list does not say yet)
137
+ self._durable: Optional[bool] = None # gateway has /sandboxes/{id}/executions
136
138
  self._remote: Dict[str, str] = {} # execution id -> devbox id, for executions started through the durable API
137
139
  self.contexts: Dict[str, Any] = {} # build contexts by object id (in-process; see _context.py)
138
140
 
@@ -189,7 +191,7 @@ class Gateway:
189
191
  if mounts or secrets:
190
192
  return await self._create_with_mounts(body, mounts or [], secrets)
191
193
  with mp.translate_errors():
192
- return await self._sbx.create(**body)
194
+ return await create_as_vendor_user(self._sbx, **body)
193
195
  except (ex.InternalServerError, ex.RateLimitError) as e:
194
196
  retryable = isinstance(e.body, dict) and e.body.get("retryable") is True
195
197
  if isinstance(e, ex.RateLimitError) or not retryable or attempt == 6:
@@ -401,10 +403,13 @@ class Gateway:
401
403
  output: Optional[LogCallback] = None,
402
404
  shell_name: Optional[str] = None,
403
405
  attach_stdin: Optional[bool] = None,
406
+ stream: bool = False,
404
407
  ) -> _Exec:
405
408
  if shell_name:
406
409
  return self._shell_start(devbox_id, shell_name, command, stdout, stderr, output)
407
- if await self.durable(devbox_id):
410
+ # A command the caller waits for (``stream=True``) runs over the control channel, whose output is never cut; the
411
+ # gateway's durable execution keeps only the last 256 KiB.
412
+ if not stream and await self.durable(devbox_id):
408
413
  view = await self.remote_start(devbox_id, command, (stdout, stderr, output))
409
414
  rec = _Exec(execution_id=view.execution_id, devbox_id=devbox_id, command=command, handle=None, remote=True)
410
415
  rec.done = asyncio.Event()
@@ -422,7 +427,7 @@ class Gateway:
422
427
  asyncio.get_running_loop().create_task(self._watch(rec))
423
428
  return rec
424
429
 
425
- # --- durable executions (gateway #570) --------------------------------------------------
430
+ # --- durable executions --------------------------------------------------
426
431
 
427
432
  async def durable(self, devbox_id: str) -> bool:
428
433
  """Does the gateway have durable executions? Probed once; a missing sandbox is still a NotFoundError."""
@@ -636,7 +641,8 @@ class Gateway:
636
641
  async def execute(self, devbox_id: str, command: str, **kw: Any) -> DevboxAsyncExecutionDetailView:
637
642
  last_n = kw.pop("last_n", None)
638
643
  polling: Optional[PollingConfig] = kw.pop("polling_config", None)
639
- rec = await self.exec_start(devbox_id, command, **kw)
644
+ durable = bool(kw.pop("durable", False)) # True: run it as a gateway execution (output capped at 256 KiB)
645
+ rec = await self.exec_start(devbox_id, command, stream=not durable, **kw)
640
646
  assert rec.done is not None
641
647
  try:
642
648
  await asyncio.wait_for(rec.done.wait(), polling.timeout_seconds if polling else None)
@@ -747,6 +753,9 @@ class Gateway:
747
753
  if asynchronous:
748
754
  body["async"] = True
749
755
  d = await self._req("POST", f"/sandboxes/{_q(devbox_id)}/snapshots", body)
756
+ sid = d.get("snapshotId") or d.get("id")
757
+ if sid:
758
+ self._snapshot_sources[sid] = devbox_id
750
759
  return mp.to_snapshot_view(dict(d, name=d.get("name", name), metadata=d.get("metadata", metadata or {})), source_devbox_id=devbox_id)
751
760
 
752
761
  async def update_snapshot(self, snapshot_id: str, *, name: Optional[str] = None, metadata: Optional[Dict[str, str]] = None) -> DevboxSnapshotView:
@@ -777,10 +786,43 @@ class Gateway:
777
786
  raise PollingTimeout("Timed out waiting for snapshot", snap)
778
787
  await asyncio.sleep(cfg.interval_seconds)
779
788
 
780
- async def list_snapshots(self, limit: Optional[int] = None) -> List[DevboxSnapshotView]:
781
- qs = "?kind=sandbox" + (f"&limit={limit}" if limit else "")
782
- d = await self._req("GET", f"/snapshots{qs}")
783
- return [mp.to_snapshot_view(s) for s in d.get("snapshots", [])]
789
+ async def list_snapshots(
790
+ self,
791
+ limit: Optional[int] = None,
792
+ *,
793
+ starting_after: Optional[str] = None,
794
+ devbox_id: Optional[str] = None,
795
+ name: Optional[str] = None,
796
+ ) -> mp.DiskSnapshotsPage:
797
+ """Runloop's ``list_disk_snapshots``. ``devbox_id`` keeps only that devbox's snapshots: one counts when the gateway
798
+ reports its ``sandboxId`` or when this client made it (the gateway's list does not name the source yet, so
799
+ snapshots made elsewhere are left out rather than handed to another team). Pages are followed until ``limit``
800
+ matches are found, so ``has_more`` is right for a filtered list."""
801
+ want = limit if limit and limit > 0 else 100
802
+ kept: List[Tuple[Dict[str, Any], str]] = []
803
+ cursor: Optional[str] = None
804
+ skipping = starting_after is not None
805
+ for _ in range(200):
806
+ d = await self._req("GET", "/snapshots?kind=sandbox&limit=1000" + (f"&sandboxId={_q(devbox_id)}" if devbox_id is not None else "") + (f"&cursor={_q(cursor)}" if cursor else ""))
807
+ for s in d.get("snapshots", []):
808
+ source = s.get("sandboxId") or s.get("sourceSandboxId") or self._snapshot_sources.get(s.get("id") or "", "")
809
+ if devbox_id is not None and source != devbox_id:
810
+ continue
811
+ if name is not None and s.get("name") != name:
812
+ continue
813
+ if skipping:
814
+ if s.get("id") == starting_after:
815
+ skipping = False
816
+ continue
817
+ kept.append((s, source))
818
+ cursor = d.get("nextCursor") or None
819
+ if not cursor or len(kept) > want:
820
+ break
821
+ if skipping:
822
+ kept = [] # an unknown starting_after id: nothing follows it
823
+ more = len(kept) > want or (cursor is not None and len(kept) >= want)
824
+ views = [mp.to_snapshot_view(s, source_devbox_id=src) for s, src in kept[:want]]
825
+ return mp.DiskSnapshotsPage(views, has_more=more, total_count=len(views))
784
826
 
785
827
  async def get_snapshot(self, snapshot_id: str) -> DevboxSnapshotView:
786
828
  return mp.to_snapshot_view(await self._req("GET", f"/snapshots/{_q(snapshot_id)}"))
@@ -859,7 +901,7 @@ class Gateway:
859
901
  raise ex.NotFoundError(f"No blueprint named {blueprint_name!r}", body=None)
860
902
  return matches[-1].id
861
903
 
862
- # --- storage objects (gateway #574) / create-time mounts (#577) ---------------------------
904
+ # --- storage objects (gateway) / create-time mounts ---------------------------
863
905
 
864
906
  async def objects_available(self) -> bool:
865
907
  if self._objects is None:
@@ -930,7 +972,7 @@ class Gateway:
930
972
  with mp.translate_errors():
931
973
  return await self._sbx.connect(d["sandboxId"])
932
974
 
933
- # --- account secrets (gateway #583) -----------------------------------------------------
975
+ # --- account secrets (gateway) -----------------------------------------------------
934
976
 
935
977
  async def _secret_call(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
936
978
  try:
@@ -974,7 +1016,7 @@ class Gateway:
974
1016
  break
975
1017
  return out
976
1018
 
977
- # --- tunnels (gateway #575; per-port preview URLs on gateways without it) --------------
1019
+ # --- tunnels (gateway; per-port preview URLs on gateways without it) --------------
978
1020
 
979
1021
  @staticmethod
980
1022
  def _tunnel_obj(d: Dict[str, Any]) -> Any:
@@ -7,6 +7,7 @@ from __future__ import annotations
7
7
 
8
8
  import logging
9
9
  import math
10
+ import re
10
11
  import time
11
12
  from contextlib import contextmanager
12
13
  from datetime import datetime
@@ -144,13 +145,27 @@ def to_devbox_view(raw: Dict[str, Any], *, snapshot_id: Optional[str] = None, ke
144
145
  )
145
146
 
146
147
 
148
+ class DiskSnapshotsPage(list): # type: ignore[type-arg]
149
+ """``list_disk_snapshots`` result: the snapshots as a list (older callers iterate it) and, as in Runloop and in the
150
+ TypeScript package, ``.snapshots``, ``.has_more`` and ``.total_count``."""
151
+
152
+ def __init__(self, snapshots: List[DevboxSnapshotView], has_more: bool = False, total_count: Optional[int] = None) -> None:
153
+ super().__init__(snapshots)
154
+ self.has_more = has_more
155
+ self.total_count = len(snapshots) if total_count is None else total_count
156
+
157
+ @property
158
+ def snapshots(self) -> List[DevboxSnapshotView]:
159
+ return list(self)
160
+
161
+
147
162
  def to_snapshot_view(raw: Dict[str, Any], *, source_devbox_id: str = "") -> DevboxSnapshotView:
148
163
  """A Solari ``SnapshotView`` / create-snapshot response -> Runloop ``DevboxSnapshotView``."""
149
164
  view = DevboxSnapshotView(
150
165
  id=raw.get("id") or raw["snapshotId"],
151
166
  create_time_ms=_iso_to_ms(raw.get("createdAt")),
152
167
  metadata={str(k): str(v) for k, v in (raw.get("metadata") or {}).items()},
153
- source_devbox_id=raw.get("sourceSandboxId") or source_devbox_id,
168
+ source_devbox_id=raw.get("sandboxId") or raw.get("sourceSandboxId") or source_devbox_id,
154
169
  name=raw.get("name"),
155
170
  size_bytes=raw.get("sizeBytes"),
156
171
  )
@@ -197,12 +212,24 @@ def create_body(
197
212
  lp = dict(launch_parameters or {})
198
213
  for key, label in (
199
214
  ("network_policy_id", "network policies"),
200
- ("user_parameters", "user_parameters"),
201
215
  ("required_services", "required_services"),
202
216
  ):
203
217
  if lp.get(key):
204
218
  raise ex.SolariCompatUnsupported(label)
205
219
  cpu, mem_mb, disk_gb = resolve_size(lp)
220
+ user: Optional[str] = None
221
+ cwd: Optional[str] = None
222
+ up = lp.get("user_parameters")
223
+ if up:
224
+ # Runloop's launch_parameters.user_parameters {username, uid} picks the devbox user. The gateway creates the user (with
225
+ # passwordless sudo) and its home; it picks the uid itself, so a uid other than root's is noted and ignored.
226
+ username = up.get("username") if isinstance(up, dict) else getattr(up, "username", None)
227
+ uid = up.get("uid") if isinstance(up, dict) else getattr(up, "uid", None)
228
+ if not isinstance(username, str) or not re.fullmatch(r"[a-z_][a-z0-9_-]{0,31}", username):
229
+ raise ex.SolariCompatUnsupported("user_parameters.username", "use a valid Linux user name")
230
+ user, cwd = username, "/root" if username == "root" else f"/home/{username}"
231
+ if not (username == "root" and uid == 0):
232
+ log.warning("user_parameters.uid %s is ignored: Solari picks the uid of user %r", uid, username)
206
233
  meta: Dict[str, str] = dict(metadata or {})
207
234
  if name is not None:
208
235
  meta[NAME_KEY] = name
@@ -214,6 +241,8 @@ def create_body(
214
241
  "envs": dict(environment_variables) if environment_variables else None,
215
242
  "metadata": meta or None,
216
243
  "from_snapshot": snapshot_id,
244
+ "user": user,
245
+ "cwd": cwd,
217
246
  }
218
247
  idle = lp.get("after_idle") or (lp.get("lifecycle") or {}).get("after_idle")
219
248
  ka = lp.get("keep_alive_time_seconds")
@@ -0,0 +1,12 @@
1
+ """Sandbox ids are `<payload>.<signature>` (base64url, about 195 characters) and work as credentials: error messages
2
+ carry the first 8 characters only (the same rule as the TypeScript packages and core's close() warning)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import re
7
+
8
+ _ID_RE = re.compile(r"[A-Za-z0-9_-]{60,}\.[A-Za-z0-9_-]{30,}")
9
+
10
+
11
+ def redact_ids(text: str) -> str:
12
+ return _ID_RE.sub(lambda m: m.group(0)[:8] + "…", text)
@@ -135,8 +135,9 @@ class AsyncDiskSnapshots:
135
135
  def __init__(self, gw: Gateway) -> None:
136
136
  self._gw = gw
137
137
 
138
- async def list(self, *, limit: Optional[int] = None, **_: Any) -> List[DevboxSnapshotView]:
139
- return await self._gw.list_snapshots(limit)
138
+ async def list(self, *, limit: Optional[int] = None, starting_after: Optional[str] = None, devbox_id: Optional[str] = None,
139
+ source_devbox_id: Optional[str] = None, name: Optional[str] = None, **_: Any) -> Any:
140
+ return await self._gw.list_snapshots(limit, starting_after=starting_after, devbox_id=devbox_id or source_devbox_id, name=name)
140
141
 
141
142
  async def delete(self, snapshot_id: str, **_: Any) -> object:
142
143
  await self._gw.delete_snapshot(snapshot_id)
@@ -302,14 +303,14 @@ class AsyncDevboxes:
302
303
  return await self._gw.create(body, snapshot_id=params.get("snapshot_id"), post=post, name=params.get("name"), mounts=mounts, tunnel=tunnel, secrets=secrets)
303
304
 
304
305
  async def _solari_mounts(self, mounts: Any) -> Optional[List[Dict[str, Any]]]:
305
- """Runloop ``mounts`` -> the gateway's create-time object mounts (``{objectId, path, extract}``, pinetree-desktop#577)."""
306
+ """Runloop ``mounts`` -> the gateway's create-time object mounts (``{objectId, path, extract}``)."""
306
307
  out: List[Dict[str, Any]] = []
307
308
  for m in mounts or []:
308
309
  kind = m.get("type")
309
310
  if kind != "object_mount":
310
311
  raise unsupported_(f"mount type {kind!r}", "Only object_mount is supported.")
311
312
  if not await self._gw.objects_available():
312
- raise unsupported_("object_mount", "This gateway has no storage objects / object mounts yet (pinetree-desktop#574, #577).")
313
+ raise unsupported_("object_mount", "This gateway has no storage objects / object mounts yet.")
313
314
  info = await self._gw.object_get(m["object_id"])
314
315
  names = (info.get("name", "") + " " + info.get("contentType", "")).lower()
315
316
  extract = any(t in names for t in (".tgz", ".tar.gz", "gzip", "x-tar"))
@@ -17,6 +17,8 @@ from ._loop import LoopThread
17
17
  def wrap_result(res: Any, loop: LoopThread) -> Any:
18
18
  if getattr(type(res), "_solari_mirror", False):
19
19
  return SyncMirror(res, loop)
20
+ if type(res).__name__ == "DiskSnapshotsPage": # a list that also carries .snapshots / .has_more / .total_count
21
+ return res
20
22
  if isinstance(res, list):
21
23
  return [wrap_result(x, loop) for x in res]
22
24
  return res
@@ -0,0 +1,45 @@
1
+ """Create sandboxes that run as Runloop's default user (commands, code and files default to its home)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import warnings
7
+ from typing import Any
8
+
9
+ from solari_core.errors import GatewayError
10
+
11
+ from ._exceptions import SolariCompatUnsupported
12
+
13
+ VENDOR_USER = "user"
14
+ VENDOR_HOME = "/home/user"
15
+
16
+
17
+ def _refuses_user_fields(e: BaseException) -> bool:
18
+ return isinstance(e, GatewayError) and e.status == 400 and re.search(r"\b(user|cwd)\b", repr(getattr(e, "body", None)), re.I) is not None
19
+
20
+
21
+ def _warn_root() -> None:
22
+ warnings.warn(
23
+ "solari-runloop-compat: the server or this template's image predates user support, so the sandbox runs as root instead of 'user'. "
24
+ "Rebuild templates and snapshots made before user support shipped to get the vendor user.",
25
+ RuntimeWarning,
26
+ stacklevel=4,
27
+ )
28
+
29
+
30
+ async def create_as_vendor_user(solari: Any, **opts: Any) -> Any:
31
+ """``solari.create(**opts)`` with ``user`` / ``cwd`` set to Runloop's defaults. A gateway that predates them (it answers 400
32
+ naming them) gets the plain create, and the sandbox runs as root there (COMPAT.md). Restores from a snapshot keep the
33
+ snapshot's own user and are sent without them."""
34
+ if opts.get("from_snapshot") is not None:
35
+ return await solari.create(**opts)
36
+ explicit = opts.get("user") is not None # a user the caller named (launch_parameters.user_parameters) wins
37
+ try:
38
+ return await solari.create(**{"user": VENDOR_USER, "cwd": VENDOR_HOME, **opts})
39
+ except GatewayError as e:
40
+ if not _refuses_user_fields(e):
41
+ raise
42
+ if explicit: # the default user is best effort on a gateway that predates user/cwd; a user the caller named is not
43
+ raise SolariCompatUnsupported("user_parameters", "this gateway cannot create sandboxes as another user yet") from e
44
+ _warn_root()
45
+ return await solari.create(**opts)
@@ -142,7 +142,7 @@ class AsyncFileInterface:
142
142
 
143
143
 
144
144
  class AsyncNetworkInterface:
145
- """Runloop's one-tunnel-per-devbox API over Solari's tunnel (pinetree-desktop#575); on a gateway without it, an open
145
+ """Runloop's one-tunnel-per-devbox API over Solari's tunnel; on a gateway without it, an open
146
146
  per-port preview URL."""
147
147
 
148
148
  _solari_mirror = True
@@ -330,8 +330,8 @@ class AsyncSnapshotOps:
330
330
  self._client = client
331
331
 
332
332
  async def list(self, **params: Any) -> List[AsyncSnapshot]:
333
- snaps = await self._client.devboxes.disk_snapshots.list(**params)
334
- return [AsyncSnapshot(self._client, s.id) for s in snaps]
333
+ page = await self._client.devboxes.disk_snapshots.list(**params)
334
+ return [AsyncSnapshot(self._client, s.id) for s in page.snapshots]
335
335
 
336
336
  def from_id(self, snapshot_id: str) -> AsyncSnapshot:
337
337
  return AsyncSnapshot(self._client, snapshot_id)
@@ -393,7 +393,7 @@ class AsyncBlueprintOps:
393
393
 
394
394
 
395
395
  class AsyncStorageObject:
396
- """A Runloop storage object. Backed by the gateway's ``/objects`` when it has them (pinetree-desktop#574); otherwise a
396
+ """A Runloop storage object. Backed by the gateway's ``/objects`` when it has them; otherwise a
397
397
  build context held by this client (``_context.py``), which can only be used as a ``build_context``."""
398
398
 
399
399
  _solari_mirror = True
@@ -181,7 +181,7 @@ async def test_durable_exec_start_wait_and_view():
181
181
  ("POST", "/sandboxes/sb%3A1/executions"): EXEC_RUNNING,
182
182
  ("GET", "/sandboxes/sb%3A1"): RAW,
183
183
  })
184
- res = await g.execute("sb:1", "echo o; exit 7")
184
+ res = await g.execute("sb:1", "echo o; exit 7", durable=True)
185
185
  start = [c for c in s.calls if c[0] == "POST" and c[1].endswith("/executions")][0]
186
186
  assert start[2]["cmd"] == "/bin/bash" and start[2]["env"] == {"SOLARI_USER_CMD": "echo o; exit 7"}
187
187
  assert (res.exit_status, res.stdout, res.stderr, res.stderr_truncated, res.status) == (7, "o\n", "e\n", True, "completed")
@@ -563,7 +563,7 @@ async def test_durable_exec_on_a_native_image_build_avoids_the_login_shell():
563
563
  ("POST", "/sandboxes/sb%3A1/executions"): EXEC_RUNNING,
564
564
  ("GET", "/sandboxes/sb%3A1"): {**RAW, "fromImage": "docker.io/library/golang:1.22"},
565
565
  })
566
- await g.execute("sb:1", "echo $PATH")
566
+ await g.execute("sb:1", "echo $PATH", durable=True)
567
567
  start = [c for c in s.calls if c[0] == "POST" and c[1].endswith("/executions")][0]
568
568
  assert start[2]["cmd"] == "/bin/sh" and start[2]["args"][0] == "-c" and "-l" not in start[2]["args"][0]
569
569
  assert "/bin/bash -c" in start[2]["args"][1] and start[2]["args"][-1] == g._remote_script()
@@ -571,7 +571,7 @@ async def test_durable_exec_on_a_native_image_build_avoids_the_login_shell():
571
571
 
572
572
  @pytest.mark.asyncio
573
573
  async def test_cleanup_shutdown_failure_never_logs_the_whole_id(caplog):
574
- token = "AmByE367p4swyUL_N6WF5CiDMT9I4F4Xr3r.iVPUw-Zx82gtp3OkR5WDEvkHmuvgG06zp9S9zdDkV4M"
574
+ token = "AmByE367p4swyUL_N6WF5CiDMT9I4F4Xr3r" + "x" * 105 + ".iVPUw-Zx82gtp3OkR5WDEvkHmuvgG06zp9S9zdDkV4M"
575
575
  quoted = sr._gateway.quote(token, safe="")
576
576
  g, _ = gw({("DELETE", "/sandboxes/"): RuntimeError(f"DELETE /sandboxes/{token} failed; retry /sandboxes/{quoted}")})
577
577
  with caplog.at_level("ERROR", logger="solari_runloop"):
@@ -580,3 +580,111 @@ async def test_cleanup_shutdown_failure_never_logs_the_whole_id(caplog):
580
580
  assert "AmByE367…" in text
581
581
  assert token not in text and quoted not in text and token[:20] not in text
582
582
  assert all(r.exc_info is None for r in caplog.records), "no traceback: exception messages carry the id"
583
+
584
+
585
+ @pytest.mark.asyncio
586
+ async def test_list_disk_snapshots_filters_by_devbox_and_returns_the_ts_shape():
587
+ snaps = [
588
+ {"id": "snap_1", "name": "a", "sizeBytes": 1, "createdAt": "2026-10-27T00:00:00Z", "sandboxId": "dbx_mine", "metadata": {"team": "x"}},
589
+ {"id": "snap_2", "name": "b", "sizeBytes": 1, "createdAt": "2026-10-27T00:00:01Z", "sourceSandboxId": "dbx_other"},
590
+ {"id": "snap_3", "name": "c", "sizeBytes": 1, "createdAt": "2026-10-27T00:00:02Z", "sourceSandboxId": "dbx_mine"},
591
+ {"id": "snap_4", "name": "d", "sizeBytes": 1, "createdAt": "2026-10-27T00:00:03Z"},
592
+ ]
593
+ g, _ = gw({("GET", "/snapshots"): {"snapshots": snaps}})
594
+ mine = await g.list_snapshots(devbox_id="dbx_mine")
595
+ assert [s.id for s in mine.snapshots] == ["snap_1", "snap_3"] and mine.has_more is False
596
+ assert any("sandboxId=dbx_mine" in c[1] for c in g._http.calls), "the gateway filter is sent as sandboxId"
597
+ assert mine.snapshots[0].source_devbox_id == "dbx_mine" and mine.snapshots[0].metadata == {"team": "x"}
598
+ assert list(mine) == mine.snapshots # still usable as a list
599
+ none = await g.list_snapshots(devbox_id="dbx_no_snapshots")
600
+ assert none.snapshots == [] and none.has_more is False
601
+ page = await g.list_snapshots(1, devbox_id="dbx_mine")
602
+ assert [s.id for s in page.snapshots] == ["snap_1"] and page.has_more is True
603
+ nxt = await g.list_snapshots(1, starting_after="snap_1", devbox_id="dbx_mine")
604
+ assert [s.id for s in nxt.snapshots] == ["snap_3"] and nxt.has_more is False
605
+
606
+
607
+ def test_error_messages_carry_only_the_first_8_characters_of_a_sandbox_id():
608
+ token = "AmByE367p4swyUL_N6WF5CiDMT9I4F4Xr3r" + "x" * 105 + ".iVPUw-Zx82gtp3OkR5WDEvkHmuvgG06zp9S9zdDkV4M"
609
+ e = sr.NotFoundError(f"Devbox {token} not found")
610
+ assert "AmByE367…" in str(e) and token not in str(e) and token not in e.message
611
+ for text in ("File not found: /home/user/project-configuration-file.production-settings", "lookup my-internal-service-name.internal-example-domain.com failed", "api-sta.getsolari.com"):
612
+ assert str(sr.NotFoundError(text)) == text, "ordinary paths and hostnames pass through untouched"
613
+
614
+
615
+ @pytest.mark.asyncio
616
+ async def test_create_asks_for_runloops_user_and_falls_back_on_a_gateway_that_refuses_it():
617
+ from solari_core.errors import GatewayError
618
+ from solari_core.types import GatewayErrorBody
619
+ from solari_runloop._vendor_user import create_as_vendor_user
620
+
621
+ class Fake:
622
+ def __init__(self, refuse): self.refuse, self.calls = refuse, []
623
+ async def create(self, **kw):
624
+ self.calls.append(kw)
625
+ if self.refuse and "user" in kw:
626
+ raise GatewayError(400, "unknown field: user", GatewayErrorBody(code="ValidationError", message="unknown field: user"))
627
+ return "ok"
628
+
629
+ f = Fake(False)
630
+ assert await create_as_vendor_user(f, template="base") == "ok"
631
+ assert f.calls[0]["user"] == "user" and f.calls[0]["cwd"] == "/home/user"
632
+ f = Fake(True)
633
+ assert await create_as_vendor_user(f, template="base") == "ok"
634
+ assert len(f.calls) == 2 and "user" not in f.calls[1]
635
+ f = Fake(False)
636
+ await create_as_vendor_user(f, from_snapshot="snap_1")
637
+ assert "user" not in f.calls[0], "a restore keeps the snapshot's own user"
638
+
639
+
640
+ @pytest.mark.asyncio
641
+ async def test_a_400_that_does_not_name_user_or_cwd_is_not_retried():
642
+ from solari_core.errors import GatewayError
643
+ from solari_core.types import GatewayErrorBody
644
+ from solari_runloop._vendor_user import create_as_vendor_user
645
+
646
+ class Fake:
647
+ calls = 0
648
+
649
+ async def create(self, **kw):
650
+ Fake.calls += 1
651
+ raise GatewayError(400, "bad template", GatewayErrorBody(code="ValidationError", message="template tpl_x does not exist"))
652
+
653
+ with pytest.raises(GatewayError):
654
+ await create_as_vendor_user(Fake(), template="tpl_x")
655
+ assert Fake.calls == 1
656
+
657
+
658
+ def test_user_parameters_pick_the_create_user_and_its_home(caplog):
659
+ import logging
660
+
661
+ body = lambda up: sr._mapping.create_body(launch_parameters={"user_parameters": up}) # noqa: E731
662
+ with caplog.at_level(logging.WARNING, logger="solari_runloop"):
663
+ dev = body({"username": "dev", "uid": 1001})
664
+ root = body({"username": "root", "uid": 0})
665
+ assert (dev["user"], dev["cwd"]) == ("dev", "/home/dev") and (root["user"], root["cwd"]) == ("root", "/root")
666
+ assert len([r for r in caplog.records if "uid" in r.getMessage()]) == 1, "the uid is chosen by Solari: said once, not for root/0"
667
+ with pytest.raises(sr.SolariCompatUnsupported):
668
+ body({"username": "Bad Name!", "uid": 1})
669
+ assert "user" not in sr._mapping.create_body()
670
+
671
+
672
+ @pytest.mark.asyncio
673
+ async def test_a_user_the_caller_named_wins_and_a_gateway_that_cannot_do_it_is_an_error():
674
+ from solari_core.errors import GatewayError
675
+ from solari_core.types import GatewayErrorBody
676
+ from solari_runloop._vendor_user import create_as_vendor_user
677
+
678
+ class Fake:
679
+ def __init__(self, refuse): self.refuse, self.calls = refuse, []
680
+ async def create(self, **kw):
681
+ self.calls.append(kw)
682
+ if self.refuse and "user" in kw:
683
+ raise GatewayError(400, "unknown field: user", GatewayErrorBody(code="ValidationError", message="unknown field: user"))
684
+ return "ok"
685
+
686
+ f = Fake(False)
687
+ await create_as_vendor_user(f, user="dev", cwd="/home/dev")
688
+ assert (f.calls[0]["user"], f.calls[0]["cwd"]) == ("dev", "/home/dev")
689
+ with pytest.raises(sr.SolariCompatUnsupported):
690
+ await create_as_vendor_user(Fake(True), user="dev", cwd="/home/dev")
@@ -1,4 +1,4 @@
1
- """Runs the Runloop-style flows against a real gateway (staging). Skipped unless SOLARI_API_KEY and
1
+ """Runs the Runloop-style flows against a real staging gateway. Skipped unless SOLARI_API_KEY and
2
2
  SOLARI_BASE_URL are set and ``-m live`` is passed. Everything created is deleted in teardown."""
3
3
 
4
4
  from __future__ import annotations
@@ -216,7 +216,7 @@ def test_blueprint_with_a_build_context_copy_and_add(sdk: sr.RunloopSDK, cleanup
216
216
 
217
217
 
218
218
  def test_phase2_name_update_paging_and_async_snapshot(sdk: sr.RunloopSDK, cleanup: List) -> None:
219
- """Needs a gateway with pinetree-desktop#566 (PATCH, startingAfter/hasMore, async snapshots, snapshot update)."""
219
+ """Needs a gateway with PATCH, startingAfter/hasMore, async snapshots and snapshot update."""
220
220
  a = sdk.devbox.create(name="p2-a", metadata={"k": "v"})
221
221
  b = sdk.devbox.create(name="p2-b")
222
222
  cleanup.extend([("devbox", a.id), ("devbox", b.id)])
@@ -1,84 +0,0 @@
1
- # Blueprints (Runloop) on Solari: design and status
2
-
3
- A Runloop *blueprint* is a reusable devbox image built from a Dockerfile (plus setup commands, file mounts, a build
4
- context, launch parameters). A Solari *template* is a golden VM snapshot built by running ordered steps inside a VM
5
- cloned from a base golden (`POST /templates` with a `CompiledImage`: `{base|fromTemplate, packages, steps[]}`,
6
- `building -> ready|failed`, build logs at `GET /templates/{id}/logs`). So the mapping is "Dockerfile -> recipe", not
7
- "Dockerfile -> OCI image".
8
-
9
- ## Level 1: shipped in this PR (client side, no gateway change)
10
- `solari_runloop/_dockerfile.py` compiles a Dockerfile subset into the existing recipe, and `client.blueprints.*` /
11
- `sdk.blueprint.*` drive `/templates`. Verified on staging: a Dockerfile + `system_setup_commands` + `file_mounts` blueprint
12
- builds in ~40 s, a devbox created from it sees the baked files, and the template is deleted afterwards.
13
-
14
- | Runloop | Solari |
15
- |---|---|
16
- | `dockerfile` `FROM ubuntu/debian[:tag]`, `base`, `workstation` | `base` golden |
17
- | `base_blueprint_name` / `base_blueprint_id` | `fromTemplate` (name resolved to `tpl_` id) |
18
- | `RUN` (shell or JSON form) | `{op:"run"}` step (ARGs exported into the command) |
19
- | `ENV` | `{op:"env"}` step |
20
- | `WORKDIR`, `ENTRYPOINT`, `CMD` | `{op:"workdir","dir"}`, `{op:"entrypoint"}`, `{op:"cmd"}` |
21
- | `ARG` + `build_args` | substituted / exported |
22
- | `system_setup_commands` | `run` steps after the Dockerfile |
23
- | `file_mounts {path: contents}` | `run` step that base64-writes each file (small files only) |
24
- | `launch_parameters` size | `cpu`/`memMb` on the template row, same size table as devboxes |
25
- | status `building / ready / failed` | `building / build_complete / failed` |
26
- | blueprint id | `templateId` (`tpl_...`); `create(template=)` takes the **id** or a built-in name |
27
-
28
- Rejected loudly (`SolariCompatUnsupported`): a `FROM` from a registry outside the allowlist, `FROM scratch`, multi-stage builds,
29
- `COPY`/`ADD`, `USER`, `VOLUME`, `HEALTHCHECK`, `ONBUILD`, `build_context`, `code_mounts`, `services`, `secrets`.
30
-
31
- Findings worth fixing in the gateway docs: `openapi.yaml` shows `{op:"workdir", path}` but the SDKs (and so the
32
- pipeline) use `{op:"workdir", dir}`; `localFiles` is rejected (`LocalFilesUnsupported`), which is why `COPY` is not in level 1.
33
-
34
- ## Level 2: `COPY`/`ADD` and `build_context`
35
- **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.
36
-
37
- ### Proper version (needs bug2's storage objects)
38
- 1. Build context = a storage object (`.tar.gz`, `GET /objects/{id}/download-url`).
39
- 2. New recipe field `contextObjectId` and a new step op `{op:"copy", src, dest, chown?}`; the build VM downloads and extracts the
40
- object to `/tmp/build-context`, then `copy` is `cp -a` from there (`ADD` of a local tar = `tar -x`).
41
- 3. Compat layer: `build_context={type:"object", object_id}` passes through; `COPY`/`ADD` translate to `copy` steps;
42
- `.dockerignore` is applied client-side when the SDK uploads the directory (`storage_object.upload_from_dir`).
43
- Gateway work: `contextObjectId` validation (same org), the `copy` op in the build executor, ~2 days; tests for wrong-org objects.
44
-
45
- ## Level 3a: any public `FROM <image>` by chroot import (SUPERSEDED by 3b for new builds; Python compat now emits `fromImage`)
46
- `FROM python:3.12-alpine`, `FROM node:20`, `FROM ghcr.io/org/img:tag`, and (with `build_args={"SOLARI_IMPORT": "1"}`) `FROM ubuntu`/`debian`
47
- **as an imported image** instead of the native base. How: the build steps (a) install `crane` (pinned `v0.20.3`, tarball sha256 checked
48
- at download, the binary's sha256 **re-checked before every use**, the build fails on a mismatch), (b) check the manifest size against
49
- the cap before downloading, (c) `crane export --platform linux/amd64 <image>` piped into `solari-extract`, a validating tar extractor,
50
- into `/srv/root`, (d) install `solari-run`, which chroots into `/srv/root` with the Dockerfile's `ENV` (`/etc/solari-env`) and `WORKDIR`
51
- (`/etc/solari-workdir`). The existing orchestrator snapshots the builder as a normal template. At runtime the compat layer sees
52
- `/etc/solari-rootdir` and runs `cmd.exec` through `solari-run`, and maps file paths under the root.
53
- Verified live: `python:3.12-alpine` (musl, `python --version` = 3.12), `debian:bookworm-slim`, `ubuntu:22.04`: the process sees the image's
54
- `/etc/os-release`, `ENV`, `WORKDIR`, baked files; file API reads are inside the root; a symlink out of the root is refused (403).
55
-
56
- | Guard | Where | Test |
57
- |---|---|---|
58
- | crane pinned by version + sha256, re-verified at use | `import_steps` | `test_crane_is_pinned_and_checked_at_use` |
59
- | 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...` |
60
- | 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 |
61
- | 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) |
62
- | file API never follows a symlink out of the root (guest `realpath` re-check) | `Gateway._abs` | live test |
63
- | `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 |
64
-
65
- **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
66
- 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
67
- `/etc/solari-cmd` but **not started**; public registries only; amd64 only; absolute symlinks inside the image resolve against the host in the file API,
68
- 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
69
- no PID 1/init in the image (no systemd), and a `RUN` that needs a running daemon fails.
70
- The Python compat layer no longer emits these steps (it sends `compiled.fromImage`, level 3b); the exec/fs marker-file handling stays for templates built earlier.
71
-
72
- ## Level 3b: native, for every SDK (assigned to bug1; archi-sandbox's block list applies)
73
- guest-agent `rootDir` mode (exec chroots, fs ops use a symlink-safe join, rootDir immutable, capabilities dropped), `fromImage` on `POST /templates`
74
- (org-scoped, registry allowlist, digest pinned at build time and recorded), builder `diskGb` (bounded), the OCI config (Env, WorkingDir, Entrypoint, Cmd, User)
75
- applied at create. Needs a guest rebake + re-pin before prod. The marker-file contract above keeps 3a templates working.
76
-
77
- ## Level 3c: real rootfs rebuild (fidelity; later)
78
- `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.
79
- The `python:X` -> `base` + install shortcut stays out unless opted in explicitly.
80
-
81
- ## Risks
82
- Untrusted builds (egress, CPU time, disk) need quotas before this is exposed beyond staging; `RUN` steps that rely on BuildKit
83
- features (`--mount=type=cache`, heredocs) are not supported; blueprint *versioning* (Runloop's immutable ids per build) is
84
- `tpl_` ids here, so rebuilding under the same name creates a new id.
@@ -1,64 +0,0 @@
1
- # Target gateway API for Runloop compatibility (proposal, v1)
2
-
3
- Build to these shapes and the compat packages (`solari_runloop`, `@solarisdk/runloop-compat`) will wire to them. Shapes follow
4
- the gateway's existing conventions: camelCase JSON, opaque signed ids, `Idempotency-Key` on creates, errors as
5
- `{code,error,message,retryable}`. If you must deviate, change this file in the same PR and tell feat1.
6
- Everything is scoped to the caller's org like the existing `/sandboxes/*` routes. "SandboxView" is the existing view.
7
-
8
- ## 1. Durable executions + logs (owner: feat2)
9
- Why: Runloop's `execute_async` returns an `execution_id` that is retrievable, waitable and killable from any process.
10
- Today `cmd.start` is a live WebSocket handle only.
11
-
12
- | Route | Body / query | Response |
13
- |---|---|---|
14
- | `POST /sandboxes/{id}/executions` | `{cmd, args?, cwd?, env?, user?, shellName?, attachStdin?}` (`cmd` = argv[0]; the compat layer sends `/bin/bash -lc "<string>"`) | `201 ExecutionView` |
15
- | `GET /sandboxes/{id}/executions/{eid}` | `?lastN=<lines>` | `ExecutionView` |
16
- | `GET /sandboxes/{id}/executions` | `?limit&cursor&status` | `{executions: ExecutionView[], nextCursor?}` |
17
- | `POST /sandboxes/{id}/executions/{eid}/wait` | `{timeoutMs?}` long-poll (cap 30 s per call) | `ExecutionView` (status `running` if the wait timed out) |
18
- | `POST /sandboxes/{id}/executions/{eid}/kill` | `{signal?}` | `ExecutionView` |
19
- | `POST /sandboxes/{id}/executions/{eid}/stdin` | `{data, eof?}` | `{ok:true}` |
20
- | `GET /sandboxes/{id}/executions/{eid}/stream` | `?stream=stdout\|stderr\|both&fromSeq=` SSE: `data: {"seq":n,"stream":"stdout","data":"..."}` then `event: exit` | stream |
21
- | `GET /sandboxes/{id}/logs` | `?executionId&source&lastN&cursor&limit` | `{logs:[{ts,source:"stdout"\|"stderr"\|"entrypoint"\|"system",executionId?,message}], nextCursor?}` |
22
-
23
- ```
24
- ExecutionView = { executionId, sandboxId, status: "queued"|"running"|"completed", exitCode?: int,
25
- stdout: string, stderr: string, stdoutTruncated: bool, stderrTruncated: bool,
26
- shellName?: string, startedAt, finishedAt? }
27
- ```
28
- Semantics: output is buffered server-side (suggest 1 MiB per stream, tail kept, `*Truncated` set) and survives the client
29
- disconnecting; records are kept >= 24 h after exit. A paused sandbox keeps its records. `status:"completed"` with
30
- `exitCode` absent means the sandbox died mid-run. The HTTP `POST /sandboxes/{id}/exec` fast path stays as is.
31
-
32
- **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,
33
- 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
34
- `stdout|stderr|system` (+ `entrypoint`, always empty for now), `system` lines are "execution started: <cmd>" / "execution exited with code N", the cursor is an opaque
35
- numeric offset; shared-context sandboxes get 409 `NotSupported`; wait/kill/stdin only work on the pod that started the run, else 409 `ExecutionOnOtherInstance`
36
- (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;
37
- `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.
38
-
39
- ## 2. Names, metadata, pagination, snapshots (owner: bug3)
40
- - `PATCH /sandboxes/{id}` `{name?: string|null, metadata?: {string:string}}` -> `SandboxView` (metadata is replaced, not merged;
41
- send `null` to clear a field). Add first-class `name?: string` and `template` to `SandboxView`/create (`name` in
42
- `POST /sandboxes`). Until it ships the compat layer stores the name under metadata key `runloop.name`.
43
- - `GET /sandboxes` gains `startingAfter=<sandboxId>` (exclusive; fall back to 400 if unknown) and returns
44
- `{sandboxes, nextCursor?, hasMore: bool, totalCount?: int}` (`includeTotalCount=true` to get it). Keep `cursor`.
45
- - Snapshots: `POST /sandboxes/{id}/snapshots` accepts `{name?, metadata?, commitMessage?}`; `SnapshotView` gains
46
- `metadata`, `commitMessage?`, `sourceSandboxId`; `PATCH /snapshots/{id}` `{name?, metadata?, commitMessage?}`.
47
- Optional `?wait=false` on create returns early with `status:"pending"` and `GET /snapshots/{id}` shows `status: pending|ready|failed`
48
- (default stays synchronous).
49
- - Named persistent shells: `shellName` on execution create = one persistent bash per `(sandboxId, shellName)`; commands queue
50
- one at a time, cwd/env persist (Runloop `devbox.shell("name")`). First use creates the shell.
51
-
52
- ## 3. Storage objects, mounts, tunnels (owner: bug2)
53
- - `POST /objects` `{name, contentType?, ttlMs?}` -> `{objectId, uploadUrl, uploadHeaders?}`; client PUTs the bytes;
54
- `POST /objects/{id}/complete`; `GET /objects/{id}` -> `{objectId,name,contentType,sizeBytes,state:"uploading"|"ready",createdAt,expiresAt?}`;
55
- `GET /objects/{id}/download-url` -> `{url, expiresAt}`; `DELETE /objects/{id}`; `GET /objects?limit&cursor&name&contentType`.
56
- - Mounts at create: `POST /sandboxes` accepts `mounts: [{objectId, path, extract?: bool}]` (a `.tar.gz` object with
57
- `extract:true` is unpacked at `path`; otherwise placed as a file).
58
- - Tunnel: `POST /sandboxes/{id}/tunnel` `{authMode?: "open"|"authenticated", wakeOnHttp?: bool, keepAlive?: bool}` ->
59
- `{urlTemplate: "https://{port}-<key>.<domain>", authToken?, authMode}`; `GET` same shape; `DELETE`. The existing
60
- per-port `GET /sandboxes/{id}/ports/{port}` stays.
61
-
62
- ## 4. Blueprints from a Dockerfile (owner: feat1 to sketch, see BLUEPRINTS.md)
63
- `POST /templates` additionally accepts `{name, dockerfile, buildContext?: objectId, systemSetupCommands?: string[], launchCommands?: string[], baseTemplate?}`;
64
- `TemplateView`/`GET /templates/{id}/logs` unchanged (status `building|ready|failed`).