Workspace Runs

Workspace Runs are CrowNest's archive-based job runner for agent and repo workflows. Create a run, upload a gzipped tar archive, start execution, stream events, then read the Evidence Bundle after the sandbox is gone.

They are intentionally not a provider picker. Public responses expose CrowNest templates and resources, not Cloudflare, E2B, VM class, image, or provider IDs.

The launch path is release-gated on the python-node template in CrowNest-managed Cloudflare Sandboxes. Run the release smoke before changing public launch language:

CROWNEST_WORKSPACE_RUN_E2E=1 \
CROWNEST_API_URL=https://api.crownest.dev \
CROWNEST_API_KEY=$CROWNEST_API_KEY \
pnpm live:workspace-runs

The API key needs workspace_run:create, workspace_run:read, workspace_run:cancel, sandbox:read, sandbox:kill, artifact:create, and file:read.

The Workspace Run object

Create a run

POST /v1/workspace-runs — requires workspace_run:create. Accepts an Idempotency-Key header.

Artifact collection also requires artifact:create and file:read. Environment variables are not accepted on Workspace Runs yet; use committed files or a future secret-backed path instead.

curl -X POST https://api.crownest.dev/v1/workspace-runs \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: repo-test-01" \
  -d '{
    "template": "python-node",
    "command": "pnpm test",
    "timeoutMs": 120000,
    "artifacts": [{ "path": "coverage/lcov.info", "name": "coverage" }],
    "sourceMetadata": { "repo": "acme/app", "commit": "abc123" }
  }'

Returns 201 with { "workspaceRun": { ... } } and status awaiting_archive.

Upload an archive

For small archives, upload raw gzipped tar bytes directly:

PUT /v1/workspace-runs/{workspaceRunId}/archive — requires workspace_run:create.

SHA=$(shasum -a 256 repo.tgz | awk '{print $1}')
SIZE=$(wc -c < repo.tgz | tr -d ' ')

curl -X PUT "https://api.crownest.dev/v1/workspace-runs/wsr_abc123/archive" \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/gzip" \
  -H "x-crownest-archive-sha256: $SHA" \
  -H "x-crownest-archive-size: $SIZE" \
  --data-binary @repo.tgz

Returns { "archive": { ... }, "workspaceRun": { ... } } with status archive_uploaded.

Staged archive transfer

Use staged transfer when you want the transfer contract explicitly, or when future durable-storage upload targets are available.

1. Create a transfer:

   curl -X POST "https://api.crownest.dev/v1/workspace-runs/wsr_abc123/archive-transfer" \
     -H "Authorization: Bearer $CROWNEST_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{ \"sha256\": \"$SHA\", \"sizeBytes\": $SIZE }"

2. Upload the archive to transfer.uploadUrl with transfer.method and the returned transfer.headers. If the upload URL is a CrowNest API URL, authenticate normally with your API key. If it is an external storage URL, do not attach the CrowNest bearer token unless the transfer headers explicitly include an auth mechanism.

3. Finalize:

   curl -X POST "https://api.crownest.dev/v1/workspace-runs/wsr_abc123/archive/finalize" \
     -H "Authorization: Bearer $CROWNEST_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{ \"uploadId\": \"upl_abc123\", \"sha256\": \"$SHA\", \"sizeBytes\": $SIZE }"

Start execution

POST /v1/workspace-runs/{workspaceRunId}/start — requires workspace_run:create. Accepts an Idempotency-Key header.

The run must already have an uploaded archive. Start transitions through starting, extracting, and running, then finishes as succeeded, failed, or canceled.

curl -X POST "https://api.crownest.dev/v1/workspace-runs/wsr_abc123/start" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Read and stream events

GET /v1/workspace-runs/{workspaceRunId}/events — requires workspace_run:read.

Query parameters:

Stored event reads return { "data": [...], "hasMore": false, "nextSeq": 12 }. Streaming uses SSE and accepts afterSeq or the standard Last-Event-ID header.

Event types are status, archive_progress, stdout, stderr, artifact_collected, artifact_error, heartbeat, terminal, and error.

curl -N "https://api.crownest.dev/v1/workspace-runs/wsr_abc123/events?stream=true" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Status, list, cancel, and evidence

GET /v1/workspace-runs/{workspaceRunId} — requires workspace_run:read.

GET /v1/workspace-runs — requires workspace_run:read.

POST /v1/workspace-runs/{workspaceRunId}/cancel — requires workspace_run:cancel. Cancel is idempotent by state.

GET /v1/workspace-runs/{workspaceRunId}/evidence — requires workspace_run:read.

The Evidence Bundle is durable run proof: command, template fields, archive checksum, timing, exit code, artifact IDs and errors, failure classification, cleanup status, metadata, and source metadata. It is available only after the run reaches a terminal state and evidence persistence succeeds.

Dashboard inspection

The signed-in dashboard includes a Workspace Runs inspection surface at /workspace-runs. Use it after a run is created through the API, CLI, SDK, or Crabbox to list runs, open a detail page, inspect Evidence Bundle fields, copy Artifact IDs, and cancel active runs.

The dashboard does not create Workspace Runs, upload archives, start runs, build Templates, open live terminals, or expose provider/runtime placement.

Next steps

• TypeScript SDK Workspace Runs — use the typed client and staged upload helper.
• CLI Workspace Runs — run an existing archive from the terminal.
• Capability matrix — compare supported surfaces.

Workspace Runs do not yet include self-serve Dockerfile templates, E2B-backed core runtime behavior, SSH/devbox access, desktop, GPU, pause/resume, browser automation, artifact globs, full CI replacement, or public provider selection.