Workspace Run Matrices
Run one immutable archive across bounded, isolated Workspace Runs.
A Workspace Run Matrix is a first-class wsm_ parent for an ordered set of
ordinary Workspace Runs. Upload one .tar.gz, declare cells and dimensions,
and choose maxConcurrency. Every cell gets an isolated Sandbox and its own
logs and Evidence Bundle; cells never share a mutable workspace.
Start reserves the complete concurrency width immediately. If it is not
available, CrowNest returns quota_exceeded and starts zero children. There is
no hidden capacity queue. Within a successful reservation, scheduled cells
are waiting only for an earlier declared cell to finish.
CrowNest continues remaining cells after failures and does not retry cells automatically. Canceling the parent prevents new starts and cancels active or scheduled children. The matrix evidence endpoint returns aggregate counts and links to child Evidence Bundles rather than duplicating their logs or artifacts.
REST lifecycle
The REST API exposes the complete Matrix lifecycle under
/v1/workspace-run-matrices. Use workspace_run_matrix:create for create,
archive, finalize, and start operations; workspace_run_matrix:read for reads;
and workspace_run_matrix:cancel for cancellation.
| Method | Path | Operation |
|---|---|---|
POST | /v1/workspace-run-matrices | Create a Matrix. |
GET | /v1/workspace-run-matrices | List Matrices with cursor pagination. |
GET | /v1/workspace-run-matrices/{matrixId} | Read parent and cell status. |
PUT | /v1/workspace-run-matrices/{matrixId}/archive | Upload a small shared archive. |
POST | /v1/workspace-run-matrices/{matrixId}/archive-transfer | Create a staged archive transfer. |
PUT | /v1/workspace-run-matrices/{matrixId}/archive-transfer/{uploadId} | Upload staged archive bytes. |
POST | /v1/workspace-run-matrices/{matrixId}/archive/finalize | Verify and attach a staged archive. |
POST | /v1/workspace-run-matrices/{matrixId}/start | Reserve capacity and start fan-out. |
GET | /v1/workspace-run-matrices/{matrixId}/events | Replay events by sequence number. |
POST | /v1/workspace-run-matrices/{matrixId}/cancel | Cancel active and scheduled cells. |
GET | /v1/workspace-run-matrices/{matrixId}/evidence | Read aggregate terminal evidence. |
Create accepts between 1 and 64 ordered cells and maxConcurrency from 1 to 16. Each cell needs a unique key, a command, and a dimensions object. The
only current source is { "kind": "archive", "format": "tar.gz" }, and the
only strategy is isolated.
{
"projectId": "prj_abc123",
"source": { "kind": "archive", "format": "tar.gz" },
"strategy": "isolated",
"maxConcurrency": 2,
"cells": [
{
"key": "node-20",
"command": "pnpm test",
"dimensions": { "node": "20" }
},
{
"key": "node-22",
"command": "pnpm test",
"dimensions": { "node": "22" }
}
]
}For a direct archive upload, send gzipped tar bytes with
content-type: application/gzip, x-crownest-content-sha256, and
x-crownest-content-length. For larger archives, create a staged transfer,
upload with the returned method and headers, then finalize with its uploadId,
sha256, and sizeBytes. Start only after either upload path makes the Matrix
ready.