Getting started

Upliftr is AI debugging agents. You describe what's wrong, a bug, a failing flow, a setup or config issue, in plain English, and the agents investigate, reproducing it in a real browser or probing your services, and root-cause the failure to its exact cause, down to the backend line. They are read-only by design: they investigate and diagnose, but never mutate your code, your data, or your infrastructure. Anything they confirm becomes a plain-English check they re-run in CI. The only thing they need is an Anthropic API key, Claude is the brain that drives the browser (you bring your own key; there's no per-seat AI markup).

There are three ways to run it. Pick one:

1. Cloud, nothing to install

The fastest way to try it. Sign up and you're in a dashboard in under a minute at app.upliftr.io.

Create your account, then add your Anthropic key in Settings → AI. Now open the Assistant, describe the bug or flow, and the agents reproduce it, root-cause it read-only, and save a check they re-run for you.

2. Self-host in one line

Run the whole platform on your own machine or server, your keys, your data, nothing leaves your infra. One command pulls the prebuilt images and brings it up behind trusted HTTPS:

curl -fsSL https://get.upliftr.io | bash

It generates every secret, starts the stack (API + dashboard + Postgres) behind a local CA, and opens at https://upliftr.test, green padlock, no warnings. Re-running the same command upgrades in place and keeps your data.

Want it on a server with your own domain, Let's Encrypt, backups, and zero-downtime upgrades? See Self-hosting for the full guide (and the one-liner details).

Testing an app on your own machine

The in-container browser reaches your local apps automatically, localhost:3000, gdk.test, any *.test domain. See Testing a local app.

3. From source, to develop or contribute

Clone the monorepo and run the API + dashboard yourself. Upliftr is a FastAPI backend (the JSON API + execution engine) and a Vite + React dashboard over a shared engine; runs use the cross-platform Playwright path, so they work on Windows, macOS, and Linux.

Prerequisites

• Python 3.12+ and uv for the backend.
• Bun for the frontend.
• An Anthropic API key (ANTHROPIC_API_KEY, or save it later in the dashboard's Settings).
• A headless Chromium for Playwright (playwright install chromium).

The monorepo

upliftr/
  backend/     FastAPI JSON API (core · schemas · store · services · api/v1) + engine
  frontend/    Vite + React + Tailwind + TanStack Query dashboard
  mcp-server/  MCP server exposing upliftr_test / upliftr_run_suite / upliftr_check
  examples/    A deliberately-buggy sample app + suites that prove root-cause
  docs/        This documentation site (VitePress)
  templates/   GitLab CI component (gate MRs on Upliftr)

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).

Start the backend

cd backend
uv venv && uv pip install -e .
uv run playwright install chromium       # once
uv run uvicorn app.main:app --port 8400  # API under /api/v1 on http://127.0.0.1:8400

• Interactive OpenAPI / Swagger UI: http://127.0.0.1:8400/docs
• Liveness: curl http://127.0.0.1:8400/api/v1/health

Start the frontend

In a new terminal:

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

Open http://localhost:3400 for the dashboard: chat with the Assistant, 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 (two terminals) run the same thing. Or bring up the whole surface with docker compose up --build (see Deployment).

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 Upliftr 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.

Connect your server logs (the root-cause moat)

The backend diagnosis, the exact server line and the fix, is the whole point. The sample demo wires it for you (LOG_BACKEND=file → server.log); against your app you connect it once. Two things:

1. Emit a trace id. Drop the zero-dependency snippet into your app so every request carries a W3C traceparent and your backend logs it:

   <script src="https://YOUR-UPLIFTR/api/v1/tracing/snippet.js"></script>

2. Point Upliftr at where those logs land — a file, Loki, Datadog, Elasticsearch, GCP Cloud Logging, docker logs/journalctl, or any HTTP endpoint:

   export LOG_BACKEND=file  LOG_FILE_PATH=/path/to/app.log     # simplest

Without this you still catch the UI failure; with it you get the backend line and the fix. Full setup for every backend: Server-log root cause.

Run the tests

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 (model stubbed)
cd frontend && bun run build                               # production bundle (build check)

Configuration

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

Variable	Default	Purpose
UPLIFTR_DATA_DIR	backend/data	Where suites, runs, issues, and artifacts are stored.
UPLIFTR_LOG_LEVEL	INFO	Log verbosity.
UPLIFTR_CORS_ORIGINS	localhost:3400 / :5173	Allowed dashboard origins.

Structured data lives in a SQL database, SQLite by default, Postgres in production via UPLIFTR_DATABASE_URL. The API is authenticated and integration credentials are encrypted at rest; see Authentication and the full Settings & env reference.

Next

You're up. Open the Assistant and just describe what's wrong, and the agents take it from there, or write your first test by hand.