diff --git a/changelog.d/fixed-crux-runs-docs.md b/changelog.d/fixed-crux-runs-docs.md new file mode 100644 index 0000000000..d84df7053c --- /dev/null +++ b/changelog.d/fixed-crux-runs-docs.md @@ -0,0 +1 @@ +- `docs/crux-serve.md` and `docs/env-vars.md` now document `crux serve --runs-config` / `CRUX_RUNS_CONFIG` and the `/v1/runs` routes, and the work-services design doc reflects that S2 and S7 shipped (#17027, #17028). diff --git a/src/docs/crux-serve.md b/src/docs/crux-serve.md index f16325f2a9..31e79e8b47 100644 --- a/src/docs/crux-serve.md +++ b/src/docs/crux-serve.md @@ -37,6 +37,7 @@ runtime and every agent must arrive as a definition on `POST /v1/agents`. | `--checkout-allow PREFIX,…`, `CRUX_CHECKOUT_ALLOWLIST` | repository URL prefixes `POST /v1/checkouts` may clone; unset means no checkout service ([design](design/crux-work-services.md)). | | `--checkout-dir PATH`, `CRUX_CHECKOUT_DIR` | where pinned checkouts live. Default `/checkouts`. | | `--lanes-config PATH`, `CRUX_LANES_CONFIG` | opt into [durable event/work lanes](crux-lanes.md) on this same server, backed by NATS JetStream. Lane project credentials are separate from agent-control credentials. | +| `--runs-config PATH`, `CRUX_RUNS_CONFIG` | contained-run configuration file that supplies the sandbox backend for `POST /v1/runs`. Without it the server still serves saved run records under `/runs` (`GET /v1/runs/{id}`), and `POST /v1/runs` answers `501`; runs left in flight by an earlier process are marked unfinished at startup ([design](design/crux-work-services.md)). | | `--hive-callback ADDR`, `CRUX_HIVE_SOCKET` (+ `CRUX_HIVE_TOKEN`) | dial hive's callback endpoint (`crux/api/callback`) for the capabilities hive owns — scoped GitHub tokens, PR creation, Linear credentials, text/canary scanners, conditions — and feed the runtime's seams from it instead of leaving them nil. Health reports it under `hive_callback`; an unreachable endpoint raises the `hive_callback_unavailable` condition. (#14246) When the runtime is a manager it also polls hive's host policy from the same endpoint; see [Host policy from hive](#host-policy-from-hive-14138-stage-4). | `serve` does not use the per-work-dir control socket that a foreground @@ -95,6 +96,7 @@ and [lane error codes and failure behavior](crux-lanes.md#bounds-and-failure-beh | `POST /v1/agents/{name}/stop` | | `Lifecycle.Stop` | `{"agent","process"}` | | `GET /v1/events` | | watcher + `Kicker.SetKickObserver` + the `crux.Host` observers | `text/event-stream` of `Event` records | | `POST /v1/checkouts`, `GET /v1/checkouts[?owner=]`, `GET`/`DELETE /v1/checkouts/{id}` | `{"repo","commit","owner"?,"branches"?,"max_bytes"?,"ttl"?}` | `checkout.Service` | Work service (S1): a worktree pinned at a full SHA, owned by the caller principal; `501` without `--checkout-allow`; [routes, codes and semantics](design/crux-work-services.md) | +| `POST /v1/runs`, `GET /v1/runs/{id}`, `POST /v1/runs/{id}/cancel` | contained-run request (see `ContainedRunRequest` in `crux/api/runs.go`) | `runs.Service` | Work service (S2/S7): run an untrusted command in a sandbox and read the saved record whatever the process state; cancel after completion returns the result; `501` on `POST` without `--runs-config`; restart and listing routes are [deferred](design/crux-work-services.md#deferred-runs-routes) | | `GET /v1/lanes` and lane/group subroutes | Publish/recovery/receipt JSON; [request shapes](crux-lanes.md#public-http-and-go-api) | `lanes.Broker` | Opt-in only; lane-project credential and capability ACLs; JSON or `204`; [full routes and responses](crux-lanes.md#public-http-and-go-api) | ### Runtime families (#14138 stage 3) diff --git a/src/docs/design/crux-work-services.md b/src/docs/design/crux-work-services.md index 1530515246..1071465854 100644 --- a/src/docs/design/crux-work-services.md +++ b/src/docs/design/crux-work-services.md @@ -1,8 +1,7 @@ # Crux work services: S1 pinned checkout (hivecommons/crux#114) Status: **S0 caller principals and S1 pinned checkout shipped in hive -`src/crux` (v5).** S2 contained run and S7 minimum are in flight in a -sibling change; everything else in the RFC is unscheduled. This records +`src/crux` (v5).** S2 contained run and S7 minimum shipped in #17014; everything else in the RFC is unscheduled. This records S1 *as implemented*, including where it is weaker than the RFC text. The RFC asks for "a working copy of this repo at this commit, owned by @@ -143,12 +142,18 @@ a `.jsonl` index. - TTL sweeper (recorded, not enforced). - `--filter=blob:limit=` partial clones; the cap is post-hoc only. - A per-owner allowlist; one list per server. -- Wiring `InUse` to live runs: that is S2's side of the seam. +- Wiring `InUse` to live runs: that is S2's side of the seam; the S2 commit (#17014) did not wire it, so it remains an open follow-up. - `ssh://` and `http://` repositories; `git@` syntax. - Anything about the hivecommons/crux repository or the publish path: the service lives in hive `src/crux` and ships through the existing mirror unchanged. +## Deferred runs routes + +The runs routes (`POST /v1/runs`, `GET /v1/runs/{id}`, +`POST /v1/runs/{id}/cancel`) shipped in #17014. Restart and listing routes +for runs are deferred and not scheduled. + ## Package map | Path | Role | diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 3abd2bb8fa..ca69978586 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -130,6 +130,7 @@ project capabilities, deployment requirements and recovery. | Variable | Required | Default | Purpose | |---|---:|---|---| | `CRUX_LANES_CONFIG` | No | none (durable lanes disabled) | Crux server's lane configuration file, used when `crux serve --lanes-config` is absent. An explicit flag takes precedence. Broker credentials and project tokens are referenced by environment variable name in that file, not embedded as secret values. | +| `CRUX_RUNS_CONFIG` | No | none (no contained-run backend; saved run records are still served) | Crux server's contained-run configuration file, used when `crux serve --runs-config` is absent. An explicit flag takes precedence. | | `HIVE_LANES_ADDRESS` | No | none (participant disabled) | Opts the Hive process into a Crux API endpoint. This is the Crux server address, not the NATS broker URL. | | `HIVE_LANES_LANE` | Yes when `HIVE_LANES_ADDRESS` is set | none | Registered lane ID for the Hive participant. Missing lane, group or token logs an explicit configuration error and leaves participation disabled. | | `HIVE_LANES_GROUP` | Yes when `HIVE_LANES_ADDRESS` is set | none | Registered delivery-group ID for Hive's claim loop; the configured project must have that group's work capability. | diff --git a/src/docs/move-hub-registered-cutover.md b/src/docs/move-hub-registered-cutover.md index 4849e6ae66..7ec38a40d9 100644 --- a/src/docs/move-hub-registered-cutover.md +++ b/src/docs/move-hub-registered-cutover.md @@ -38,7 +38,7 @@ move procedures in the other guides should regenerate: - **`HIVE_HUB_SECRET`** — the hub's master secret, present in the spoke's own pod env. Every per-hive derived key (heartbeat bearer, session key, invite key, terminal key) is `HMAC(HIVE_HUB_SECRET, domain-string, HIVE_ID)` — - see `src/docs/env-vars.md:305-320` and, for the heartbeat bearer + see `src/docs/env-vars.md:306-321` and, for the heartbeat bearer specifically, `src/docs/heartbeat-bearer-cutover.md`: ```