Deployment Guide
System requirements, setup, and network configuration
System Requirements
Minimum
- Windows 10 / macOS 12 / Ubuntu 22.04
- 4 GB RAM
- 200 MB disk space
- Internet connection
Recommended
- Windows 11 / macOS 14 / Ubuntu 24.04
- 8 GB RAM
- 500 MB disk space
- Administrator / root access
Image scanning uses Bleep's built-in OCR engine with embedded ML models - no additional software required. Works on Windows, macOS, and Linux.
Individual Setup
The Individual plan runs as a standalone desktop application. No server or IT infrastructure required.
- 1Download the installer from your dashboard (Windows .msi/.exe, macOS .dmg, or Linux .AppImage/.deb/.rpm)
- 2Run the installer and follow the setup process
- 3Enter your license key when prompted (format:
LIC-XXXX-XXXX-XXXX-XXXX) - 4Install the CA certificate (required for HTTPS inspection of AI traffic)
- 5Bleep starts protecting - runs in your system tray
Team Deployment
Team plans include a centralized admin server for policy management and monitoring. The admin server runs on your infrastructure via Docker.
Admin Server Setup (Docker)
Create a .env file next to your docker-compose.yml with the following:
BLEEP_LICENSE_KEY=LIC-XXXX-XXXX-XXXX-XXXX
BLEEP_PROXY_PORT=8080
BLEEP_WEB_PORT=8081- •
BLEEP_LICENSE_KEY- Your license key (required) - •
BLEEP_PROXY_PORT- Port for proxied AI traffic inspection (default: 8080) - •
BLEEP_WEB_PORT- Port for the admin dashboard & API (default: 8081)
Change the port values if the defaults conflict with other services on your machine.
Then start the server:
docker-compose up -dDirect Setup (No Docker)
Run the admin server directly with Python. Use the --bind flag to make it accessible to endpoint devices on your network:
python -m bleep --server-only --web-port 8081 --bind 0.0.0.0By default, the server only listens on 127.0.0.1 (localhost). The --bind 0.0.0.0 flag makes it listen on all network interfaces so other machines on the LAN can connect. Docker deployments already handle this via port mapping.
Open the dashboard at http://YOUR-SERVER-IP:BLEEP_WEB_PORT (e.g. http://192.168.1.50:8081). Use the server's LAN IP so employee machines can reach it.
Endpoint Deployment
Deploy the endpoint app to team devices using your existing software deployment tools (SCCM, Intune, Jamf, etc.) or have users install manually.
- • Available as .msi (Windows), .dmg (macOS), .AppImage/.deb/.rpm (Linux)
- • Each endpoint requires a license key for activation
- • License is bound to the instance on first validation
- • Endpoint ports (proxy & PAC) are managed from the admin dashboard under Settings → Endpoint Ports and pushed to all devices automatically
Environment Variables
Bleep can be configured via environment variables or a YAML config file (config.yaml or bleep.yaml).
| Variable | Default | Description |
|---|---|---|
| BLEEP_LICENSE_KEY | - | Your license key (required) |
| BLEEP_PROXY_PORT | 8080 | HTTP/HTTPS proxy port (admin server) |
| BLEEP_WEB_PORT | 8081 | Dashboard & API port (also used in Docker port mapping) |
| BLEEP_PAC_PORT | 18080 | PAC file server port |
| BLEEP_BIND_HOST | 127.0.0.1 | Bind address - use 0.0.0.0 for LAN access (CLI: --bind). Docker handles this via port mapping. |
| BLEEP_MODE | warning | Operating mode: learning, warning, or enforcing |
| BLEEP_SECRET_KEY | - | Session secret (Docker admin server) |
| BLEEP_LICENSE_API_URL | (built-in) | License API URL override |
| BLEEP_IMAGE_SCANNING | true | Enable OCR-based image scanning |
Network Configuration
Firewall Rules
Bleep needs outbound HTTPS access for license validation and updates:
| Service | Destination | Port |
|---|---|---|
| License validation | *.supabase.co | 443 |
| Updates & downloads | *.supabase.co | 443 |
| AI services (proxied) | See destinations config | 443 |
Local Ports
Bleep uses three local ports. All bind to 127.0.0.1 by default (localhost only). Use --bind 0.0.0.0 or BLEEP_BIND_HOST=0.0.0.0 to accept connections from other devices on your network. All ports are configurable via environment variables, config file, or the admin dashboard.
| Default Port | Purpose | Notes |
|---|---|---|
| 8080 | HTTP/HTTPS proxy | Only AI traffic is routed here via PAC |
| 8081 | Web dashboard | Admin UI and API |
| 18080 | PAC file server | Serves proxy.pac for selective routing |
Only AI traffic is routed through the proxy via PAC-based selective routing. All other traffic (browsing, email, apps) goes direct without any inspection. For team deployments, endpoint ports (proxy & PAC) are managed centrally from the admin dashboard and pushed to all enrolled devices.