Install & run

Tripwire is a monorepo with two apps over a shared engine: a FastAPI backend (the JSON API plus the execution engine) and a Vite + React frontend (the dashboard). The browser runs on the cross-platform Playwright path, so actual test runs work on Windows, macOS, and Linux.

Prerequisites

• Python 3.12+ and uv for the backend.
• Bun for the frontend (the lockfile and scripts target Bun).
• An Anthropic API key — Claude is the brain that drives the browser and adjudicates checks. Set it as ANTHROPIC_API_KEY, or save it in the dashboard's Settings.
• A headless Chromium for Playwright (playwright install chromium).

macOS-only legacy path

There is a second, legacy execution path that drives the local macOS browser via native Quartz events (TRIPWIRE_DRIVER=desktop). It's optional. The default driver is playwright, which is fully cross-platform — prefer it everywhere.

The monorepo

tripwire/
  backend/     FastAPI JSON API (core · schemas · store · services · api/v1) + engine
  frontend/    Vite + React + Tailwind + TanStack Query dashboard
  mcp-server/  MCP server exposing tripwire_test / tripwire_run_suite / tripwire_check
  examples/    A deliberately-buggy sample app + suites that prove root-cause
  docs/        This documentation site (VitePress)
  action.yml   The GitHub Action

1. Configure your key

cp .env.example .env       # then add ANTHROPIC_API_KEY (+ tracker creds if you want)

docker compose auto-loads .env. For a venv run, export the key or save it later in the dashboard's Settings page (it's stored secret-masked).

2. Start the backend

cd backend
uv venv && uv pip install -e .
uv run uvicorn app.main:app --port 8400

The API now serves under /api/v1 on http://127.0.0.1:8400.

• Interactive OpenAPI / Swagger UI: http://127.0.0.1:8400/docs
• Raw schema: http://127.0.0.1:8400/openapi.json

Liveness check:

curl http://127.0.0.1:8400/api/v1/health

Install browsers once if you haven't:

uv run playwright install chromium

3. Start the frontend

In a new terminal:

cd frontend
bun install
bun run dev   # → http://localhost:3400

Open http://localhost:3400 for the dashboard: author suites, run them live, browse runs, triage the Issues board, and configure integrations in Settings.

One command for both

make dev-api and make dev-web (in two terminals) run the same thing. Or bring up the API + UI surface with docker compose up --build (see Deployment).

4. Try it against the buggy sample app

The repo ships a deliberately-buggy FastAPI app and ready-made suites so you can see a real failure — and its backend root cause — in minutes:

# Terminal 1 — the target
cd examples/sample-app && uvicorn app:app --port 8500   # http://localhost:8500

# Terminal 2 — the launch demo: find the bug AND the backend reason, file a ticket
backend/.venv/bin/python demo/break_demo_app.py

The demo points Tripwire at the checkout, drives it in plain English, catches a silent data bug, correlates the failing request's trace_id to the real server.log, and files a root-caused ticket. See Quick test a URL for the same flow against your app.

Configuration

The backend reads settings from the environment with the TRIPWIRE_ prefix (pydantic-settings). The most useful:

Variable	Default	Purpose
TRIPWIRE_DATA_DIR	backend/data	Where suites, runs, issues, and artifacts are stored.
TRIPWIRE_LOG_LEVEL	INFO	Log verbosity.
TRIPWIRE_CORS_ORIGINS	localhost:3400 / :5173	Allowed dashboard origins.
TRIPWIRE_DRIVER	playwright	Execution driver (playwright or desktop).
TRIPWIRE_HEADLESS	1	Run headless (set 0 to watch).

Structured data (suites, runs, issues, plans, settings, users) lives in a SQL database — SQLite by default under data/, Postgres in production via TRIPWIRE_DATABASE_URL; run artifacts stay on disk under data/artifacts/. The API is authenticated and integration credentials are encrypted at rest; see Authentication, Filing issues, and the full Settings & env reference.

Run the tests

# from the repo root
backend/.venv/bin/python -m pytest backend -q              # API + engine + native-tracker tests
backend/.venv/bin/python -m pytest examples/proof -q       # full E2E loop vs the sample app (no key, model stubbed)
cd frontend && bun run build                               # production bundle (build check)

Next

You're up. Continue to Your first test to author and run a suite.