Workspace Runs

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

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

Use run-archive to do all of that in one command. It uploads the archive, runs the remote command, streams stdout and stderr, and exits with the remote command's exit code. After the command reaches a terminal state, read the Evidence Bundle as the durable terminal proof for archive checksum, timing, exit code, artifact IDs, and failure details. Use logs or --json event replay for stdout and stderr.

One command

Terminal

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

The CLI uploads the archive, starts the run, streams output, and exits with the run command's exit code.

Write the terminal proof after completion:

Terminal

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

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

Terminal

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

Archive size

The CLI uses staged archive transfer, so repo archives can use the larger Workspace Run transfer limit. The low 8 MiB cap applies only to direct API upload.

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, for example `python-node`.
`--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. The CLI hashes and uploads the archive as a file stream.

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.

Use the CLI, API, SDK, or Crabbox to create and start runs.

Next steps

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

On this page