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.sh

Dashboard 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-engine

Look 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/health

If 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 -d

Forgot admin password

bash

docker compose exec policy-engine node dist/scripts/reset-admin.js

Follow 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-engine

Look 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 6379

If 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 .desktop file 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

bitdrip enroll --server https://<your-policy-engine> --token <enrollment-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/health

If 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 .env has POLICY_ENGINE_PORT=3002 and that docker compose ps shows port 3002 bound to 0.0.0.0 (not just 127.0.0.1).

Installing on macOS or Windows (unsigned build)

Early-access builds of the BitDrip tray app are not yet code-signed. macOS and Windows will show a security warning on first install. This is expected for the current early-access version.

macOS - "can't be opened because Apple cannot check it for malicious software"

macOS Gatekeeper blocks unsigned apps by default. You will see a dialog like:

"BitDrip" can't be opened because Apple cannot check it for malicious software.

Fix:

Open the downloaded .dmg, then drag BitDrip to Applications.
In Finder, open Applications.
Right-click → Open or Control-click BitDrip.app, then choose Open.
Click Open in the confirmation dialog.

If macOS 13 or later still blocks the app:

Open System Settings → Privacy & Security.
Scroll to the Security section.
Find the message that BitDrip was blocked because it is not from an identified developer.
Click Open Anyway.
Confirm by clicking Open.

BitDrip will launch normally after this. You only need to approve the app once.

Windows - "Windows protected your PC"

Windows SmartScreen flags unsigned installers from unknown publishers. You will see a dialog like:

Windows protected your PC
Microsoft Defender SmartScreen prevented an unrecognized app from starting.

Fix:

In the SmartScreen dialog, click More info.
Click Run anyway.

BitDrip will install normally after this prompt.

Signed Windows and macOS builds are planned after production signing certificates are available. These workarounds are only needed for the current early-access version.

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 intercepts HTTPS traffic to: 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. Coverage applies to both browser traffic and CLI tools (via system proxy settings) — no browser extension required.

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.

Troubleshooting & FAQ ​

Common Errors ​

License file not found at './license.jwt' ​

Dashboard loads but shows "Cannot connect to API" ​

Tray app shows red icon or "Daemon unreachable" ​

port XXXX is already in use ​

Forgot admin password ​

no space left on device ​

Policy engine starts then immediately stops (crash loop) ​

"Enroll this computer" link does nothing ​

"BitDrip — Enrollment Failed" notification ​

Workstation cannot reach the policy engine ​

Installing on macOS or Windows (unsigned build) ​

macOS - "can't be opened because Apple cannot check it for malicious software" ​

Windows - "Windows protected your PC" ​

Diagnostic Commands ​

FAQ ​

Troubleshooting & FAQ

Common Errors

`License file not found at './license.jwt'`

Dashboard loads but shows "Cannot connect to API"

Tray app shows red icon or "Daemon unreachable"

`port XXXX is already in use`

Forgot admin password

`no space left on device`

Policy engine starts then immediately stops (crash loop)

"Enroll this computer" link does nothing

"BitDrip — Enrollment Failed" notification

Workstation cannot reach the policy engine

Installing on macOS or Windows (unsigned build)

macOS - "can't be opened because Apple cannot check it for malicious software"

Windows - "Windows protected your PC"

Diagnostic Commands

FAQ