Docs GitHub Ko-fi

Install

Brido is a lightweight Windows desktop application written in Rust. It can be run completely standalone (utilizing local hotkeys and a stealth overlay window directly on Windows) or paired with an optional Android companion app written in Kotlin for dual-screen streaming. The system contains no account registration or baked-in API keys — it operates completely within your local network, using AI models powered by your own API configurations.

To run the server from source, clone the repository and execute the following commands in PowerShell:

TERMINAL copy
# download the latest release cd brido_server && cargo run --release # the egui window opens — QR code + PIN appear instantly

Alternatively, you can run the standalone prebuilt server binary downloaded from GitHub releases:

TERMINAL copy
# or grab the prebuilt exe from GitHub Releases brido-server-v1.0.1.exe

Pair your phone (optional)

If you choose to stream your screen to an external device, install the Android APK on a physical phone connected to the exact same Wi-Fi network as your laptop. Launch the app and point your phone's camera at the QR code displayed on the server GUI. Pairing completes in seconds, exchanging a self-signed TLS handshake and saving a session token.

If you prefer running Brido completely standalone on Windows, you can skip this step entirely and use the global hotkey overlay mode.

If the camera fails to scan or you want to connect manually, enter the server's IP address and the active 6-digit PIN shown on the server window. The connection URI uses the following schema:

TERMINAL copy
# QR encodes this URI — scan or enter manually brido://<your-local-ip>:<port>:<6-digit-pin>

Analyse a screen

Brido supports two analysis workflows depending on your configuration:

  • Standalone Windows Overlay (Hotkey Mode) — The Windows application registers global hotkeys. Pressing the capture hotkey (default Ctrl+Shift+Space) captures the active screen area under focus and triggers immediate analysis directly on your PC, displaying results in a stealthy, non-activating overlay window without requiring an external device.
  • Companion Phone Streaming — Once paired, the Windows server uses DXGI to capture desktop frames, encode them as JPEG, and push them at 15 fps over a secure WebSocket (WSS) link. Tap the anAlyse button inside the Android companion app to capture the active frame. The phone resizes the frame and POSTs it to the local server API for evaluation.

The Android client triggers analysis by firing a REST request to the server endpoint:

TERMINAL copy
POST /api/analyse Content-Type: application/json { "image_b64": "...", "model_hint": "gemini-2.0-flash" }

Configure AI providers

On first launch with no API keys set, the server opens a configuration dialog to setup your provider. Alternatively, you can edit or create a .env.local file in the folder containing your executable. If running from a read-only directory (such as Program Files), the server automatically falls back to reading/writing configurations at %APPDATA%/Brido/.env.local.

Provider Environment Variable Key
Gemini GEMINI_API_KEY
OpenRouter OPENROUTER_API_KEY
OpenAI OPENAI_API_KEY
Anthropic ANTHROPIC_API_KEY
Ollama (Local) OLLAMA_BASE_URL & OLLAMA_API_KEY

The server routes requests through configured providers using a built-in failover order: OpenRouter → OpenAI → Anthropic → Gemini → Ollama. To force a specific provider, pass a model_hint in the request payload containing part of the model identifier (e.g. gemini or gpt-4).

Stealth mode

Stealth mode applies native Windows API flags to the overlay window, protecting your session integrity. These configurations are built specifically to bypass proctoring tools and screen monitors during educational practice sessions.

  • WDA_EXCLUDEFROMCAPTURE — Excludes the overlay from capturing APIs. The window is rendered completely black or invisible in screenshots, OBS studio records, Zoom/Teams screen sharing, and proctoring capture streams.
  • WS_EX_NOACTIVATE — Bypasses window activation. The overlay never steals OS keyboard or mouse focus when clicked or opened, meaning browser visibilitychange and blur events are never fired.
  • WS_EX_TOOLWINDOW — Removes the overlay window from the Windows Alt-Tab task switcher.

Toggle stealth mode options inside the server GUI settings panel (⚙) or by using the global stealth hotkey (default Ctrl+Shift+S).

Hotkeys

All global hotkeys are registered at the system level via the Win32 API. They remain active even when the Brido server window is minimized to the system tray. Keys can be customized from the settings panel.

Action Default Hotkey Configurable
Capture & analyse Ctrl+Shift+Space Yes
Toggle visibility Ctrl+Shift+H Yes
Open settings Ctrl+Shift+O Yes
Toggle stealth Ctrl+Shift+S Yes
Direct type Ctrl+Shift+D Yes

Note: All hotkeys must use a Ctrl+ modifier prefix. Changes made in the settings GUI take effect immediately without requiring a server reboot.

Release artifacts

Every version tag (v*) pushed to the GitHub repository automatically compiles and deploys binaries and bundles through a automated GitHub Actions workflow. These release assets include:

  • brido-server-<tag>.exe — Standalone compiled Windows server binary. Can be run directly without any dependencies.
  • brido-server-<tag>-bundle.zip — Comprehensive zip archive containing the server executable, sample environment configurations (.env.local.template), and documentation.
  • brido-android-debug-<tag>.apk — Standard debug Android package, suitable for local installation and testing.
  • brido-android-release-<tag>.apk — Production release package, signed with the repository keystore.

Error reference

Common errors returned by the server API or displayed in the Android client terminal panel during operation.

HTTP 401: unauthorized
Cause:
The session token is either missing, invalid, or expired. This usually happens if the server was restarted after the phone paired, invalidating all previous token UUIDs stored in memory.
Fix:
Disconnect from the Android app and re-connect (either by scanning the fresh QR code or typing in the new PIN) to generate a new valid session token.
HTTP 413: image_payload_too_large
Cause:
The captured screen image size exceeded the maximum upload payload limit defined on the Axum server configuration.
The client will automatically attempt to downsize and compress the frame quality (from 1440p → 1024p → 768p) on failure, but extreme resolutions may still trigger this.
Fix:
Configure lower default capture dimensions or reduction settings in the Android app viewmodel settings, or lower the quality parameter (q=65) in the server's DXGI capture thread.
HTTP 422: model_unsupported_image_input
Cause:
The active model routed on the provider upstream (e.g. OpenRouter) is text-only and does not support image or multimodal inputs. This results in the API provider throwing an error indicating no multimodal endpoints found.
Fix:
Verify that your configured model name supports vision capabilities. Switch to a vision-capable model (like gemini-2.0-flash, gpt-4o-mini, or claude-3-5-sonnet) and re-submit the request.
HTTP 429: provider_rate_limited
Cause:
You have hit the request quota or rate limit of your active AI provider. This is common when utilizing free-tier API endpoints (such as OpenRouter's free models or Google AI Studio's free Gemini API limits).
Fix:
Wait a few seconds before requesting analysis again. If limits are hit repeatedly, configure alternative API keys in .env.local to enable automatic failover routing, or upgrade your API tier.
HTTP 502: provider_auth_failed / all_providers_failed
Cause:
The API key, base URL, or model identifier configured inside .env.local is invalid, or the server failed to authenticate requests with the upstream providers.
Fix:
Double-check your keys inside the server configuration GUI (or check the local .env.local file). Make sure keys contain no leading/trailing spaces or quotes. Check your internet connection.
HTTP 503: no_provider_configured
Cause:
The server has no active AI provider credentials set. The `.env.local` file is empty or is missing valid API keys for Gemini, OpenRouter, OpenAI, or Anthropic.
Fix:
Click the **Configure AI** button in the server GUI window, input a valid API key for your chosen provider, click save, and restart the server application.

Troubleshooting

Step-by-step debugging flows for the most common failure modes.

Port 8080 already in use
  1. Verify if another instance of Brido or another web server is already running on port 8080.
  2. Open PowerShell as Administrator and run the following command to terminate any process currently holding port 8080:
    TERMINAL copy
    Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
  3. Restart the server from the GUI controls.
Server starts but IP Address shows "unknown"
  1. Ensure your laptop is connected to an active local network interface (Wi-Fi or Ethernet).
  2. Restart the server to allow the local IP discovery mechanism to bind to the active network socket.
  3. If running multiple virtual network adapters (VPNs, Docker, Hyper-V), disable them temporarily to ensure Brido detects the correct physical LAN adapter.
Screen capture initialization failed
  1. Make sure the Windows server is running in a local, physical desktop session.
  2. Do not run the server within a headless VM or unsupported Windows Remote Desktop Protocol (RDP) sessions, as the DXGI desktop capture API requires an active physical display context.
  3. If you must use RDP, try VNC or alternative remote solutions that maintain active local session rendering.
Overlay window does not reappear after hiding
  1. Press your configured toggle hotkey combination again (default is Ctrl+Shift+H). The same key operates as both hide and show.
  2. Double-click the Brido icon inside the system tray (bottom-right taskbar section) to force-restore the GUI window.
  3. Alternatively, right-click the system tray icon and select Open to force coordinates recalculation and bring the window back to screen bounds.
Hotkey does not work at all
  1. Run the Brido server executable as Administrator to give the global keyboard listener higher execution rights.
  2. Check for software conflicts with other active keyboard listeners, macro programs, or hotkey managers (e.g. AutoHotkey, PowerToys, or keyboard overlay controls).
  3. Verify the application registered the keys by checking the server startup logs for hotkey binding success confirmation.
QR scanner tab crashes or camera does not open on phone
  1. Open the Android settings panel on your phone.
  2. Go to Apps → Brido and check your application permission settings.
  3. Explicitly enable Camera permissions for the application, then force-close and relaunch the app.
Connected to server but stream shows "waiting for frames"
  1. Confirm that the server is active and the GUI says "Running" status.
  2. Create a Windows Firewall rule in PowerShell as Administrator to allow incoming connections on port 8080:
    TERMINAL copy
    New-NetFirewallRule -DisplayName "Brido" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow
  3. Verify that your phone and laptop are connected to the exact same Wi-Fi SSID, and that router AP isolation is turned off.
Cannot reach server in manual entry mode
  1. Double-check the server IP address and PIN shown on the server desktop UI window.
  2. Verify that both devices are on the same Wi-Fi connection.
  3. Open your phone's web browser and navigate to https://<SERVER_IP>:8080/api/qr-info. Accept the self-signed TLS certificate warning to allow OkHttp to connect.
Portfolio Home