Appearance
Troubleshooting & FAQ
Common Errors
License file not found at './license.jwt'
Your license file is missing from the installation directory.
Fix: Download license.jwt from your welcome email and place it in the same directory as install.sh:
bash
cp ~/Downloads/license.jwt ./license.jwt
bash install.shDashboard loads but shows "Cannot connect to API"
The Dashboard can't reach the Policy Engine.
Check service status:
bash
docker compose ps
docker compose logs policy-engineLook for startup errors. Verify API_URL in .env matches the Policy Engine port (default: 3002).
Tray app shows red icon or "Daemon unreachable"
The tray app cannot reach the proxy daemon.
Verify the proxy daemon is running:
bash
curl http://localhost:3001/healthIf the proxy daemon is not running, start it with bitdrip proxy start or use Start Proxy in the tray menu.
port XXXX is already in use
Another service is using port 3000, 3001, or 3002.
Fix: Edit the port mappings in .env, then restart:
bash
docker compose down && docker compose up -dForgot admin password
bash
docker compose exec policy-engine node dist/scripts/reset-admin.jsFollow the prompts to set a new password.
no space left on device
Docker images and volumes have filled your disk.
bash
docker system prune # remove unused images/containers
docker volume prune # remove unused volumes (careful: may delete data)Policy engine starts then immediately stops (crash loop)
Cause: Redis connection instability can trigger a reconnect loop crash in @redis/client v1.5.x, surfacing as an unhandled promise rejection that kills the process.
How to tell: Check the logs for either of these patterns:
bash
docker compose logs policy-engineLook for:
Redis reconnect race (non-fatal)Unhandled Promise Rejection
Fix: This issue is resolved in v2.2.15 with a reconnectStrategy cap. If you are already on v2.2.15 and still see the crash, verify that your REDIS_URL is reachable from inside the policy-engine container:
bash
docker compose exec policy-engine nc -z redis 6379If Redis is genuinely unreachable, the policy engine (v2.2.15+) will degrade gracefully — cache is disabled and policy rules are evaluated without caching, but traffic continues to be served. The /health endpoint will return 200 degraded in this state. A crash loop should not occur.
If Redis is reachable but the crash persists, restart the Redis container and then restart the policy engine:
bash
docker compose restart redis
docker compose restart policy-engine"Enroll this computer" link does nothing
The bitdrip:// URI scheme is registered by the installer on first launch. If clicking the enrollment link does nothing:
- Confirm the tray app is installed and has been launched at least once — first launch registers the URI scheme on Windows and Linux.
- On macOS, check System Settings → General → Login Items — BitDrip should be listed. If absent, open it manually from
/Applications/BitDrip.app. - On Linux, ensure the
.desktopfile is present:ls ~/.local/share/applications/bitdrip*.desktop. If missing, re-run the installer. - Use the manual command shown in the fallback section of the invitation email:
bash
read -rsp 'Enrollment token: ' BITDRIP_ENROLL_TOKEN; echo
printf '%s\n' "$BITDRIP_ENROLL_TOKEN" | bitdrip enroll --server https://<your-policy-engine> --token-stdin
unset BITDRIP_ENROLL_TOKEN"BitDrip — Enrollment Failed" notification
Common causes:
| Cause | Fix |
|---|---|
| Enrollment token expired (24-hour limit) | Ask your admin to send a new invitation |
| Token already used (single-use) | Ask your admin to generate a new enrollment token |
| Policy engine not reachable from this workstation | Check firewall rules — port 3002 must be reachable from the workstation |
| Wrong server URL in the invitation | Ask your admin to verify the Policy Engine URL in Settings → Workstations |
If the error message reads "connect ECONNREFUSED" or "getaddrinfo ENOTFOUND", the workstation cannot reach the policy engine — see the firewall section below.
Workstation cannot reach the policy engine
The tray app and bitdrip enroll both need outbound TCP access to the policy engine (default port 3002).
Verify connectivity from the workstation:
bash
curl -v http://<policy-engine-host>:3002/healthIf this fails:
- Corporate firewall: Open outbound TCP 3002 to the policy engine host, or reconfigure the policy engine to listen on port 443 with TLS.
- Local firewall on the server: Check that the policy engine port is open:bash
# On the server (iptables) sudo iptables -L INPUT -n | grep 3002 # Allow if needed: sudo iptables -A INPUT -p tcp --dport 3002 -j ACCEPT - Docker port not exposed: Confirm your
.envhasPOLICY_ENGINE_PORT=3002and thatdocker compose psshows port 3002 bound to0.0.0.0(not just127.0.0.1).
Installing early-access workstation builds
macOS — "can't be opened because Apple cannot check it for malicious software"
Choose the path from authenticated release evidence. When the release manifest channel is early-access and signed is false, macOS Gatekeeper may show:
"BitDrip" can't be opened because Apple cannot check it for malicious software.
Before opening that early-access artifact, independently verify its SHA-256 and both Sigstore bundles against the expected workflow identity and issuer, and confirm the manifest records the intended immutable source commit. Follow the exact commands in Supply Chain Security.
Only when organization policy permits and all evidence matches may you Control-click BitDrip.app, choose Open, or use Open Anyway in System Settings → Privacy & Security. Do not disable Gatekeeper, antivirus, or enterprise policy. If a managed device blocks the early-access artifact, stop and contact the administrator; do not bypass the control.
When authenticated evidence instead reports stable-signed, require the expected signing, notarization, and Gatekeeper validation, then use the normal macOS installation flow. An unexpected warning or channel/signing mismatch blocks installation.
Windows — "Windows protected your PC"
Windows Early Access — Unsigned may show Unknown publisher and the following Microsoft Defender SmartScreen dialog:
Windows protected your PC
Microsoft Defender SmartScreen prevented an unrecognized app from starting.
Before opening the installer, verify both Sigstore bundles against the expected workflow identity and issuer, confirm the manifest names the intended source commit, and independently compute the installer SHA-256. Follow the exact commands and prerequisites in Supply Chain Security. A checksum copied from the same unauthenticated download location is not independently authenticated release evidence.
Only when organization policy permits and the computed SHA-256 matches that independently authenticated release evidence, select More info, then Run anyway. Do not disable SmartScreen, antivirus, UAC, or enterprise policy. Never bypass an enterprise control. A managed device may be blocked; stop and wait for the future stable-signed Windows release or ask the administrator to deploy an approved package.
Uninstalling BitDrip on macOS
Use Uninstall BitDrip… in the BitDrip tray menu. The guided flow disables BitDrip-owned routing, stops the local proxy, disables launch at login, removes BitDrip from the Dock, requests administrator approval to remove the trusted BitDrip certificate, and moves the application to Trash.
Enrollment, configuration, and logs are preserved by default so a reinstall can reuse the workstation enrollment and support evidence. Select Remove local data only when the workstation should be fully decommissioned. BitDrip asks for a second confirmation before making changes.
If macOS asks for administrator credentials, approve the prompt. Cancelling the prompt leaves BitDrip installed because removing the application while its certificate remains trusted would be unsafe.
If the guided flow reports a failure:
- Follow the remediation shown in the error dialog and retry Uninstall BitDrip….
- For a Login Item failure, open System Settings -> General -> Login Items and disable BitDrip.
- For a certificate failure, open Keychain Access, select System Keychains -> System, locate
BitDrip Local CA, verify it is the BitDrip certificate for this workstation, and remove it with administrator approval. - For a routing failure, open System Settings -> Network, select the active service, open Details -> Proxies, and remove only entries pointing to
127.0.0.1:3001orhttp://127.0.0.1:3001/proxy.pac. Do not remove an organization's unrelated proxy settings.
Contact the workstation administrator if ownership of a proxy setting or certificate cannot be confirmed.
Diagnostic Commands
bash
# View all service logs
docker compose logs -f
# Check specific service
docker compose logs -f policy-engine
# Health check
curl -s http://localhost:3002/health | python3 -m json.tool
# Restart a service
docker compose restart policy-engine
# Resource usage
docker stats $(docker compose ps -q)FAQ
Does BitDrip send any data to Anchor Cyber Security?
The running product sends only a license validation signal to portal.bitdrip.app — a hash of your installation ID and license ID. No conversation content, prompts, user data, or policy configurations are ever transmitted.
Can I run BitDrip without internet access?
Yes. The Policy Engine operates fully offline. License validation requires internet access on first start; after that, a 7-day grace period applies if connectivity is lost.
What AI services does BitDrip protect?
The proxy daemon can inspect configured HTTPS destinations for ChatGPT, Claude, Google Gemini, Microsoft Copilot, Perplexity, HuggingFace, Poe, You.com, Outlook Web Copilot, M365 Copilot Chat, M365 Copilot Hub, Microsoft Teams, and Office Online apps. Additional domains can be added via custom URL patterns in Admin Dashboard → Policies → Proxy Sites. Tested browsers and applications that honor the OS proxy or PAC settings are supported without a browser extension. CLI and SDK tools require explicit HTTPS proxy and CA configuration. Validate every managed application before claiming coverage.
Applications that bypass proxy settings, use certificate pinning, connect by direct IP, or use unsupported transports are not guaranteed to be protected by the current workstation client.
Does BitDrip scan AI responses, not just what I send?
Yes. The Proxy Daemon intercepts AI responses at the TLS layer before they reach your browser or CLI tool. All detection rules fire on both request and response bodies. Violations detected in responses are flagged with direction: response in the Audit Log. For browser sessions, blocked responses return an HTTP 403 before any content is rendered.
Does BitDrip support Safari?
BitDrip is not browser-extension based. The tray app protects apps that use the configured system proxy or PAC URL. Chrome, Firefox, and Edge are tested first; Safari support depends on macOS system proxy behavior and should be validated in your deployment.
How do I update BitDrip?
Download the new bundle from portal.bitdrip.app after signing in. Copy your license.jwt and .env into the new directory, then run install.sh.
How many users can I have?
Community: 3 (evaluation) · Team: 10 · Starter: 50 · Professional: 250 · Enterprise: 500+. See bitdrip.app for pricing.
How do I get support?
Email contact@anchorcybersecurity.com with your BitDrip version (docker compose exec policy-engine node -e "console.log(require('./package.json').version)") and a description of the issue.