# Workspace Run Matrices (/docs/api/workspace-run-matrices)



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 [#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`.

```json
{
  "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`.