Artifacts

client.artifacts exports files from a sandbox's workspace to durable object storage and manages them afterward. Export is always explicit: nothing is copied out automatically when a sandbox is destroyed. Artifacts outlive the sandbox they came from.

A SandboxHandle exposes sandbox.artifacts.create and sandbox.artifacts.list without the sandboxId argument. For methods that take an artifact ID (get, download, downloadUrl, delete), use the top-level client. Previews are documented separately.

create

Copy a file from the sandbox workspace into object storage. Requires a live sandbox and the artifact:create and file:read scopes.

create(
  sandboxId: `sbx_${string}`,
  input: { path: string; name?: string; idempotencyKey?: string },
): Promise<Artifact>

const artifact = await client.artifacts.create(sandbox.id, {
  path: "dist/report.pdf",
  name: "quarterly-report",
});
console.log(artifact.id, artifact.sizeBytes);

You can also collect artifacts automatically when a command finishes with the collect option on commands.run.

Error codes: not_found, sandbox_destroyed, file_not_found, path_outside_workspace, forbidden, quota_exceeded.

list

List artifacts exported from a sandbox.

list(sandboxId: `sbx_${string}`): Promise<readonly Artifact[]>

const artifacts = await client.artifacts.list(sandbox.id);

get

Fetch a single artifact's metadata by ID.

get(artifactId: `art_${string}`): Promise<Artifact>

const artifact = await client.artifacts.get("art_abc123");

Error codes: not_found, forbidden.

download

Download an artifact's content as bytes.

download(artifactId: `art_${string}`): Promise<Uint8Array>

import { writeFile } from "node:fs/promises";

const bytes = await client.artifacts.download(artifact.id);
await writeFile("report.pdf", bytes);

Error codes: not_found, forbidden.

downloadUrl

Get a short-lived signed URL for downloading the artifact, useful for handing off to another process or service. Requests use GET with the returned headers, authenticated as authMode: "api_key".

downloadUrl(artifactId: `art_${string}`): Promise<{
  url: string;
  method: "GET";
  headers: Record<string, string>;
  authMode: "api_key";
}>

const { url, headers } = await client.artifacts.downloadUrl(artifact.id);
const response = await fetch(url, { headers });

[!NOTE] Artifacts can contain sensitive data. Download URLs are short-lived and signed; treat them as secrets while they're valid.

delete

Delete an artifact from storage. The operation is idempotent by state and returns the artifact record with deletedAt set.

delete(artifactId: `art_${string}`): Promise<Artifact>

await client.artifacts.delete(artifact.id);

Error codes: not_found, forbidden.

Artifact object

The Artifact type includes id (art_ prefix), orgId, projectId, sandboxId, name, sourcePath, objectKey, sizeBytes, contentType, createdAt, and deletedAt.

Next steps

• Previews — expose HTTP services from a sandbox.
• Commands — collect artifacts automatically with collect.
• Artifacts concept — retention and storage model.