Creating a preview

This guide walks through adding a preview to a repo end-to-end: registering an image with Aviator, declaring runtime secrets, configuring the preview block in aviator/verify.yaml, and confirming it boots.

By the end, you'll have a working default preview that scenarios can run against.

Previews are optional. Verify works without one — every criterion routes to code-scan in that case. Add a preview when behavioral verdicts (endpoint contracts, UI flows, error shapes) start mattering for your team. See Concepts: Previews.

Time: ~15 minutes

Prerequisites:

• Admin access to your Aviator account (to manage images and secrets)

• The repo connected to Aviator — see Connect a repository

For the concept overview, see Concepts: Previews. For the full field list, see Preview YAML reference.

Step 1: Register a preview image

Aviator caches preview images locally and boots a container from the cached copy per run.

1. Open Settings → Sandboxes in the Aviator UI.

2. Register the image you want previews to boot from. Give it a short, stable name — e.g. api-preview. You'll reference this name from verify.yaml.

If you don't have a service image yet, the simplest path is to start with a base image that has your runtime (e.g. node:20) and let the setup script install dependencies. As your previews mature, bake more into the image.

Step 2: Declare runtime secrets

Anything your service reads from the environment at runtime — DB password, third-party API keys — needs to be a secret.

For each runtime secret:

1. Open Settings → Secrets.

2. Add the secret using the exact name your service expects (e.g. DB_PASSWORD, not PG_PASSWORD).

3. Grant it to the repo.

Naming matters: each secret is injected into the preview as an environment variable of the same name.

Step 3: Declare the preview in verify.yaml

Add a preview block to aviator/verify.yaml:

preview:
  - name: default
    image: api-preview
    port: 8000
    setup: .aviator/scripts/preview-setup.sh
    secrets:
      - DB_PASSWORD
      - STRIPE_KEY

Three things to get right:

• image — the name you registered in Step 1.

• port — the port your service listens on inside the container. This is what the scenario runner connects to.

• secrets — every name listed here must exist in the secret store and be granted to this repo, or the boot will fail with a clear error.

If you don't need a setup script (the image is fully self-contained), omit the setup line.

Step 4: Write the setup script (optional)

setup runs inside the container after start and before the port is marked ready. It's the right place for migrations, light fixtures, and warm-up.

Create .aviator/scripts/preview-setup.sh in the repo:

#!/usr/bin/env bash
set -euo pipefail

# Run migrations on the test database.
./bin/api migrate

# Seed a small fixture so scenarios have something to query.
./bin/api seed --fixture=tests/fixtures/preview.json

Make it executable:

chmod +x .aviator/scripts/preview-setup.sh

Two rules of thumb:

• Make it idempotent. It runs every time the preview boots.

• Keep it fast. Heavy work belongs in the image, not in setup. See Managing previews for the bake-vs-setup tradeoff.

Step 5: Commit and trigger a verification

Commit the verify.yaml change and the setup script. Submit through the MCP (or open a PR if you've already submitted).

When the next verification run starts, watch the run timeline in the review document:

• You'll see a "Building preview" line while the container is prepared.

• Then "Booting preview" while the setup script runs.

• Then "Preview ready" once the port accepts connections.

• Scenarios start executing.

If the preview fails to boot, the failure shows up here with the exit code and the last lines of container output.

Step 6: Verify the open-preview link

Once a run produces a verdict, open the review document. The run panel includes an Open preview link. Click it — it should land you at the preview's port, accessible from your browser.

If the link works, the preview is fully wired. Reviewers can now open it for ad-hoc exploration during review.

Common boot failures

Symptom	Likely cause
image not found	The image name in verify.yaml doesn't match what's registered in Sandboxes, or the image isn't granted to this repo.
Missing secret error	A name in secrets isn't defined or isn't granted to this repo.
Container exits 0 immediately	The container's CMD ran a one-off command and exited. Add a long-running process.
Port never opens	Your service binds to localhost only. Bind to 0.0.0.0 inside the container.
Setup script exits non-zero	Migration failure or fixture path wrong. The container output shows the exact line.

Next steps

• Managing previews — bake-vs-setup, refresh, multi-preview repos

• Seed data for previews — fixture strategies

• Writing a SKILL.md — give the scenario runner context for your preview