Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-crux-runs-docs.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 2 additions & 0 deletions src/docs/crux-serve.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<workdir>/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 `<workdir>/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
Expand Down Expand Up @@ -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)
Expand Down
11 changes: 8 additions & 3 deletions src/docs/design/crux-work-services.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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 |
Expand Down
1 change: 1 addition & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/move-hub-registered-cutover.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`:

```
Expand Down
Loading