One-command deployment for the BugTraceAI security platform via Docker.
Interactive wizard that clones the BugTraceAI repos, builds Docker images, generates configs, sets up databases, and orchestrates all services. Deploy WEB, CLI, or both with a single command.
This repository is part of the BugTraceAI monorepo (as a git submodule) and also works as a standalone repo.
One-liner install (recommended):
git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git ~/bugtraceai-launcher && ~/bugtraceai-launcher/launcher.shOr step by step:
git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git ~/bugtraceai-launcher
cd ~/bugtraceai-launcher
./launcher.shThe wizard will guide you step by step: choose deployment mode, enter your OpenRouter API key, configure ports, and confirm. The launcher handles the rest.
| Requirement | Details |
|---|---|
| OS | Linux (x86_64) or macOS (Intel / Apple Silicon) |
| Docker | 24.0+ with Docker Compose v2 — Docker Desktop on macOS |
| Git | Any recent version |
| curl | For the one-liner installer |
| RAM | 4 GB minimum (8 GB recommended) |
| Disk | 10 GB free space |
| OpenRouter API Key | openrouter.ai/keys (starts with sk-or-) |
The installer will automatically detect and offer to install missing dependencies (on Ubuntu/Debian systems):
- ✅ Git & curl → Installed via
apt-getif missing - ✅ Docker Compose → Installed automatically as plugin (
docker-compose-plugin) or standalone binary if missing - ℹ️ Docker Engine → If missing, the installer provides clear instructions and a quick-install command
You'll be prompted for confirmation before anything is installed. If you're on a non-Debian system, the installer will provide manual installation instructions.
Install Docker Desktop before running the launcher. The script automatically detects Docker Desktop's install location (~/.docker/bin, /usr/local/bin, Homebrew) and adds it to the PATH if needed. Git and curl are included with Xcode Command Line Tools (xcode-select --install).
The wizard presents three deployment options:
| Mode | What gets deployed | Use case |
|---|---|---|
| Full Platform (WEB + CLI) | Both stacks, auto-connected | Complete security workflow with UI |
| Standalone WEB | Browser-based dashboard only | Manual analysis, report management |
| Standalone CLI | Headless autonomous scanner only | CI/CD pipelines, automation, API-only |
In Full mode the launcher automatically configures CORS and points the WEB frontend to the CLI API — no manual wiring needed.
./launcher.sh # Interactive setup wizard
./launcher.sh status # Service dashboard (container health + endpoints)
./launcher.sh start # Start all services
./launcher.sh stop # Stop all services
./launcher.sh restart # Restart all services
./launcher.sh update # Git pull + Docker rebuild
./launcher.sh uninstall # Stop containers, remove volumes & install dir
./launcher.sh logs web # Tail WEB stack logs
./launcher.sh logs cli # Tail CLI stack logs
./launcher.sh help # Show usageNo
sudorequired. On Linux, your user needs Docker permissions (sudo usermod -aG docker $USER). On macOS, Docker Desktop handles permissions automatically.
┌──────────────────────────────────────────────────────────┐
│ User Browser │
└─────────┬────────────────────────────────┬───────────────┘
│ │
│ http://localhost:6869 │ http://localhost:8000
│ │
┌─────────▼─────────────────┐ ┌────────▼──────────────────┐
│ WEB Stack (Docker) │ │ CLI Stack (Docker) │
│ │ │ │
│ ┌─────────────────────┐ │ │ ┌─────────────────────┐ │
│ │ Nginx (Frontend) │ │ │ │ FastAPI + AI Agents │ │
│ │ React SPA │ │ │ │ Go Fuzzers │ │
│ └────────┬────────────┘ │ │ │ Playwright Browser │ │
│ ┌────────▼────────────┐ │ │ └────────┬────────────┘ │
│ │ Express + Prisma │ │ │ ┌────────▼───────────┐ │
│ │ REST API + WebSocket│ │ │ │ SQLite + LanceDB │ │
│ └────────┬────────────┘ │ │ └────────────────────┘ │
│ ┌────────▼────────────┐ │ │ │
│ │ PostgreSQL │ │ │ │
│ └─────────────────────┘ │ │ │
└───────────────────────────┘ └───────────────────────────┘
Each stack runs its own independent Docker Compose project. In Full mode, the WEB frontend sends scan requests to the CLI API endpoint.
| Service | Port | Stack |
|---|---|---|
| WEB Frontend (Nginx) | 6869 | WEB |
| WEB Backend (Express) | 3001 (internal) | WEB |
| PostgreSQL | 5432 (internal) | WEB |
| CLI API (FastAPI) | 8000 | CLI |
Ports marked (internal) are only accessible between containers. The wizard auto-detects busy ports and proposes the next available one.
The launcher installs the platform to:
~/bugtraceai/ ← configurable via BUGTRACEAI_DIR env var
├── BugTraceAI-WEB/ ← cloned repo (if WEB selected)
│ └── .env.docker ← generated config (ports, DB password, CLI URL)
├── BugTraceAI-CLI/ ← cloned repo (if CLI selected)
│ └── .env ← generated config (API key, CORS origins)
└── .launcher-state ← JSON with deployment mode, ports, version
You can override the install directory:
BUGTRACEAI_DIR=/srv/bugtraceai ./launcher.sh| Variable | Description |
|---|---|
POSTGRES_USER |
Database user (default: bugtraceai) |
POSTGRES_PASSWORD |
Database password (auto-generated, 24 chars) |
POSTGRES_DB |
Database name (default: bugtraceai_web) |
FRONTEND_PORT |
Public frontend port (default: 6869) |
VITE_CLI_API_URL |
CLI API URL (auto-set in Full mode, empty in Standalone WEB) |
| Variable | Description |
|---|---|
OPENROUTER_API_KEY |
Your OpenRouter API key |
BUGTRACE_CORS_ORIGINS |
Allowed origins (* in Standalone CLI, http://localhost:<port> in Full mode) |
After editing configs, restart for changes to take effect:
nano ~/bugtraceai/BugTraceAI-CLI/.env
./launcher.sh restart./launcher.sh updatePulls the latest code from both repos and rebuilds Docker images. The CLI's docker-compose.yml is re-patched automatically after pulling.
./launcher.sh uninstallStops all containers, removes Docker volumes (including databases), and deletes the ~/bugtraceai/ directory. Asks for confirmation before proceeding.
Services not starting:
./launcher.sh status # Check container health
./launcher.sh logs web # WEB stack logs
./launcher.sh logs cli # CLI stack logs
docker ps -a | grep bugtraceai # Raw container statusPort conflicts: The wizard auto-detects occupied ports. You can type a custom port number (1024-65535) when prompted, or press n to cycle to the next available one.
API key issues: Verify your key at openrouter.ai/keys. It should start with sk-or-. The wizard warns you if it doesn't match this pattern but lets you continue anyway.
Permission issues (Linux): Your user needs Docker permissions. Run sudo usermod -aG docker $USER and re-login.
Docker not found (macOS): Make sure Docker Desktop is installed and running. The launcher auto-detects common install paths, but if Docker still isn't found, open Docker Desktop first and try again.
Existing installation detected: If ~/bugtraceai/ already exists, the wizard offers to reinstall (wipe + fresh setup) or update (pull + rebuild).
The one-liner clones this repo to ~/bugtraceai-launcher/ and launches the interactive wizard, which:
- Checks dependencies: Docker, Docker Compose, Git, curl, RAM, and disk space
- Selects deployment mode: Full (WEB + CLI), Standalone WEB, or Standalone CLI
- Configures: Asks for OpenRouter API key, proposes ports, generates
.envfiles - Deploys: Clones repos, builds Docker images, starts services, runs health checks
MIT License. See the LICENSE file for details.
- Website: bugtraceai.com
- GitHub: github.com/BugTraceAI
- Issues: GitHub Issues
Made with care by Albert C. @yz9yt
bugtraceai.com