# Stage artifacts A stage that produces images, screenshots, reports or logs - typically written into an ignored or untracked directory - would otherwise leave nothing retrievable per step. Every agent visit therefore gets its own artifacts directory, and the files it contains are recorded on the step and served over HTTP. ## Where they live The server creates `///` before executing an agent visit. The artifacts root defaults to the directory holding the database (`/artifacts`) and can be pointed elsewhere with the server's `ArtifactsRoot` option. Only model stages get a directory. The directory is passed to the stage: - as the `PIPELINES_ARTIFACTS_DIR` environment variable in a locally spawned Pi process, and exported to the OpenCode CLI where the runtime controls it; - in the agent prompt, next to `Run directory:`, for every agent harness. Because OpenCode V2 tools execute inside the shared serve process, that prompt line is the reliable carrier there. The prompt instruction is deliberately general: save any artifacts you produce - images, screenshots, reports, logs - into the directory; they are attached to the stage. There are no technology, language or file-type rules. ## What is recorded After the stage finishes and before the step is stored, the server makes one bounded inventory of the directory and records, per file, its `name`, `size_bytes`, `content_type` (from the extension, with a content sniff of at most the first 512 bytes as a fallback) and a server-relative `url` (`/artifacts///`). The same fields appear under each step's `artifacts` in `pipelines inspect RUN_ID --json` and in the TUI. - Limits: 200 files per step, 8 MiB per file and 64 MiB total. Over-cap files are skipped and the skipped/truncated counts are recorded with the step. - Symlinks in any component and non-regular files are excluded, and the walk is bounded by the file cap so a large directory is never fully enumerated. - Artifacts are evidence, not a gate. A missing, unreadable, symlinked, oversized or empty directory records nothing and never fails the run or changes its outcome. The database retains the recorded list, not file copies. ## Fetching bytes `GET /artifacts///` on the server that serves `/healthz` and `/connect` returns the file. Only files inside that run's and step's artifact root are reachable: path traversal, absolute paths, symlink escapes and unknown runs/steps are refused. Responses carry the correct `Content-Type` and `Content-Length`; `HEAD` returns headers without a body; and `Range` requests return `206 Partial Content` with the exact slice (or `416` when unsatisfiable), so images and video can stream. `http.ServeContent` streams from the opened file, so a request never loads the whole file into memory. ## Session export When a model stage that ran against an OpenCode harness finishes, the server also exports the session the harness actually produced and writes it into the same `///` directory in markdown (`session.md`) and html (`session.html`). They are ordinary artifacts: the bounded inventory lists them and `GET /artifacts///session.md` (or `.html`) serves them with no special casing. - Source: the read-only native export path. The native v1 CLI exposes it as `opencode export `; the installed v2 CLI exposes it as `opencode session export `. Both reuse the same invocation helper and session-ID/messages validation as the transcript readback. The files are the harness's real session, never a reconstruction. - Bounds: the source read is capped at 8 MiB and each rendered file at 2 MiB. When either the source or the rendered output is cut, both files carry a visible truncation banner near the start and the end and the step records `truncated: true`; a truncated export is never described as whole. - Evidence: the step records `session_export` (`session_id`, `backend`, `source`, `markdown`, `html`, `markdown_bytes`, `html_bytes`, `messages`, `truncated`, `diagnostic`), so `pipelines inspect RUN_ID --json` shows what was written without reading the files. - Isolation: exporting never changes the stage's status, outcome, target or result validation, never waits for the session, never mutates, resumes or interrupts it, and a failure records a sanitized diagnostic and continues. An existing `session.md`/`session.html` is never overwritten and the skip reason is recorded. - Pi limitation: a Pi stage has no native session export path, so the step records `source: "unavailable"` with an explicit diagnostic and writes no files. ## Removal with run history Run artifacts live under `//` and last as long as the run does. `pipelines retention report`/`apply` (see [CLI and agent authoring](cli.md#run-retention)) is the only thing that removes them, and it does so only for a run the operator explicitly selected for removal. Removing a run removes its whole artifact directory; protected and retained runs keep theirs, and their recorded artifact URLs keep serving. A symlink at `/` is removed as a link without touching its target, and a regular file at that path is refused rather than deleted. Nothing removes artifacts automatically.