Network & Hosting Guide

This guide covers how to deploy BitDrip's server-side components on your own infrastructure and connect workstations to them. It applies whether you are running on a Proxmox VM in your server room, a bare-metal machine on your office network, a cloud VPS on any provider, or a combination of these.

1. Overview

Who this guide is for

Single-location offices where all employees are on the same LAN — the simplest setup
Multi-site or hybrid teams where some employees work in different offices or from home
Fully remote companies where no employees share a corporate network
Home labs and self-hosters running on Proxmox, NAS devices, or local servers
IT admins and security engineers responsible for fleet management and data loss prevention

Architecture: how data flows

Employee Laptop
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Browser (Chrome, Firefox, etc.)                           │
│       │                                                     │
│       │  HTTPS request to api.openai.com                   │
│       ▼                                                     │
│  BitDrip Proxy Daemon (127.0.0.1:8080)                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  1. Terminates TLS using local MITM CA              │   │
│  │  2. Reads request body (the prompt)                 │   │
│  │  3. Sends content to policy engine for evaluation   │   │
│  │  4a. BLOCK: returns 403 to browser                  │   │
│  │  4b. ALLOW: re-establishes TLS to LLM provider      │   │
│  └─────────────────────────────────────────────────────┘   │
│       │                          │                          │
└───────┼──────────────────────────┼──────────────────────────┘
        │                          │
        │ Evaluation request        │ LLM traffic (prompt/response)
        │ (content being analyzed)  │ (direct, never touches your server)
        ▼                          ▼
┌──────────────────┐     ┌──────────────────────────┐
│  Your Policy     │     │  LLM Provider            │
│  Engine          │     │  (OpenAI, Anthropic,     │
│  bitdrip.        │     │   Google, Copilot, etc.) │
│  acmecorp.com    │     └──────────────────────────┘
└──────────────────┘

Key insight: LLM traffic never touches your server

The proxy runs entirely on each employee's machine. Only two types of traffic leave the workstation toward your infrastructure:

Evaluation requests: the content being scanned is sent to your policy engine, which returns an allow/block decision
Heartbeats: lightweight status pings every 5 minutes (hostname, daemon version, IP, uptime)

The actual LLM conversation — the prompt and the response — travels directly from the workstation to the LLM provider. Your policy engine sees the content for evaluation purposes only; it does not proxy the LLM connection. This means:

Your VM does not carry the volume of LLM API traffic
Latency added by BitDrip is the round-trip to your policy engine, not a double-hop through your infrastructure
There is no risk of your server becoming a bottleneck for AI productivity

2. Choosing Your Network Setup

Before deploying, decide how workstations will reach the policy engine. Choose the scenario that matches your environment:

Scenario	When to use	Complexity
1 — Local network	All users are on the same LAN (office, Proxmox, home lab)	Lowest
2A — Public endpoint	Remote employees, no VPN	Low
2B — Tunnel	Remote employees, prefer not to open inbound ports	Low–Medium
2C — Mesh VPN	Maximum isolation, regulated industries	Medium–High

Scenario 1: Local Network (Office / Home Lab / Proxmox)

If every workstation is on the same network as the server, no public DNS or TLS certificate is required. This is the simplest possible setup.

Deploy the server on your host:

Follow the Docker Compose steps in Section 3. When you reach the POLICY_ENGINE_URL environment variable, set it to the host's LAN IP or an internal hostname:

dotenv

POLICY_ENGINE_URL=http://192.168.1.50:3002

or, if you have internal DNS:

dotenv

POLICY_ENGINE_URL=http://bitdrip.internal

Configure workstations:

When running bitdrip proxy start on each workstation, set the same URL so the proxy daemon knows where to send evaluation requests:

bash

POLICY_ENGINE_URL=http://192.168.1.50:3002 bitdrip proxy start

Or set it permanently in /etc/bitdrip/config.env (created by the installer):

bash

POLICY_ENGINE_URL=http://192.168.1.50:3002

No TLS required for a trusted LAN, but if you want HTTPS internally, generate a self-signed cert and trust it on all workstations using the same procedure as the MITM CA installation in the quickstart.

That's it. If your users are all on the LAN, you can stop here. The remaining sections cover exposing the policy engine to remote workers who are not on your network.

3. Infrastructure Setup (Server Side)

Prerequisites

A Linux host — a VM, bare metal server, Proxmox container, NAS, or cloud VPS (2 vCPU / 4 GB RAM minimum; 4 vCPU / 8 GB recommended for >100 seats)
Docker and Docker Compose installed on that host
A hostname or IP address that workstations can reach — on your LAN, a VPN, or the public internet depending on your setup (see Scenario 2 below for remote access options)
Your BitDrip license file (license.jwt)

Deploy with Docker Compose

Clone or copy the BitDrip server package to your VM and set environment variables before starting:

bash

# Generate secrets — run these once, store them in your secrets manager
JWT_SECRET=$(openssl rand -hex 32)
HMAC_SECRET=$(openssl rand -hex 32)
INTERNAL_SERVICE_SECRET=$(openssl rand -hex 32)

Create a .env file at the project root (never commit this file):

dotenv

# Database
DATABASE_URL=postgresql://bitdrip:changeme@postgres:5432/bitdrip

# Redis
REDIS_URL=redis://redis:6379

# License
BITDRIP_LICENSE_PATH=/run/secrets/license.jwt

# Auth secrets — generate with: openssl rand -hex 32
JWT_SECRET=<64-char-hex>
HMAC_SECRET=<64-char-hex>

# Internal service-to-service auth
INTERNAL_SERVICE_SECRET=<64-char-hex>

# The public URL employees will reach
POLICY_ENGINE_URL=https://bitdrip.acmecorp.com

# Fail closed: block all LLM traffic when policy engine is unreachable
BITDRIP_OFFLINE_POLICY=block

Start the stack:

bash

docker compose up -d
docker compose ps          # verify all services are healthy
docker compose logs -f     # watch startup logs

Check the health endpoint:

bash

curl https://bitdrip.acmecorp.com/health
# Expected: {"status":"ok","version":"...","db":"connected","redis":"connected"}

Scenario 2: Remote Access Options

If any workstations need to reach the policy engine from outside your LAN (remote employees, home workers, satellite offices), choose one of the following options. All three work regardless of where your server is hosted.

Option	Complexity	Security	VPN Required on Laptops	Best For
2A — Public Endpoint	Low	Good	No	Small teams, fast setup
2B — Tunnel	Low–Medium	Very Good	No	Most companies — no inbound ports needed
2C — Mesh VPN	Medium–High	Maximum	Yes (Tailscale/WireGuard)	Regulated industries, air-gap requirements

Option 2A: Public Endpoint (Simplest)

Expose the policy engine directly on port 443 with a standard reverse proxy in front.

Setup steps:

Provision a cloud VM with a public IP on any provider (AWS EC2, GCP Compute, Azure VM, DigitalOcean Droplet, etc.)
Open inbound port 443 in the cloud firewall; leave all other inbound ports closed
Install Caddy (recommended for automatic TLS) or Nginx + Certbot

With Caddy — create /etc/caddy/Caddyfile:

bitdrip.acmecorp.com {
    reverse_proxy localhost:3001
}

Then start Caddy: it fetches the Let's Encrypt cert automatically.

Create a DNS A record:

bitdrip.acmecorp.com → <your VM public IP>

Enable Cloudflare proxy (orange-cloud) on the A record to add WAF and DDoS protection without changing anything else

No VPN required on employee machines. Any machine with internet access can reach the policy engine.

Option 2B: Tunnel (Zero Inbound Ports — Cloudflare or similar)

The policy engine VM has no inbound ports open at all. The cloudflared daemon on the VM creates an outbound-only encrypted tunnel to Cloudflare's edge network. Employees reach bitdrip.acmecorp.com via Cloudflare as if it were a normal HTTPS endpoint, but there is no public IP to attack.

Setup steps:

Provision a VM. Do not open any inbound firewall ports.
Install cloudflared on the VM:

bash

# Debian/Ubuntu
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg > /dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared jammy main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install cloudflared

# Or download directly: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

Authenticate with your Cloudflare account:

bash

cloudflared tunnel login

Create the tunnel and configure the route:

bash

cloudflared tunnel create bitdrip
cloudflared tunnel route dns bitdrip bitdrip.acmecorp.com

Create the tunnel config at ~/.cloudflared/config.yml:

yaml

tunnel: bitdrip
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: bitdrip.acmecorp.com
    service: http://localhost:3001
  - service: http_status:404

Install and start the tunnel as a system service:

bash

cloudflared service install
systemctl enable --now cloudflared

Cloudflare manages DNS automatically. No A record to create, no cert to renew, no inbound firewall rules.

Option 2C: Mesh VPN (Maximum Isolation)

The policy engine joins a Tailscale (or WireGuard) mesh. Only laptops that are enrolled in the same mesh can reach the policy engine — it is never internet-reachable.

Setup steps (Tailscale):

Install Tailscale on the policy engine VM and join your tailnet:

bash

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --authkey=<your-reusable-auth-key>

Note the MagicDNS hostname assigned (e.g. policy-engine.tail12345.ts.net)
Set POLICY_ENGINE_URL in your .env to the MagicDNS URL:

dotenv

POLICY_ENGINE_URL=https://policy-engine.tail12345.ts.net

Obtain a Tailscale HTTPS certificate on the VM:

bash

tailscale cert policy-engine.tail12345.ts.net

Configure your reverse proxy to use this cert, or run the policy engine directly on 443 with the cert path.

In your MDM workflow (Jamf, Intune, Ansible), add Tailscale enrollment as a prerequisite to BitDrip enrollment. Laptops must join the tailnet before the BitDrip installer runs — otherwise POLICY_ENGINE_URL will be unreachable and enrollment will fail.

Important: This option requires every employee laptop to run the Tailscale client. Budget time for that rollout.

3. DNS Configuration

Option A — Public Endpoint

Create a single A record at your DNS provider:

Type:  A
Name:  bitdrip
Value: <your VM public IP>
TTL:   300

If using Cloudflare: set the proxy status to "Proxied" (orange cloud) to enable WAF and hide the origin IP.

Option B — Cloudflare Tunnel

No DNS configuration required. The cloudflared tunnel route dns command from the setup step above creates the CNAME automatically:

bitdrip.acmecorp.com → <tunnel-id>.cfargotunnel.com   (managed by Cloudflare)

Option C — Tailscale Mesh VPN

No public DNS configuration needed. Tailscale MagicDNS resolves policy-engine.tail12345.ts.net on any enrolled device automatically using Tailscale's internal nameservers.

No DNS changes on employee machines

In all three options, employee machines do not need DNS changes. The BitDrip PAC (Proxy Auto-Config) file tells the browser to route traffic to 127.0.0.1:8080 for LLM provider hostnames. The OS resolver is not involved in proxy routing.

4. TLS Certificate Management

There are two distinct TLS trust relationships in BitDrip. It is important not to confuse them:

Certificate	Purpose	Audience
Policy engine TLS cert	Secures HTTPS between workstations and your policy engine API	Issued to `bitdrip.acmecorp.com`; trusted by public CAs
BitDrip MITM CA cert	Allows the local proxy to intercept HTTPS to LLM providers	Self-signed; must be added to each workstation's OS trust store

This section covers the policy engine cert only. The MITM CA is covered in Section 5.

Option A — Let's Encrypt via Caddy or Certbot

Caddy handles cert issuance and renewal automatically. No additional configuration needed beyond the Caddyfile shown in Section 2.

Nginx + Certbot:

bash

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d bitdrip.acmecorp.com
# Certbot adds a systemd timer for auto-renewal

Option B — Cloudflare manages the cert

Cloudflare terminates TLS at the edge using a Cloudflare-issued certificate. The connection from Cloudflare's edge to your VM travels through the encrypted tunnel — no additional cert needed on the VM for the public-facing endpoint.

If you want end-to-end encryption from Cloudflare edge to your VM origin, generate a Cloudflare Origin Certificate in the Cloudflare dashboard (SSL/TLS → Origin Server → Create Certificate) and configure your reverse proxy to use it.

Option C — Tailscale HTTPS certificates

Run on the policy engine VM:

bash

tailscale cert policy-engine.tail12345.ts.net
# Outputs: policy-engine.tail12345.ts.net.crt and policy-engine.tail12345.ts.net.key

Tailscale issues a cert signed by Let's Encrypt that is valid for any device in your tailnet. Configure your reverse proxy (Nginx/Caddy) to use this cert pair.

Renewal is handled automatically by tailscale cert — run it via a monthly cron job or set up a systemd timer.

5. Workstation Deployment

CA Certificate Distribution (Critical — Do This First)

The BitDrip proxy performs TLS interception on HTTPS connections to LLM providers. To do this without browser certificate errors, the proxy uses a local CA to issue per-site certificates on the fly. This CA must be trusted by the OS.

The BitDrip installer generates the CA and adds it to the trust store automatically — but for MDM deployments, push the CA cert profile before running the installer so that certificate errors never appear, even briefly during enrollment.

The CA cert is generated per-workstation during installation. For MDM zero-touch deployments, use the following flow:

On a test machine, run the installer manually to generate the CA
Export the CA cert: bitdrip cert export --out bitdrip-ca.crt
Upload bitdrip-ca.crt to your MDM as a certificate payload
Deploy the cert profile to all target devices before deploying the BitDrip package

Note: For per-device CA keys (the default), each device generates its own CA. In this case, you cannot pre-distribute the CA cert. The installer adds it to the trust store during setup, which is why the installer requires admin/sudo privileges.

Platform-specific trust store locations:

Platform	Trust store mechanism	Installer command
macOS	System Keychain	`security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain bitdrip-ca.crt`
Windows	Windows Certificate Store (LocalMachine\Root)	`certutil -addstore -f "Root" bitdrip-ca.crt`
Linux	`/usr/local/share/ca-certificates/`	`cp bitdrip-ca.crt /usr/local/share/ca-certificates/ && update-ca-certificates`

Firefox manages its own trust store on Linux and Windows. The installer adds the cert to Firefox's NSS database via certutil (the NSS tool) separately.

MDM / Zero-Touch Enrollment

For fleet deployments, use your MDM to stage the config before the installer runs. The installer checks for these on first launch.

Step 1: Create an enrollment token

In the BitDrip admin dashboard, go to Fleet → Enrollment Tokens → New Token.

For MDM deployments, create a bulk token with a meaningful label:

Label:     2026-Q2-fleet-rollout
Max Uses:  500                    # set to 1 for individual device tokens
Expires:   2026-08-01

Copy the token string.

Step 2: Deploy the config file via MDM script

Deploy /etc/bitdrip/config.json (Linux/macOS) or %PROGRAMDATA%\BitDrip\config.json (Windows) before the installer runs:

json

{
  "policyEngineUrl": "https://bitdrip.acmecorp.com",
  "orgId": "<your-org-id>",
  "heartbeatIntervalMs": 300000
}

The orgId is shown in Admin → Settings → Organization.

Step 3: Deploy the enrollment token

Place the token at one of these paths (MDM file deploy or shell script):

Linux/macOS: /etc/bitdrip/enrollment-token
Windows: %PROGRAMDATA%\BitDrip\enrollment-token

bash

# Example MDM pre-install script (macOS/Linux)
mkdir -p /etc/bitdrip
echo -n "<your-enrollment-token>" > /etc/bitdrip/enrollment-token
chmod 600 /etc/bitdrip/enrollment-token

powershell

# Example MDM pre-install script (Windows)
New-Item -ItemType Directory -Force -Path "$env:PROGRAMDATA\BitDrip"
"<your-enrollment-token>" | Out-File -FilePath "$env:PROGRAMDATA\BitDrip\enrollment-token" -Encoding ASCII -NoNewline

Step 4: Deploy the CA cert profile

In Jamf Pro: Configuration Profiles → New → Certificate payload — upload bitdrip-ca.crt, set trust to "Always Trust."

In Microsoft Intune: Devices → Configuration → Create → Trusted certificate — upload bitdrip-ca.crt, set destination store to "Computer certificate store – Root."

In Ansible:

yaml

- name: Trust BitDrip CA cert
  copy:
    src: files/bitdrip-ca.crt
    dest: /usr/local/share/ca-certificates/bitdrip-ca.crt
    mode: '0644'
  notify: update ca certificates

handlers:
  - name: update ca certificates
    command: update-ca-certificates

Step 5: Deploy the installer package

Deploy the BitDrip installer package through your MDM's software deployment mechanism. The installer detects the pre-staged config and token, self-enrolls, generates the CA (if per-device), adds it to the trust store, and starts the daemon — no user interaction required.

First-boot sequence:

Installer reads config.json → knows the policy engine URL and org ID
Installer reads enrollment-token → self-enrolls with the policy engine
Policy engine returns a signed workstation credential
Installer generates the local MITM CA, adds it to the OS trust store
Daemon starts, configures the PAC file, begins heartbeating

Manual Installation (Smaller Teams)

For teams of under 20, manual installation is simpler than MDM setup.

Send employees this command in your IT onboarding guide:

bash

# Set your policy engine URL
export BITDRIP_POLICY_ENGINE_URL=https://bitdrip.acmecorp.com

# Run the installer with your enrollment token
bash <(curl -fsSL https://bitdrip.acmecorp.com/install-agent.sh) --token <enrollment-token>

The installer will:

Install the proxy daemon
Generate and trust the local CA cert
Configure the PAC file
Enroll the workstation with the policy engine
Start the daemon and tray app

For Windows, distribute the .exe installer with the enrollment token as a command-line argument:

powershell

.\bitdrip-installer.exe --token <enrollment-token> --policy-engine-url https://bitdrip.acmecorp.com

To generate per-employee tokens (recommended for traceability), use the BitDrip API:

bash

curl -X POST https://bitdrip.acmecorp.com/api/v1/enrollment-tokens \
  -H "Authorization: Bearer <admin-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "alice-laptop-2026", "maxUses": 1, "expiresAt": "2026-07-01T00:00:00Z"}'

6. Security Considerations

Policy engine hardening

Fail closed on connectivity loss. Set BITDRIP_OFFLINE_POLICY=block in your .env. This ensures that if the policy engine is temporarily unreachable (network blip, VM restart), the proxy blocks all LLM traffic rather than failing open and allowing unscanned content. Communicate this to employees so they do not file bug reports when the policy engine is down for maintenance.

DDoS and rate limiting. The policy engine has built-in rate limiting, but putting it behind Cloudflare (Option A or B) adds a free WAF and DDoS mitigation layer with no configuration. If using Option C (mesh VPN), the policy engine is not internet-reachable, so DDoS is not a concern.

Secret rotation. Rotate JWT_SECRET and HMAC_SECRET on a quarterly schedule (e.g. first Monday of each quarter). Use your secrets manager of choice (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or a .env file that is never committed) — do not store these in version control. After rotation, restart the policy engine container.

bash

# Generate new secrets
JWT_SECRET=$(openssl rand -hex 32)
HMAC_SECRET=$(openssl rand -hex 32)

# Update your secrets manager, then restart:
docker compose up -d --force-recreate policy-engine

Uptime monitoring. Set up an external health check on /health. Services like UptimeRobot (free tier) or BetterUptime will alert you if the endpoint goes down. If BITDRIP_OFFLINE_POLICY=block is set, a downed policy engine means employees cannot use AI tools — you want to know immediately.

bash

# Health endpoint response
curl https://bitdrip.acmecorp.com/health
{"status":"ok","version":"2.2.0","db":"connected","redis":"connected","uptime":86400}

Workstation security

Enforce daemon presence. Add a compliance check to your MDM or EDR: verify the bitdrip-daemon process is running. If it is absent, trigger a re-installation or flag the device as non-compliant in your fleet dashboard.

Protect the CA cert. MDM-pushed certificate profiles are harder to remove than user-installed ones. Use a supervised/managed profile in Jamf or Intune so the cert cannot be removed without MDM action. If users can remove the CA cert, they can bypass TLS interception.

Single-use enrollment tokens. For individual device enrollment, set maxUses: 1 on the token. This creates a one-to-one mapping of token to device in the audit log, making it easy to trace which token was used to enroll which workstation. Use bulk tokens (higher maxUses) only for fleet rollouts where per-device tokens are impractical.

Token expiration. Set expiresAt on all enrollment tokens. A token that never expires is a long-lived credential that could be misused if it leaks. 30–90 days is a reasonable window for a rollout; revoke unused tokens after the rollout completes.

What data leaves workstations

Understanding the data flow helps with privacy assessments and regulatory compliance:

Data	Destination	Frequency	Notes
Content being evaluated (prompts, responses)	Your policy engine only	Per LLM request	Sent over HTTPS; stored in your DB per your retention policy
Heartbeat (hostname, daemon version, IP, uptime)	Your policy engine only	Every 5 minutes	No sensitive user data
LLM prompt + response	LLM provider only (OpenAI, Anthropic, etc.)	Per request	Never touches your policy engine server
No data	BitDrip (the vendor)	Never	All traffic goes to the customer's own infrastructure

Network requirements

Only outbound traffic from workstations is required. No inbound ports need to be opened on employee machines.

Destination	Port	Purpose
`bitdrip.acmecorp.com` (your policy engine)	443 / HTTPS	Evaluation requests + heartbeats
LLM providers (api.openai.com, api.anthropic.com, etc.)	443 / HTTPS	Direct LLM traffic (already required)
`*.cloudflare.com` (if using Cloudflare Tunnel)	443 / HTTPS	Tunnel keepalive from policy engine VM only, not from laptops

7. Verifying the Deployment

Run through this checklist after initial deployment and after any infrastructure changes.

Admin verification

1. Check policy engine health:

bash

curl -s https://bitdrip.acmecorp.com/health | jq .
# All fields should show "connected" or "ok"

2. Check the fleet dashboard:

Open Admin → Fleet Health. Enrolled workstations appear here. A freshly enrolled workstation should appear within 6 minutes (one heartbeat interval).

Columns to verify:

Status: should be Online
Last Seen: should be within the last 5 minutes
Daemon Version: should match the version you deployed
Policy Engine Reachable: should be Yes

3. Test policy interception (end-to-end test):

On an enrolled laptop, open ChatGPT or Claude in the browser and type a prompt containing a Social Security Number, for example:

My SSN is 123-45-6789, can you help me fill out this form?

The request should be blocked. The browser should display a BitDrip block page. In Admin → Audit Logs, a new entry for this evaluation should appear with action: BLOCK and the triggered rule name.

4. Verify heartbeats:

In the fleet dashboard, confirm the workstation's Last Seen timestamp updates within 5 minutes of the test above.

5. Check audit logs:

Open Admin → Audit Logs. The blocked evaluation from step 3 should appear with:

Triggered rule (e.g. US Social Security Number)
Workstation hostname
Timestamp
User (if SCIM provisioning is configured)

Workstation self-check

Employees or IT can run the following on any enrolled machine:

bash

bitdrip status

Expected output:

BitDrip Daemon    ● running (pid 12345)
Proxy             ● active on 127.0.0.1:8080
PAC file          ● applied
Policy engine     ● reachable (bitdrip.acmecorp.com, 42ms)
CA cert           ● trusted
Enrollment        ● enrolled as laptop-alice (workstation ID: ws_01abc...)
Last heartbeat    ● 2 minutes ago

Any ✗ in this output indicates a problem. See Section 8 for remediation.

8. Troubleshooting

Proxy not intercepting traffic

Symptom: LLM sites load normally, no block pages appear, nothing shows in audit logs.

Cause: The PAC file is not applied to the browser's proxy settings.

macOS:

Open System Settings → Network → (select your connection) → Details → Proxies
Look for "Automatic Proxy Configuration" — the URL should be http://127.0.0.1:8787/proxy.pac (or as configured)
If missing, re-run: bitdrip proxy configure

Windows:

Open Internet Options → Connections → LAN Settings
Check "Use automatic configuration script"
URL should be http://127.0.0.1:8787/proxy.pac
If missing: bitdrip proxy configure (run as Administrator)

Chrome: Chrome on macOS uses system proxy settings automatically. On Linux, Chrome requires a --proxy-pac-url flag or the system proxy configured via gsettings.

Firefox: Firefox has its own proxy settings. Go to Settings → Network Settings → Use system proxy settings, or manually configure the PAC URL.

Certificate errors in browser

Symptom: Browser shows NET::ERR_CERT_AUTHORITY_INVALID or a red lock on LLM sites.

Cause: The BitDrip MITM CA cert is not in the OS trust store.

Fix:

bash

# Re-install the CA cert
bitdrip cert install

# Verify it was added
bitdrip cert status

If bitdrip cert install fails due to permissions, re-run with sudo (macOS/Linux) or as Administrator (Windows).

For MDM deployments: the CA cert profile may not have been pushed before the installer ran. Push the certificate profile via MDM again, then verify the cert appears in the trust store:

bash

# macOS — check System Keychain
security find-certificate -c "BitDrip" /Library/Keychains/System.keychain

# Linux — check ca-certificates bundle
grep -l "BitDrip" /etc/ssl/certs/*.pem

Policy engine unreachable

Symptom: bitdrip status shows Policy engine ✗ unreachable. Browser shows BitDrip error page "Unable to reach policy engine."

Check 1 — basic connectivity:

bash

curl -v https://bitdrip.acmecorp.com/health

If this times out, the problem is network-level.

Check 2 — outbound firewall:

Corporate networks, ISPs, or EDR tools sometimes block outbound 443 to unknown hosts. Confirm bitdrip.acmecorp.com is not blocked by a firewall rule. Add an explicit allow rule if needed.

Check 3 — Cloudflare Tunnel (Option B):

On the policy engine VM:

bash

systemctl status cloudflared
journalctl -u cloudflared -n 50

If the tunnel is not running: systemctl restart cloudflared

Check 4 — config URL mismatch:

bash

cat /etc/bitdrip/config.json

Confirm policyEngineUrl matches the actual URL. A trailing slash or http:// vs https:// mismatch will cause failures.

Workstation shows Offline in fleet dashboard

Symptom: Workstation appears in fleet dashboard but status is "Offline" even though the machine is on.

Cause: Heartbeat is failing. Usually a connectivity issue or misconfigured URL.

Diagnose:

bash

# Linux
tail -n 100 /var/log/bitdrip/daemon.log | grep -i heartbeat

# macOS
tail -n 100 ~/Library/Logs/BitDrip/daemon.log | grep -i heartbeat

Look for connection errors or HTTP status codes in the log.

Common causes:

Log message	Cause	Fix
`connection refused`	Policy engine is down	Check VM and Docker Compose status
`certificate verify failed`	Policy engine cert invalid or expired	Renew cert; check Caddy/Certbot logs
`404 not found`	Wrong URL path in config	Check `policyEngineUrl` in `config.json`
`401 unauthorized`	Workstation credential expired	Re-enroll: `bitdrip enroll --token <new-token>`

Enrollment fails

Symptom: Installer exits with "enrollment failed" or "token invalid."

Check 1 — token exhausted:

In Admin → Fleet → Enrollment Tokens, check the Uses column. If Current Uses >= Max Uses, the token is exhausted. Create a new token.

Check 2 — token expired:

The token's expiresAt has passed. Create a new token.

Check 3 — policy engine unreachable at enrollment time:

The installer attempts to reach the policy engine during setup. If the VM is down or the URL is wrong, enrollment fails. Confirm the policy engine is healthy before re-running the installer.

Re-run enrollment on an existing installation:

bash

bitdrip enroll --token <new-enrollment-token>

This does not reinstall the daemon or regenerate the CA — it only re-enrolls the workstation credential.

Network & Hosting Guide ​

1. Overview ​

Who this guide is for ​

Architecture: how data flows ​

Key insight: LLM traffic never touches your server ​

2. Choosing Your Network Setup ​

Scenario 1: Local Network (Office / Home Lab / Proxmox) ​

3. Infrastructure Setup (Server Side) ​

Prerequisites ​

Deploy with Docker Compose ​

Scenario 2: Remote Access Options ​

Option 2A: Public Endpoint (Simplest) ​

Option 2B: Tunnel (Zero Inbound Ports — Cloudflare or similar) ​

Option 2C: Mesh VPN (Maximum Isolation) ​

3. DNS Configuration ​

Option A — Public Endpoint ​

Option B — Cloudflare Tunnel ​

Option C — Tailscale Mesh VPN ​

No DNS changes on employee machines ​

4. TLS Certificate Management ​

Option A — Let's Encrypt via Caddy or Certbot ​

Option B — Cloudflare manages the cert ​

Option C — Tailscale HTTPS certificates ​

5. Workstation Deployment ​

CA Certificate Distribution (Critical — Do This First) ​

MDM / Zero-Touch Enrollment ​

Step 1: Create an enrollment token ​

Step 2: Deploy the config file via MDM script ​

Step 3: Deploy the enrollment token ​

Step 4: Deploy the CA cert profile ​

Step 5: Deploy the installer package ​

Manual Installation (Smaller Teams) ​

6. Security Considerations ​

Policy engine hardening ​

Workstation security ​

What data leaves workstations ​

Network requirements ​

7. Verifying the Deployment ​

Admin verification ​

Workstation self-check ​

8. Troubleshooting ​

Proxy not intercepting traffic ​

Certificate errors in browser ​

Policy engine unreachable ​

Workstation shows Offline in fleet dashboard ​

Enrollment fails ​

Network & Hosting Guide

1. Overview

Who this guide is for

Architecture: how data flows

Key insight: LLM traffic never touches your server

2. Choosing Your Network Setup

Scenario 1: Local Network (Office / Home Lab / Proxmox)

3. Infrastructure Setup (Server Side)

Prerequisites

Deploy with Docker Compose

Scenario 2: Remote Access Options

Option 2A: Public Endpoint (Simplest)

Option 2B: Tunnel (Zero Inbound Ports — Cloudflare or similar)

Option 2C: Mesh VPN (Maximum Isolation)

3. DNS Configuration

Option A — Public Endpoint

Option B — Cloudflare Tunnel

Option C — Tailscale Mesh VPN

No DNS changes on employee machines

4. TLS Certificate Management

Option A — Let's Encrypt via Caddy or Certbot

Option B — Cloudflare manages the cert

Option C — Tailscale HTTPS certificates

5. Workstation Deployment

CA Certificate Distribution (Critical — Do This First)

MDM / Zero-Touch Enrollment

Step 1: Create an enrollment token

Step 2: Deploy the config file via MDM script

Step 3: Deploy the enrollment token

Step 4: Deploy the CA cert profile

Step 5: Deploy the installer package

Manual Installation (Smaller Teams)

6. Security Considerations

Policy engine hardening

Workstation security

What data leaves workstations

Network requirements

7. Verifying the Deployment

Admin verification

Workstation self-check

8. Troubleshooting

Proxy not intercepting traffic

Certificate errors in browser

Policy engine unreachable

Workstation shows Offline in fleet dashboard

Enrollment fails