# Workspace Runs (/docs/concepts/workspace-runs)



A Workspace Run is a one-shot execution workflow for repo-shaped work. You
upload a gzipped tar archive, choose the `python-node` template, run a command,
stream stdout and stderr, collect named outputs as artifacts, and read a
durable Evidence Bundle after the sandbox is cleaned up.

Use Workspace Runs when the unit of work is "run this checkout" rather than
"keep this sandbox open." Use regular Sandboxes when you need an interactive
environment, repeated commands, file edits, or a long-lived preview service.

## Lifecycle [#lifecycle]

1. Create a Workspace Run in `awaiting_archive`.
2. Upload an archive directly for small files or through a staged transfer for
   larger repo archives.
3. Start the run. CrowNest extracts the archive into `/workspace` and runs the
   command in the selected template.
4. Stream `status`, `archive_progress`, `stdout`, `stderr`,
   `artifact_collected`, `artifact_error`, `heartbeat`, `terminal`, and
   `error` events.
5. On terminal status, CrowNest collects only the artifact paths you requested,
   writes the Evidence Bundle, and cleans up the sandbox unless you explicitly
   kept it.

The terminal state is `succeeded`, `failed`, or `canceled`. A timed-out
Workspace Run is a failed Workspace Run, and cleanup must stop the command or
destroy the sandbox.

## Archives [#archives]

Workspace Runs accept existing `.tar.gz` and `.tgz` archives. The archive is
the source of truth for the run input; the SDK and CLI do not yet pack a
directory for you.

There are two upload paths:

| Path            | When to use it                                      |
| --------------- | --------------------------------------------------- |
| Direct upload   | Small archives that fit the direct API body limit.  |
| Staged transfer | Larger repo archives uploaded to a transfer target. |

Every archive includes `sizeBytes` and `sha256` so CrowNest can verify the
bytes before extraction.

## Events And Evidence [#events-and-evidence]

Events are ordered by sequence number. Use `afterSeq` to resume an SSE stream
or to replay a bounded event window with `listEvents`.

The Evidence Bundle is the durable proof for the run. It includes run status,
exit code, command, template identity, timestamps, source metadata, artifact
IDs, and the terminal event. It is available after terminalization finishes.

## Artifacts [#artifacts]

Artifacts are explicit. If you want a file to survive the run, pass the output
paths when creating the Workspace Run. CrowNest exports those paths after the
command finishes and records the resulting artifact IDs in the run and
Evidence Bundle.

If the sandbox is destroyed, anything left only in `/workspace` is gone.

## API And Clients [#api-and-clients]

* [TypeScript SDK Workspace Runs](/docs/sdk/workspace-runs) — one-shot
  `runArchive`, staged transfers, events, cancelation, and evidence.
* [CLI Workspace Runs](/docs/cli/workspace-runs) — `run-archive` plus the
  step-by-step command flow.
* [REST Workspace Runs](/docs/api/workspace-runs) — endpoint details for
  custom clients.