Artifacts
How explicit artifact export, command collection, retention, and signed downloads work in CrowNest.
An artifact is a durable, indexed output copied from a sandbox workspace to object storage. Artifacts outlive the sandbox: once exported, you can list and download them after the sandbox is destroyed. Export is always explicit — CrowNest never copies files out of a sandbox automatically.
Explicit export only
Nothing leaves the workspace unless you ask. When a sandbox expires or is killed, its filesystem is gone; only files you exported as artifacts survive. This is deliberate: you stay in control of what persists, and nothing sensitive is copied out as a side effect.
There are two ways to create an artifact.
Create via the API
POST /v1/sandboxes/{id}/artifacts with body path (a file inside
/workspace) and optional name copies the file to object storage and
returns the artifact. The request requires both the artifact:create and
file:read scopes and supports an Idempotency-Key header.
Collect on command completion
The synchronous run endpoint accepts a collect array of
{ path, name? } entries and a collectOn setting:
collectOn: "success"(default) — collect only when the command exits successfully.collectOn: "always"— collect regardless of how the command ends.
Using collect requires the artifact:create scope in addition to
command:run. The asynchronous start endpoint doesn't accept collect
or collectOn.
Collection status
Collection is tracked separately from the command result. The command
object carries a collectStatus independent of its own status and
exitCode:
collectStatus | Meaning |
|---|---|
not_requested | The command had no collect entries. |
pending | Collection is still in progress. |
succeeded | Every requested file was exported. |
partial | Some files were exported, some failed. |
failed | No requested file could be exported. |
skipped | Collection didn't run, for example because collectOn was success and the command failed. |
A command can exit successfully while collection fails (for example, a
listed file was never created), and details land in collectErrors. Check
collectStatus rather than assuming a successful command means successful
collection.
Retention
Artifact retention depends on your plan. The current configurable beta
defaults are 7 days on Free and 30 days on Developer; these limits may
change, so check your plan. You can delete an artifact early with
DELETE /v1/artifacts/{artifactId}.
Downloads
Artifacts may contain sensitive data, so downloads use short-lived signed
URLs rather than permanent links. Request one with
POST /v1/artifacts/{artifactId}/download-url, which returns
{ url, method: "GET", headers, authMode: "api_key" }. Fetch the URL
promptly; request a fresh one when it expires.
To browse what exists, GET /v1/sandboxes/{id}/artifacts lists a sandbox's
artifacts and GET /v1/artifacts/{artifactId} returns one. Each artifact
records its name, sourcePath, sizeBytes, contentType, and
createdAt.
Next steps
- Commands — collect outputs as part of a command run.
- Files and the workspace — the source filesystem artifacts are exported from.
- Usage and billing — retention and storage quotas by plan.
- Artifacts API reference