Previews and Visual Review

Previews let operators and agents run the repository in development mode from a Syrus workflow workspace. They power manual preview buttons and browser-based visual review.

Preview Configuration

Add a preview block to .syrus.yml:

preview:
  setup:
    - bundle install
    - npm ci
  seed: bin/rails db:prepare db:seed
  start: bin/rails server -p $PORT -b 0.0.0.0 -e development
  health_check: /up
  health_check_timeout_seconds: 120

Syrus assigns $PORT, starts the process under its process monitor, and proxies traffic through the Syrus host. The app should use relative asset and API URLs whenever possible. Absolute localhost URLs usually work locally but break once the preview is behind a proxy and HTTPS origin.

Seed commands should be idempotent. A preview may be started repeatedly on the same branch while a user or reviewer investigates the change.

When the bundled Rails plugin auto-detects a repository, SQLite development databases work without extra deployment configuration. A Rails repository whose development adapter is PostgreSQL requires the preview runtime to have SYRUS_RAILS_PREVIEW_POSTGRES_URL, pointing to a maintenance database with a user allowed to create and drop databases. Syrus creates a deterministic, isolated database for each preview, waits for PostgreSQL readiness, runs create/migrate/seed, and drops the database at cleanup. The URL is runtime-only secret material and is redacted from commands and diagnostics.

An explicit .syrus.yml preview block always takes precedence over Rails auto-detection. Use it when the repository has custom database provisioning or cleanup requirements.

For monorepos, each nested .syrus.yml can define a project-scoped preview block. Syrus runs that preview from the nested project directory. When a Job affects one previewable project, Start Preview launches that project directly. When a Job affects more than one previewable project, the Job detail panel asks which project to start and remembers the selection for that Job. If the Job only touches projects without previews, the panel says that no affected project has a preview configured.

Browser-based visual review uses the same affected-project preview selection. The reviewer prompt lists affected preview projects with project_id, label, path, and owning .syrus.yml. With one affected preview, the reviewer can call start_preview without a project_id or pass that id explicitly. With several affected previews, the reviewer must pass the relevant project_id and may start more than one project preview when the diff crosses products. A bare start_preview is ambiguous in that case; reviewers should not test an unrelated root app just because it can boot.

Preview Logs

Preview processes run as tracked spawned processes. Their stdout, stderr, state transitions, exit status, and recent logs are available from the Job detail UI and through the preview log tools. When a preview does not boot, read those logs before assuming the browser is at fault.

Workflow visual review waits 60 seconds by default for start_preview health checks. Repositories that need longer boot time can set preview.health_check_timeout_seconds in the owning .syrus.yml. Timeout errors include the effective timeout, health-check URL, project id when one was selected, configured app log paths, the startup stdout/stderr file under .syrus/preview/, and a short recent output tail.

Visual Review

Visual review is an optional loop where a read-only agent starts a preview, drives a browser, captures screenshots, and submits a structured verdict:

• approved: the visible behavior looks correct.
• needs_work: the implementation should be revised.
• skipped: there was nothing useful to test visually.

Configuration:

visual_review:
  enabled: true
  rounds: 1
  when_files_changed:
    - "app/frontend/**/*"
    - "app/views/**/*"

Use when_files_changed to avoid launching a browser for backend-only work. The visual reviewer should inspect the running app and screenshots, not run builds or full test suites. Deterministic build and test checks belong in graders.

When a matching merge-base capture is available, the Job review presents the before and after screenshots in a single responsive comparison. Drag the divider (or use its keyboard controls) to reveal either version, and tap the comparison to open a larger preview with labeled before/after navigation.

When the reviewed UI is below the fold, screenshot submission can identify a subject by CSS selector or by its exact browser snapshot ref. Syrus waits for that element to become visible and centers it before capturing. By default, at least half of the subject must intersect the viewport; taller subjects must have their top edge visible. Saved evidence records the subject rectangle, visible fraction, and scroll position so reviewers can verify what the screenshot was meant to show.

If every screenshot shows an authentication, missing-credentials, or error wall, Syrus surfaces a blocked-evidence warning on the review instead of treating those captures as proof that the changed screen works. The same soft warning appears when a reviewer skips because the preview environment cannot reach the intended screen. The review does not hard-fail the workflow, but the operator can see that the visual evidence was inconclusive.

Nested visual_review blocks are scoped to their project. Their when_files_changed patterns are resolved relative to the nested .syrus.yml, and their seed notes are shown when that project preview is one of the affected choices. Use root settings for repository-wide policy and nested settings for product-specific review scope, seed guidance, or opt-outs.

Making Previews Reliable

For Rails, Node, and similar development servers:

• bind to 0.0.0.0,
• accept the assigned $PORT,
• keep host allowlists broad enough for the preview proxy,
• avoid hard-coded localhost URLs in generated HTML,
• seed a small realistic dataset,
• make seeds safe to run more than once.

Syrus itself has extra guardrails because it can preview a copy of Syrus from inside Syrus. Most applications do not need those special protections.