Artifacts & previews

When a diff is not the best evidence: files the agent publishes, and the running result served live.

A design task wants screenshots. A scaffolded app wants to be clicked. Peractor has a lane for each — artifacts, which are files the agent publishes for review, and previews, which are the running result served at a URL.

Artifacts

The agent renders deliverables itself — Peractor never screenshots anything — and lists them in a manifest at .peractor/artifacts.json in the workspace:

{"artifacts": [
  {"path": "shots/dashboard.png", "title": "Dashboard — desktop",
   "caption": "After the redesign"}
]}

Images (PNG, JPEG, WebP, GIF, SVG), HTML, and Markdown are supported, up to 20 artifacts of 32 MB each per phase. A malformed manifest logs a warning and never fails a run.

Two ways to produce them:

• A dedicated publish step whose prompt says how to render them and where to deliver them — the tracker issue, the pull request, and/or your notifiers. Trackers that host attachments (Linear, Jira, GitLab, Slack) show images inline; GitHub gets links.
• Any ordinary prompt step — agents are invited to publish a self-contained deliverable when there is one worth showing.

Artifacts appear in the transcript under the step that made them. Click one and the editor opens it as a real tab, the browser shows it inline, and the phones open a full-screen viewer you can swipe through.

Previews

A preview step parks the run with the built result served at a per-run URL — WebSockets and hot reload included. Reviewers press Open preview, try the real thing, then Continue or Request changes with a note that re-runs the phase. Nothing auto-continues.

It costs a machine only while somebody is looking

The step writes down how to serve itself:

- type: preview
  path: site
  build: npm ci && npm run build
  start: npx serve -s dist -l $PORT

Peractor runs those lines when the phase reaches the step, holds the preview open while people are looking at it, and then parks the run and gives the machine back. Start preview later runs the same two lines against the very commit you are being asked about — so coming back to it in the morning is a button rather than a re-run, and the second look is the same as the first.

One container serves everybody looking at a preview, and it goes when the last of them stops.

Looking at one on a phone

A push says the preview is ready. The phones open it in a sheet: look at it, continue, or request changes. You can draw on what you are looking at — circle the misaligned button — and the drawing goes into the note the agent receives.

Point at the thing that is wrong

A circle says look here. Pointing says what is here: tap the element with the point tool and Peractor reads it out of the running page — what it is, the text in it, the selector that addresses it, and the colours, type and spacing it was given. That travels with your note, so the agent goes to the element instead of hunting through its own markup for whatever the circle was around.

A tap lands on the innermost thing under your finger, which is often a word inside the button you meant. The chip that appears steps outward — to the button, to the row, to the card — and the box on the page follows it. Point at several things in one request if you want; each one is drawn on the picture with its name, so the whole request reads correctly afterwards wherever it is opened.

Pointing works where Peractor is showing you the page itself: the Mac app and both phones. Opening a preview in your own browser — which the dashboard and the editor do — still gives you the note, the drawing and every other way to answer.

From a machine you paired

Phases that run on your own machine preview the same way. The server stays on the machine's own localhost and its traffic rides the machine's outbound connection back to Peractor, so the link works for every reviewer while nothing is exposed on the machine's network.