Skip to content
BranchesTags

Repository files navigation

BugTraceAI

BugTraceAI Launcher

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

Ask DeepWiki

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.9.2: the AI Setup & Repair Assistant is interactive again (provider, install/repair, Full/CLI/WEB, optional reconFTW/Kali). Ubuntu sudo uses the same TTY as the cached ticket and re-enters the docker group, so it no longer loops on sudo: a password is required. The AI chat restores cooked TTY + GNU readline so Backspace and arrows edit the line instead of printing ^H. Status lines still continue on their own; a real question waits for an answer. The standard guided installer is unchanged.

v2.9.0: DeepSeek V4.1 Flash via OpenRouter with sticky Qwen 3.8 Max (0902) failover; one visible native sudo ticket (never stored); host-held API key; dynamic ports; Docker Engine bootstrap on Linux; reconFTW built from local source; Kali in a separate Compose step; install.log next to launcher.sh.

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://github.com/ghraw/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 Engine → Installed automatically via Docker's official installer (get.docker.com), with a distro-package fallback, then the daemon is started and your user is added to the docker group
  • ✅ Docker Compose → Installed automatically as plugin (docker-compose-plugin) or standalone binary if missing

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 + API + CLI) All stacks, auto-connected Complete security workflow with UI
Standalone WEB WEB dashboard + BugTraceAI-API API testing and 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:<WEB_PORT>    │ http://localhost:<CLI_PORT>
          │                                │
┌─────────▼─────────────────┐     ┌────────▼──────────────────┐
│   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 can send scans to both the CLI API and BugTraceAI-API; the API engine is also enabled for Standalone WEB deployments.

The Launcher writes the same BTAI_SHARED_NETWORK into the WEB and API Compose environments. Both projects therefore join one named Docker bridge; the WEB proxy reaches the API as bugtrace-api:<selected API REST port> while the host-facing REST and MCP ports remain entirely selected by the wizard.

Selected Ports

Service Port Stack
WEB Frontend (Nginx) selected by wizard WEB
WEB Backend (Express) 3001 (internal) WEB
PostgreSQL 5432 (internal) WEB
CLI API (FastAPI) selected by wizard CLI
BugTraceAI-API REST selected by wizard API
BugTraceAI-API MCP selected by wizard API

Ports marked (internal) are only accessible between containers. The wizard selects every host-facing port, auto-detects conflicts and proposes the next available one; the API and WEB proxy receive those selected values at runtime. The numeric values shown during setup are proposals only, never service contracts or hardcoded host bindings.

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)
├── BugTraceAI-API/               ← cloned repo (if WEB selected)
│   └── .env                      ← generated provider configuration
└── .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

Installer log: the wizard and the AI installer append events to install.log in the same directory as launcher.sh (override with BUGTRACEAI_INSTALL_LOG). API keys and env-style secrets are redacted. Docker image builds still go to ~/bugtraceai/.build.log.

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

MCP and Kali Toolbox Compatibility Notes

The launcher starts optional Compose profiles explicitly after the base WEB and CLI services are up. This keeps a full selection from attempting reconFTW or Kali during the initial WEB build.

If Docker reports that ../reconftw-mcp cannot be found, run ./launcher.sh update. The launcher restores a completely missing sibling source checkout before building the recon profile. It intentionally refuses to overwrite an existing incomplete reconftw-mcp folder, so move that folder aside or restore its Dockerfile first if prompted.

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 toolbox:

  • Replaces either upstream command format with a retrying startup command and verifies nmap, hydra, and python3 before it stays running.
  • nuclei is installed separately so a transient package issue does not take down the whole toolbox.
  • The upstream Kali image is an interactive toolbox, not an HTTP/SSE MCP server, so it is not emitted as a fake MCP URL. Open a shell with docker exec -it kali-mcp-server bash.

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 --profile recon --profile kali build --no-cache reconftw-mcp kali-mcp
docker compose --env-file .env.docker --profile recon --profile kali 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 DeepSeek V4.1 Flash, with an automatic sticky fallback to Qwen 3.8 Max (0902) (both via OpenRouter). A fresh target defaults to a Full install; an existing or partial target defaults to repair/diagnosis first. The assistant only asks when a real decision is needed, such as confirming a destructive reinstall. The API key is entered hidden only if no private local CLI configuration exists, 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. It then opens the operating system's normal sudo prompt once, keeping only sudo's temporary ticket for the running launcher; the password is never stored in Python, a shell variable, or the model context. If no locally saved key is available, it asks for and validates your OpenRouter API key before starting the agent. The key is never inserted into the system prompt: dedicated host tools write it directly to the private CLI configuration.

For AI-managed fresh installs, host ports are allocated dynamically and then verified from Docker's published mappings. The WEB proxy is wired to the resolved CLI endpoint by the host tool, not by asking the model to guess a port. Every successful command/tool result immediately triggers the next model turn; after verification passes, the same loop remains available for support and repairs.

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 DeepSeek V4.1 Flash (falling back to Qwen 3.8 Max (0902)) through OpenRouter. You can override either model with BTAI_INSTALLER_MODEL and BTAI_INSTALLER_FALLBACK_MODEL; use BTAI_INSTALLER_ACTION, BTAI_INSTALLER_MODE, or BTAI_INSTALLER_PROVIDER only when you need to override the safe detected defaults. 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

Apache License 2.0. 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
Activity
Custom properties

Stars

34 stars

Watchers

0 watching

Forks

7 forks
Report repository

Releases

Packages

Contributors

Languages