GoogleFindMyToolsWebUi

A self-hosted app that logs into your Google account, keeps polling your Find My Device / Find Hub trackers and Android phones, and forwards each new location to your own Traccar or Nextcloud PhoneTrack server, so you keep your location history on your own infrastructure instead of nowhere. One Docker container, a web UI, nothing else to run.

It's built on top of GoogleFindMyTools, the original reverse-engineering work that figured out how to talk to Google's Find My Device / Find Hub network at the protocol level (querying trackers, decrypting end-to-end encrypted locations, registering custom ESP32/Zephyr trackers). That original tool is still in here and still works as a set of Python scripts - see Advanced: running it as a CLI tool below. Everything described in the rest of this README is a self-hosted app built around it: a web UI, a scheduler, multi-destination forwarding, and the operational stuff (logging, throttling, auth, encryption at rest) a service you actually leave running needs.

[!CAUTION] This holds long-lived Google account tokens and live device location data. It's meant for local/LAN use - see Security below before exposing it any further than that.

Features

• Devices page - every tracker and phone on your account, in one list. Manual "Locate" and "Play sound" buttons, plus whatever the last scheduled poll found. Shows last-seen time for phones and tags alike.
• Scheduled forwarding, not a one-off export - each device polls on its own cron schedule and forwards to as many destinations as you want, each with its own schedule and its own alias. Every destination is really the same generic HTTP request builder (method, URL - query string and all - headers, body, all with {{latitude}}-style placeholders) - Traccar, and Nextcloud PhoneTrack's OsmAnd, GpsLogger, Locus Map, uLogger, OwnTracks, and Overland-compatible log endpoints are just one-time presets that pre-fill it when you're setting up a new endpoint, so you can add a custom endpoint (a different self-hosted service, a webhook, whatever takes HTTP) without waiting on this project to add it by name.
• Skip pointless updates - two independent, opt-in gates per destination: skip sending if the device hasn't moved far enough, and skip re-sending the same stale cached fix Google keeps returning. Both are local math (haversine distance), no external API calls, no extra cost.
• Logging - every forwarding attempt and every warning/error anywhere in the app (a failed locate, an expired token, a forwarding failure) lands in a searchable in-app log, with errors also pushed out live through Apprise to whatever you already use (ntfy, Discord, Telegram, Pushover, email, 100+ others) - configured from the Config page, no restart needed.
• Register your own trackers - pair a custom ESP32- or Zephyr-based BLE tracker straight from the web UI.
• Build and flash ESP32 firmware from the browser - the Firmware page bakes a registered tracker's key into an ESP32/ESP32-C3 build (device name, advertising interval, TX power, and the unwanted-tracking-protection flag are all configurable), then flashes it over USB via Web Serial, or gives you a plain .bin to flash yourself. Still marked experimental in the UI - hasn't been exercised across every board/setup yet. Other Zephyr-supported boards link out to a manual build/flash guide instead.
• Account-wide rate limiting - every call to Google's backend (device list, locate, sound, register) goes through one shared throttle, tunable live from the Config page, so a burst of manual clicks and every device's poll loop can never combine into something that gets your account flagged.
• /metrics - a small set of Prometheus-format gauges (uptime, sign-in status, query-throttle queue depth, forwarding/system log entry counts by outcome) if you already scrape other self-hosted services and want this one in the same dashboard. Behind the same Basic Auth as everything else when configured.

Screenshots

Quick start

docker compose up -d

This pulls the pre-built image from ghcr.io/p6g9yhk6/googlefindmytools - no local build, no Chrome install on the host. Then open http://localhost:4321 and go to Config → Sign in with Google.

Chrome and the Xvfb/x11vnc/noVNC stack needed for that one-time Google login aren't baked into the image - they install on demand into an in-memory directory the first time you sign in. The Config page shows live progress while this happens, and you complete the actual Google login in an embedded browser view right there on the page - no separate machine, no VNC client needed.

Building from source instead: docker compose -f docker-compose.dev.yml up --build.

Configuration

Copy .env.example to .env and fill in what you need, or pass these directly to docker run/docker compose. Everything is optional - the defaults are a reasonable, auth-free single-user setup.

The Config page also has fields for the query throttle and Apprise notification settings, applied immediately without a restart.

Demo mode

Set DEMO_MODE=1 to run a public-facing instance that shows off the UI with no real Google account and no real data at all - useful for a public demo link, a quick local screenshot/dev aid, or a CI/screenshot-testing fixture. It's the same image everyone else runs, just this one env var - not a separate build.

With it on:

• Every page (Devices, Firmware, Forwarding Settings, Staleness, Logs, Config) shows the same fixed set of ~10 fake devices (deterministic, same every restart), realistic Bay Area coordinates, no movement.
• Locate/Play Sound/Register Tracker all return a fake success instantly - nothing real is contacted.
• Forwarding Settings comes pre-filled with example endpoints pointed at obviously-fake (.invalid) hosts; saving or "Send now" always simulates success and is never actually sent or persisted.
• Staleness tracking shows a realistic mix of fresh/stale devices from the fixed dataset; toggling tracking works but is never persisted.
• The Logs page shows canned example history instead of this process's own logs.
• Firmware Build is disabled outright (not simulated) - it's a real multi-minute compile with a real toolchain download, too heavy/real to fake safely.
• Debug Export's "Live API query" is disabled outright - it would otherwise run a real, uncached device-list + locate-all query. The logs-only export still works, with the canned demo logs.
• Real Google sign-in is disabled server-side (not just the greyed-out button) - a public instance can never be made to spin up the real embedded-browser login flow.
• Every outbound network call this process could make is additionally hard-blocked at a low level, regardless of what a visitor types into any form - see webui/demo_network_guard.py.
• Nothing a visitor does is ever written to disk; a small 🚩 Demo flag next to the build id in the footer is the only visual tell.

Independently of DEMO_MODE, any normal instance (the env var unset) with no Google account signed in yet shows the same fake devices on the Devices page only, as an onboarding placeholder instead of an empty table - real sign-in stays fully live, and this never affects Settings/Staleness/Logs/Firmware/write-actions.

Security

[!CAUTION] By default this is plain HTTP with no auth - meant for a trusted LAN (or behind your own reverse proxy/VPN if you need remote access), not exposed directly to the public internet. HTTPS_ENABLED=1 gets you transport encryption (see below), but self-signed TLS still isn't the same as a real reverse proxy or VPN for anything beyond casual LAN use. The one supported way to expose this app to the public internet is DEMO_MODE=1, which runs with no real account, no real data, and no outbound network access at all.

• Set HTTP_USER/HTTP_PASSWORD to gate the whole UI, including /docs (FastAPI's interactive API explorer) - it's one more route behind the same middleware, not a separate hole.
• Set HTTPS_ENABLED=1 to serve HTTPS with an automatically generated, persisted self-signed certificate - no separate reverse proxy needed. Your browser will show a one-time "not trusted" warning the first time (expected for any self-signed cert, not a sign something's wrong) - accept/pin it, or point GFMT_TLS_CERT_PATH/GFMT_TLS_KEY_PATH at a real cert instead if you have one. This defeats passive network snooping but gives no identity guarantee the way a CA-signed cert does. It's a toggle, not a dual mode - with it on, plain http:// to the same port gets a connection reset, not a redirect.
• Set SECRETS_ENCRYPTION_KEY to encrypt credentials at rest instead of plain YAML. Back this up somewhere alongside (or independent of) your GFMT_DATA_DIR volume: it's not stored anywhere itself, and losing or changing it makes every already-encrypted value in auth.yaml permanently unreadable - your only recovery is signing in again from scratch, not restoring the key.
• Everything - config, credentials, logs - lives in the one data directory you control; nothing phones home except to Google's own APIs and (if you configure it) your Apprise notification targets.

Advanced: running it as a CLI tool

The original scripts this project is built on still work standalone, without Docker or the web UI - useful for scripting or if you just want to query a device once.

[!CAUTION] Before starting, ensure Chrome and Python are up to date - if Chrome isn't current, this will not work.

• Clone this repository: git clone or download the ZIP file
• cd GoogleFindMyToolsWebUi
• Optional: create/activate a venv (python -m venv venv, then venv\Scripts\activate on Windows or source venv/bin/activate on Linux/macOS)
• pip install -r requirements.txt
• Install the latest Google Chrome
• python main.py

On first run this walks you through the same Google sign-in as the web UI, storing the result in Auth/auth.yaml - copy that file to run on a headless machine without Chrome. (Upgrading from an older version that still has Auth/secrets.json migrates it automatically the first time it's read; the old file is left in place, untouched.) SECRETS_ENCRYPTION_KEY (see Configuration) applies here too.

TODO

• Finish the live data scraper: battery level, wifi, wifi signal strength, force a phone update and any other data found via this api.
• AirTag support, with the help of a reverse-engineered locate app: AirtagAlex, demo video.