Skip to content

BugTraceAI/BugTraceAI-Launcher

BranchesTags

Repository files navigation

BugTraceAI

BugTraceAI Launcher

One-command deployment for the BugTraceAI security platform via Docker.

Launcher version source of truth: VERSION

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.

New in v2.8.3: The experimental AI installer is now the AI Setup & Repair Assistant (ai_installer.py, Claude Haiku 4.5). It can install from scratch or repair/diagnose an existing deployment, and you pick the scope (Full / CLI / WEB). The OpenRouter API key is entered with hidden input and only shown back masked. Commands run in a stateful persistent Bash shell under a kernel-enforced timeout, destructive commands require confirmation, and the conversation is in Spanish. The standard installer now streams Docker's native build output (no fragile spinner), installs dependencies across distros (apt/dnf/yum/pacman/zypper), and writes generated .env files with 600 permissions.

This repository is part of the BugTraceAI monorepo (as a git submodule) and also works as a standalone repo.

Quick Start

One-liner install (recommended):

curl -fsSL https://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh | bash

Or step by step:

git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git ~/bugtraceai-launcher
cd ~/bugtraceai-launcher
./launcher.sh

The wizard will guide you step by step: choose installer mode, choose deployment mode, enter your OpenRouter API key, configure ports, and confirm. The launcher handles the rest.

During one-liner setup, if Python 3 and ai_installer.py are available, you will also be asked whether you want to try the experimental AI Setup & Repair Assistant:

Try the AI Setup & Repair Assistant (Experimental — installs & troubleshoots)? [y/N]

Choose N for the standard wizard, or Y to let the AI installer guide and troubleshoot the deployment.

If you start from a local clone with ./launcher.sh, the first menu also lets you choose between the standard guided installer and the experimental AI Setup & Repair Assistant.

Requirements

Requirement Details
OS Linux (x86_64) or macOS (Intel / Apple Silicon)
Container Runtime Docker Engine 24.0+ + Compose (Linux), or on macOS: Docker Desktop OR Colima
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-)

Auto-Installation (Linux)

The installer will automatically detect and offer to install missing dependencies across major Linux distros:

  • ✅ Git & curl → Installed via your package manager (apt-get, dnf, yum, pacman, or zypper) if 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 no supported package manager is found, the installer provides manual installation instructions.

Auto-Installation (macOS)

The launcher now supports two runtime paths on macOS:

  • Docker Desktop (traditional)
  • Colima (Docker Desktop-free)

If Docker is not ready, the wizard can:

  • Prompt you to choose Docker Desktop or Colima
  • Install missing dependencies with Homebrew (docker, docker-compose, colima, qemu, lima-additional-guestagents)
  • Start the selected runtime automatically and continue installation

For best automation, install Xcode CLT first if missing:

xcode-select --install

Deployment Modes

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.

Commands

./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 usage

No sudo required. On Linux, your user needs Docker permissions (sudo usermod -aG docker $USER). On macOS, the launcher can bootstrap either Docker Desktop or Colima.

Architecture

┌──────────────────────────────────────────────────────────┐
│                      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.

Default Ports

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.

What Gets Installed

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

Configuration

WEB config: ~/bugtraceai/BugTraceAI-WEB/.env.docker

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)

CLI config: ~/bugtraceai/BugTraceAI-CLI/.env

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

Updating

./launcher.sh update

Pulls the latest code from both repos and rebuilds Docker images. The CLI's docker-compose.yml is re-patched automatically after pulling.

Uninstalling

./launcher.sh uninstall

Stops all containers, removes Docker volumes (including databases), and deletes the ~/bugtraceai/ directory. Asks for confirmation before proceeding.

Troubleshooting

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 status

Port 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): Re-run ./launcher.sh and choose a runtime when prompted. If you pick Colima, the launcher can install/start it automatically via Homebrew.

Colima start fails with missing guest agent: Install and retry:

brew install lima-additional-guestagents
colima start --runtime docker

macOS MCP Compatibility Notes (reconFTW + Kali)

The launcher now applies macOS-focused compatibility patches during deployment when these MCPs are enabled.

reconFTW MCP (Apple Silicon):

  • Forces linux/amd64 for six2dez/reconftw:main on ARM hosts.
  • Patches reconftw-mcp Dockerfile for Python venv fallback (virtualenv) when ensurepip fails.
  • Forces SSE mode for WEB-managed MCP startup (/sse health path consistency).
  • Extends reconFTW health timing on ARM emulation.
  • Patches startup behavior to skip heavy reconftw/install.sh auto-bootstrap by default (RECONFTW_AUTO_INSTALL=false) to avoid health timeouts.

Kali MCP:

  • Rewrites the Kali startup command into a robust single bash -lc command to avoid multiline parsing/continuation issues during package install.
  • Verifies key binaries (nmap, hydra, python3) after install in container startup.

If you still see MCP issues after pulling latest launcher changes, rebuild only the affected service:

cd ~/bugtraceai/BugTraceAI-WEB
docker compose --env-file .env.docker build --no-cache reconftw-mcp kali-mcp
docker compose --env-file .env.docker up -d reconftw-mcp kali-mcp

Then inspect logs:

docker logs --tail 200 reconftw-mcp
docker logs --tail 200 kali-mcp-server

Existing installation detected: If ~/bugtraceai/ already exists, the wizard offers to reinstall (wipe + fresh setup) or update (pull + rebuild).

How the Install Script Works

The one-liner clones this repo to ~/bugtraceai-launcher/ and launches the interactive wizard, which:

  1. Bootstraps dependencies: Git/curl first, then clones or updates the Launcher
  2. Selects installer mode: Standard guided wizard or experimental AI Setup & Repair Assistant
  3. Checks runtime: Docker runtime + Compose checks, including Docker Desktop or Colima on macOS
  4. Selects deployment mode: Full (WEB + CLI), Standalone WEB, or Standalone CLI
  5. Configures: Asks for OpenRouter API key, proposes ports, generates .env files
  6. Deploys: Clones repos, builds Docker images, starts services, runs health checks

AI-Assisted Installer

BugTraceAI Launcher includes an optional AI Setup & Repair Assistant (ai_installer.py) powered by Claude Haiku 4.5 (via OpenRouter). You choose up front whether to install from scratch or repair/diagnose an existing deployment, then the scope (Full / CLI / WEB). The API key is entered hidden and shown back masked, destructive commands require confirmation, and the assistant can autonomously:

  • Analyze your system configuration and error logs
  • Diagnose Docker, network, port, or dependency issues
  • Propose and apply fixes interactively
  • Guide you through complex deployment scenarios (VM hosts, non-standard environments)

The AI mode starts only after explicit confirmation with a classic [y/N] prompt. If you answer y, it asks for your OpenRouter API key and validates it before starting Haiku; invalid keys stop the installer with an error. After validation, it can execute shell commands through its run_command tool while attempting to complete the installation, so use it primarily on clean VMs, VPS instances, or disposable test environments.

How to invoke

The one-liner can offer AI mode before the standard wizard starts, and ./launcher.sh exposes it in the first menu:

cd ~/bugtraceai-launcher
./launcher.sh

Requirements

  • Python 3.8+ (usually already present)
  • Your OpenRouter API key (the same one used for BugTraceAI)
  • Internet access to reach the OpenRouter API

The AI installer uses Claude Haiku through OpenRouter. It is experimental and can run commands after you opt in, so review the terminal output and use the standard wizard if you prefer fully manual control.

License

AGPL-3.0 License. See the LICENSE file for details.

Links

Made with care by Albert C. @yz9yt
bugtraceai.com

About

One-command Docker deployment wizard for BugTraceAI — interactive setup, 3 deployment modes, auto-configuration

bugtraceai.com

Resources

Readme

License

AGPL-3.0 license
Activity
Custom properties

Stars

15 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases 1

v2.5.2 — AI-Assisted Installer, macOS Apple Silicon, Universal Terminal Compatibility Latest
Jun 15, 2026

Packages

 
 
 

Contributors

Languages