Skip to main content
An Artifact is an exported Run file snapshot stored by the control plane. It remains downloadable after the Session’s cloud resources are closed. Continue from the first Session guide with an authorized Run ID and initialized client.

Ask for exported deliverables

Tell the Agent to write deliverables into its supplied Run artifact directory, currently artifacts/<run-id>/ within the workspace. Each Run has its own directory. Saving somewhere in the project does not automatically export a file. The worker exports files after the Harness exits and before completing the Run. Limit violations fail visibly rather than silently dropping files. Query actual artifact metadata instead of relying on the assistant’s claim that it created a file.

Download and verify

Each execution creates a private temporary directory and writes generated filenames exclusively. The printed directory is retained for inspection; move verified downloads to your application storage and remove temporary copies when finished. The example writes manifest.json, mapping each generated filename to its Artifact ID, original name, Run ID, size and hash. The manifest is written only after every listed download passes integrity checks. If execution stops earlier, the directory can contain partial downloads; an absent manifest means this batch was not completed. An empty manifest still does not satisfy a task that requires deliverables. Never use a remote name directly as a local destination. Metadata includes name, size, SHA-256, Session ID, Run ID, and creation time. Downloads return binary content. Authorize business users again before delivery and select a safe response content type and download filename.

Decide whether a deliverable is complete

A matching hash proves that downloaded bytes match the exported snapshot; it does not prove that code is correct, a report is accurate or the Agent ran the requested tests. Define required artifact names and task-specific checks before execution. An empty list satisfies none of those requirements even if the Run is completed. Keep the final assistant answer, Run outcome and artifact validation as separate records. The worker attempts capture for non-interrupted terminal invocations, including failed or cancelled execution. Such files may be useful partial results, not approved deliverables. An interrupted Runtime skips that capture path; do not assume its unexported workspace is available as artifacts. An export failure can also make an otherwise successful Harness task fail. Inspect the Run error and timeline before deciding to repeat any work. For delivery through your application, authenticate the requester, resolve the Artifact ID through that user’s business task, fetch bytes on the backend, verify integrity, and return a download. Use a controlled filename and Content-Disposition: attachment; do not render generated HTML on the application’s trusted origin. A private preview is the separate mechanism for running generated pages.

Limits and retention

Current exports allow 64 files, 4 MiB per file, and 8 MiB per Run. Symbolic links and nonregular files are rejected. See the artifact implementation and Runtime export logic. Bytes reside in PostgreSQL. Session closure does not delete them, and subsequent Runs do not overwrite earlier snapshots. This is not an unlimited-capacity or permanent archival guarantee; backups, storage capacity, and deployment retention remain operational responsibilities.

Diagnose and verify

For an empty list, check terminal state, output directory, actual Harness execution, and export errors. Do not resubmit merely to inspect files. Cross-tenant artifact reads must fail; your application must also check business ownership. Verify metadata, size, digest, task-specific content, and a second download of the same Artifact ID after Session closure. Keep unresolved cleanup records even when artifact export succeeds.

A two-file retention exercise

In a dedicated Session, submit a task to write message.txt containing exactly Hello from Hexagon plus a newline, and status.json containing exactly {"ok":true} plus a newline, both in the supplied Run artifact directory. Save the submission intent and Run ID as in backend integration. Wait for a terminal Run and require completed for this success exercise; inspect errors before proceeding otherwise. Use the download loop above and additionally compare required names and expected bytes. Do not require the list to contain only these files if the task legitimately exports additional deliverables. Keep the two Artifact IDs and hashes, explicitly close the Session, confirm resource cleanup, then download those same IDs again. The bytes must equal the pre-close downloads. A successful download is evidence of retention, not evidence that resource deletion finished. Run the complete Python program or TypeScript program from the repository root. Use the SDK installation and enabled connection IDs from the first Session guide. These programs create independent cloud Sessions and incur Provider/model usage:
Each program requires the two exact filenames and exact bytes, verifies every exported file’s size/hash, waits for completed, explicitly closes the Session, and downloads every same Artifact ID again. Additional exports are permitted and also checked. Local files use generated names; original metadata and IDs remain in the private journal. This example’s journal is its download record; the earlier reusable snippet instead writes a separate manifest.json. Python records .local/docs-artifacts-python/; TypeScript records .local/docs-artifacts-typescript/. Success ends at journal phase closed_and_retention_checked. A ten-minute observation timeout does not cancel execution. On any error, keep the journal, inspect the recorded Session/Run and resource operations, and follow the first Session recovery table. The program refuses to overwrite an existing journal; do not delete it to retry. After verified cleanup, archive the directory before another independent experiment. Both programs passed independent real-cloud execution on 2026-11-20 using Vercel, built-in Pi 1.5.2 and the configured Messages endpoint with deepseek-ai/DeepSeek-V4-Flash. The two-file execution record confirms exact bytes and hashes for both files, completed Runs, closed Sessions, completed resource-deletion records, and identical downloads after closure. This does not certify another combination, infinite retention or a fresh over-limit cloud test. The runnable project tutorial provides a broader implemented example: its dated dual-SDK record verifies six required exports per Run, including code and fixed-test results, with retained byte equality after closure on the documented Vercel/Pi/Messages combination.

Interpret export failures

The Runtime snapshot and the control-plane capture are separate boundaries. Runtime errors can be surfaced through the worker’s Run error, rather than as the exact public code of a direct artifact-download request. See limits and errors. Sources: capture and download storage, stored bytes migration, Runtime export. Next: private previews, persistence boundaries, backup and restore.