Workspace Runs

Run an existing gzipped tar archive from the crownest CLI and keep durable evidence.

Workspace Run CLI commands drive the archive-based job flow: create a run, upload an existing .tar.gz or .tgz, start execution, stream output, and download evidence.

The CLI does not pack a local directory. run-archive takes an existing archive path and runs everything after -- inside the extracted workspace.

The launch smoke for release operators is:

Terminal

CROWNEST_WORKSPACE_RUN_E2E=1 \
CROWNEST_API_KEY=cn_live_... \
pnpm live:workspace-runs

It proves staged upload, command streaming, evidence, explicit artifact collection, cleanup, kept-sandbox cleanup, user command failures, timeout cleanup, and archive-limit rejection against the public API.

One command

Terminal

crownest workspace-runs run-archive repo.tgz --template python-node -- pnpm test

The CLI uploads the archive, starts the run, streams stdout and stderr, and exits with the Workspace Run command's exit code.

Use --json to print each stream event as a JSON envelope:

Terminal

crownest workspace-runs run-archive repo.tgz --json -- pytest -q

Implemented upload limit

Current archive uploads are capped at 8 MiB. Build a smaller archive or wait for storage-backed staged uploads before sending large repositories.

Step-by-step flow

Create a run:

Terminal

crownest workspace-runs create \
  --template python-node \
  --command "pnpm test" \
  --metadata repo=acme/app

Upload an existing archive:

Terminal

crownest workspace-runs upload wsr_abc123 repo.tgz

Start it:

Terminal

crownest workspace-runs start wsr_abc123

Stream events:

Terminal

crownest workspace-runs logs wsr_abc123

Read status:

Terminal

crownest workspace-runs status wsr_abc123 --json | jq .data.exitCode

Write evidence after completion:

Terminal

crownest workspace-runs evidence wsr_abc123 --output evidence.json

Cancel an active run:

Terminal

crownest workspace-runs cancel wsr_abc123

Commands

crownest workspace-runs create

Create a Workspace Run record.

crownest workspace-runs create --command <command> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json]

Flag	Description
`--command`	Shell command to run after archive extraction.
`--project`	Project to create the run in.
`--template`	CrowNest template slug. `python-node` is the launch default.
`--sandbox`	Warm sandbox to reuse.
`--keep-sandbox`	Keep the sandbox after the run.
`--timeout-ms`	Command timeout in milliseconds.
`--metadata`	Metadata label as `key=value`. Repeatable.
`--json`	Print `{ "data": ... }`.

crownest workspace-runs upload

Upload an existing archive to a run.

crownest workspace-runs upload <workspace-run-id> <archive.tgz> [--sha256 <hex>] [--json]

archive.tgz must be a file ending in .tgz or .tar.gz. Directories are rejected.

crownest workspace-runs start

Start extraction and command execution.

crownest workspace-runs start <workspace-run-id> [--json]

crownest workspace-runs run-archive

Create a run, upload an existing archive, start it, and stream events.

crownest workspace-runs run-archive <archive.tgz> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json] -- <command>

Everything after -- becomes the command line. The CLI exits with the remote command's exit code when the run reaches a terminal event.

crownest workspace-runs status

Retrieve current run status.

crownest workspace-runs status <workspace-run-id> [--json]

crownest workspace-runs list

List Workspace Runs.

crownest workspace-runs list [--project <prj_id>] [--status <status>] [--json]

crownest workspace-runs logs

Stream Workspace Run events. Use --after-seq to resume after a known event sequence.

crownest workspace-runs logs <workspace-run-id> [--after-seq <n>] [--json]

Without --json, stdout events are written to stdout and stderr events are written to stderr. With --json, each event is printed as { "data": ... }.

crownest workspace-runs cancel

Cancel an active run. Canceling a terminal run returns its current state.

crownest workspace-runs cancel <workspace-run-id> [--json]

crownest workspace-runs evidence

Read the durable Evidence Bundle. Use --output to write pretty JSON to a file.

crownest workspace-runs evidence <workspace-run-id> [--output <path>] [--json]

Dashboard inspection

After a CLI-created Workspace Run starts, the signed-in dashboard can inspect it at /workspace-runs. The dashboard shows status, command, template, timing, exit code, Artifact IDs, and Evidence Bundle fields, and it can cancel active runs.

The dashboard is not the CLI replacement for packing, uploading, starting, or streaming a run. Keep those workflows in the CLI/API/SDK or Crabbox.

Next steps

API Workspace Runs — endpoint details.
TypeScript SDK Workspace Runs — typed client helpers.
Command reference — every CLI command.

The CLI does not provide self-serve Dockerfile templates, provider selection, E2B-backed execution, SSH/devbox access, desktop, GPU, pause/resume, browser automation, artifact globs, or full CI replacement.

On this page