Workspace Runs
Run an uploaded repo archive in a sandbox, stream execution, collect explicit artifacts, and keep a durable Evidence Bundle.
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
- Create a Workspace Run in
awaiting_archive. - Upload an archive directly for small files or through a staged transfer for larger repo archives.
- Start the run. CrowNest extracts the archive into
/workspaceand runs the command in the selected template. - Stream
status,archive_progress,stdout,stderr,artifact_collected,artifact_error,heartbeat,terminal, anderrorevents. - 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
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 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 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
- TypeScript SDK Workspace Runs — one-shot
runArchive, staged transfers, events, cancelation, and evidence. - CLI Workspace Runs —
run-archiveplus the step-by-step command flow. - REST Workspace Runs — endpoint details for custom clients.