Quickstart

Get BitDrip running in under 5 minutes.

Prerequisites

• Docker 24+ with docker compose plugin or Podman 4+ with podman-compose
• A license file (license.jwt) — register free at bitdrip.app
• Linux or macOS host (Windows with WSL2 is supported)
• 2 GB RAM minimum, 4 GB disk

Steps

1. Register and download

Register at bitdrip.app. The Community tier is free — no credit card required.

After registering, check your email for:

• Your license.jwt file
• A download link for bitdrip-2.2.29.tar.gz

2. Extract the bundle

tar -xzf bitdrip-2.2.29.tar.gz
cd bitdrip-2.2.29

3. Place your license file

cp ~/Downloads/license.jwt ./license.jwt

4. Run the installer

bash install.sh

The installer detects your container runtime, validates the license, generates secure secrets, pulls images, and starts all services.

Expected output:

  ✓ Container runtime: docker (docker compose)
  ✓ License file found: ./license.jwt
  ✓ Environment configured
  ✓ Services started

  BitDrip v2.2.51 is running
  ▸ Dashboard:      http://localhost:3000
  ▸ Policy Engine:  http://localhost:3002
  ▸ Proxy Daemon:   http://localhost:3001

5. Generate and install your CA certificate

bitdrip cert generate && bitdrip cert install

This creates a local CA keypair and installs it into the OS trust store, Firefox NSS, and Chrome NSS. Required once per host so the MITM proxy can intercept HTTPS traffic without browser warnings.

6. Start the proxy daemon

bitdrip proxy start

This starts the proxy daemon on port 3001 and configures the system-wide proxy via the PAC file (http://localhost:3001/proxy.pac). All HTTP/HTTPS traffic from the workstation — including AI service calls from any application — is now routed through the policy engine.

7. Verify everything is healthy

bash status.sh

Expected output:

  ✓ Proxy Daemon    http://localhost:3001/health
  ✓ Policy Engine   http://localhost:3002/health
  ✓ Dashboard       http://localhost:3000

  All services healthy

If any service shows ✗, the script prints the exact docker compose logs command to diagnose it.

8. Sign in to the dashboard

Open http://localhost:3000 and sign in with the admin credentials printed at the end of the installer output.

Upgrading

The installer bundle includes upgrade.sh for in-place upgrades. Run it from your existing install directory:

bash upgrade.sh

This pulls the latest image version from GHCR (pinned to the BITDRIP_VERSION value stored in your .env) and restarts the containers. Your .env, license.jwt, and PostgreSQL data are preserved — no manual file copying required.

To upgrade to a specific version, update BITDRIP_VERSION in .env before running the script.

Deploy to workstations

The proxy daemon on the server only protects server-side processes. To protect your team's laptops and desktops you need to install the tray app on each workstation.

9. Invite users from the dashboard

1. Open the dashboard → Settings → Workstations
2. Click Invite User
3. Enter the employee's email address and click Send Invitation

They receive an email with per-platform download links (Linux, macOS, Windows) and an enrollment token pre-configured in the setup instructions. Once they install and run the tray app, their workstation appears in your dashboard automatically.

10. Manual enrollment (alternative)

If you prefer to enrol manually instead of using email invitations:

1. In the dashboard go to Settings → Workstations → Generate Enrollment Token
2. Copy the token (single-use, expires in 24 hours)
3. On the workstation run:

bitdrip enroll --server http://<your-server-ip>:3002 --token <token>

The tray app will connect, download the PAC file, and start routing AI traffic through the policy engine.

Next Steps

• Install the tray app — manage the proxy daemon on each workstation with a system tray UI
• Configure compliance profiles — GDPR, HIPAA, PCI DSS, and custom rules
• Start the proxy daemon — protect browser and CLI AI traffic transparently
• Invite your team