Home / Docs

Getting Started

Everything you need to install, configure, and embed FeedbackLoop AI on your site.

What is FeedbackLoop AI?

FeedbackLoop AI is an open-source, self-hosted platform that combines session replay, AI-qualified feedback, and console/network capture into a single embed. When a user reports a bug or requests a feature, the AI automatically asks follow-up questions, categorizes the feedback, runs deep root-cause analysis, and can trigger your CI/CD pipeline to implement and deploy a fix — all without human intervention. Think of it as a self-hosted Hotjar alternative with an AI brain and an autonomous deployment pipeline.

Architecture Overview

FeedbackLoop AI consists of five main components that work together:

⚡

API Server

Fastify + Prisma + PostgreSQL

🎬

Worker

Puppeteer + FFmpeg for MP4 renders

📹

Tracker

rrweb-based session recording

💬

Widget

Vanilla JS, closed Shadow DOM

📊

Dashboard

Vanilla JS SPA with rrweb-player

The API server is the central hub. It handles tracker event ingestion, widget chat sessions, AI qualification via OpenRouter, webhook dispatch for CI/CD, and serves the dashboard. PostgreSQL stores all structured data (sessions, feedback, tenants, AI usage), Redis powers the render job queue, and MinIO stores rendered MP4 session replays.

The Tracker is a lightweight JavaScript snippet (built on rrweb) that records DOM mutations, clicks, scrolls, console errors, and network failures. It ships data to the API in real time.

The Widget is the user-facing feedback interface — a chat bubble that opens into an AI-powered conversation. It runs inside a closed Shadow DOM to avoid CSS conflicts with your site.

Prerequisites

Tip

If you are deploying to a VPS (Hetzner, DigitalOcean, OVH, etc.), the automated install script handles all prerequisites for Ubuntu/Debian systems. You only need SSH access.

Quick Start

The fastest way to get FeedbackLoop AI running is with the automated installer:

  1. Clone the repository
    bash 
    git clone https://github.com/QuentinAdt/FeedbackLoopAIOSS.git
cd FeedbackLoopAIOSS
  2. Run the install script
    bash 
    sudo bash install.sh

    This installs Node.js, PostgreSQL, Docker, Redis, MinIO, Caddy (reverse proxy), PM2, and configures everything automatically.

  3. Open the setup wizard

    Once the install script completes, open your browser and navigate to https://your-domain.com/setup. The wizard walks you through:

    • Verifying the setup token
    • Creating your admin account
    • Configuring API keys (OpenRouter for AI)
    • Setting your public domain
    • Creating your first tenant
  4. Embed the widget

    Copy the embed snippet from the setup wizard and paste it into your site's HTML, just before the closing </body> tag:

    html 
    <script src="https://your-domain.com/unified/feedbackloop.js"
  data-api-key="your-api-key"
  data-api-secret="your-api-secret"></script>
What happens next?

Once the widget is embedded, session replay starts recording automatically. When a user opens the widget and submits feedback, the AI qualifies it in real time, runs deep analysis, and (if configured) creates a Linear issue and triggers your CI/CD pipeline.

Next Steps