Self-hosted visual regression testing: an open-source option for Storybook teams

What you run when you self-host

Self-hosting runs the same web app, worker and diff engine as the hosted service, from the repository's Dockerfile and production docker-compose.yml. The Compose file defines six services:

• snapvisor-web. The API and the app UI.
• snapvisor-worker. Build processing, screenshot comparison and notifications. The diff engine runs inside the worker; there is no separate diff service.
• snapvisor-migrate. A one-shot container that runs migrations, seeds the default plans and exits.
• redis, rabbitmq and dynamodb. Caching and short-lived codes, the job queue between web and worker, and local DynamoDB for the deployments feature.

Two things are not in the Compose file because you supply them: a Postgres database and an S3-compatible bucket for screenshots (AWS S3, MinIO and Backblaze B2 all work). You also put a TLS-terminating proxy in front of the web container. The self-hosting guide has the environment variables and the first-run steps.

Storybook: how your stories get captured

@snapvisor/storybook runs your stories in a real browser and captures one screenshot per story, so the story list stays in Storybook. Two routes are documented. The recommended one is the Storybook Vitest addon:

npm install --save-dev @snapvisor/storybook

// vitest.config.ts
import { defineConfig } from "vitest/config";
import { argosVitestPlugin } from "@snapvisor/storybook/vitest-plugin";

export default defineConfig({
  plugins: [
    argosVitestPlugin({
      // Upload the screenshots only on CI.
      uploadToArgos: process.env.CI === "true",
    }),
  ],
});

A screenshot is captured for every story automatically. If you run your stories with the Storybook Test Runner instead:

// .storybook/test-runner.ts
import { argosScreenshot } from "@snapvisor/storybook/test-runner";

export default {
  async postVisit(page, context) {
    await argosScreenshot(page, context);
  },
};

The package list is on the SDKs page. The official adapters also cover Playwright, Cypress and Puppeteer, so Storybook and end-to-end screenshots can land in one review workflow; see getting started. The hosted service can also serve a static Storybook build on its own URL so reviewers can open it: see deployments. On a self-hosted instance that feature is not turnkey: it is served by an AWS CloudFront stack that the Compose file does not deploy.

What Snapvisor does not document: equivalents of the Chromatic features listed on Snapvisor vs Chromatic, such as TurboSnap and UI version tracking. If those drive your workflow, weigh them before you move.

Point your pipeline at your instance

Once your instance is up, create an account, create a project and copy its project token. There is no command-line flag for the server address: the CLI reads the API base URL from the ARGOS_API_BASE_URL environment variable, and it includes the /v2/ path.

export ARGOS_TOKEN="<your project token>"
export ARGOS_API_BASE_URL="https://api.snapvisor.example.com/v2/"

npx @snapvisor/cli upload ./screenshots

The SDKs keep the ARGOS_* variable names, so a pipeline already wired for the hosted service works against your instance once that one variable is set.

What self-hosting costs you

The hosted service absorbs the following. On your own infrastructure it is your work:

• Access and setup. The repository is not public yet, then you run six containers plus Postgres, a bucket and a proxy. The Compose file expects an external Docker network named dokploy-network; create it or edit the networks: blocks.
• Secrets that stop the boot. In production the backend refuses to start without ENCRYPTION_KEY, SERVER_SESSION_SECRET, STRIPE_PRICING_TABLE_ID and STRIPE_PUBLISHABLE_KEY. ENCRYPTION_KEY is permanent: losing it makes every encrypted column unreadable, with no recovery.
• A monthly screenshot cap. Without Stripe billing every account is held to a built-in monthly screenshot cap, and builds are rejected once an account passes 110% of it. The plan rows are re-seeded on every deploy, so raising the cap means pinning an account to another plan by hand in the database. The self-hosting guide has the details.
• Pull request checks. Status checks, repository linking and provider sign-in need your own GitHub App, GitLab application or Google OAuth client. Without them you upload builds and review them in the UI instead of on the pull request.
• SAML SSO. The SAML add-on is bought through Stripe, so the UI cannot switch it on without Stripe; it would take a manual database change. GitHub SSO needs your GitHub App.
• MCP. The MCP server runs inside the same web process, but you set MCP_BASE_URL yourself and route an mcp hostname to the web container. Its plan gate does nothing without Stripe.
• Analytics. The shipped Compose file bakes Snapvisor's own browser analytics keys into the build unless you override them. Turn PostHog off with POSTHOG_DATASET=disabled and leave GA4_MEASUREMENT_ID empty.
• Email. Sign-in codes and invitations go through UseSend. Without a key nothing delivers them, so you either configure it or sign in only through Google, GitHub or GitLab.
• Storage and backups. Postgres holds every build and review, the bucket holds every screenshot, and ENCRYPTION_KEY unlocks the encrypted columns. All three have to survive together.
• Upgrades. You pull, rebuild and let the migrate service run before the new web and worker containers take traffic.

If you would rather not run any of the above, hosted Snapvisor is the same engine and SDKs, and we run and update it for you.

Which one fits

Chromatic is a strong choice when:

• Storybook is the center of your UI workflow — Chromatic is built by the Storybook maintainers and you want its deep component-level tracking.
• You want TurboSnap to only re-snapshot components affected by a change, controlling snapshot cost.
• UI version history and component review inside Storybook matter more than an open-source core.

Self-hosted Snapvisor fits when:

• Screenshots of your product cannot leave your network, which is the case the self-hosting guide is written for.
• You have someone who can run Postgres, a bucket, a proxy, backups and upgrades, and you want to inspect the engine you run.
• You capture Storybook alongside Playwright, Cypress or Puppeteer and want one review workflow for all of it.

Hosted Snapvisor fits when you want the open-source engine and SDKs without operating anything. For pricing and features side by side, read Snapvisor vs Chromatic; for the basics of the workflow, read the visual regression testing guide.

The engine underneath

Snapvisor is a fork of Argos CI, an open-source visual testing engine that is itself self-hostable. If you want to run the upstream project instead of the Snapvisor fork, that is a legitimate route; the comparison page says what is the same and what differs.

Frequently asked questions

Sources

Try hosted Snapvisor