# 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.