Castles

Local Gmail relationship discovery

Understand the services reflected in your inbox—without sending your mail elsewhere.

Castles is a local command-line application. It reads an explicitly authorized Gmail mailbox, derives privacy-minimized relationship findings, and keeps those findings on your device.

Install the current release View source code

A deliberately small boundary

Local by design

No Castles backend

OAuth and Gmail API traffic goes directly between the local Castles process and Google. Castles operates without a hosted application server.

Raw content stays ephemeral

Message headers, visible text, and links are processed in bounded memory. Raw messages, subjects, bodies, and complete URLs are not stored by Castles.

Findings stay on your device

Privacy-minimized signals and findings are saved in a local SQLite database. Castles has no analytics, advertising, telemetry, or automatic uploads.

The public onboarding goal

A browser approval, then a local scan

  1. Install Castles. Use the versioned wheel from the official GitHub release.
  2. Authorize read-only access. Castles opens Google in your browser and listens only on 127.0.0.1 for the protected desktop callback.
  3. Scan locally. Castles reads authorized Gmail evidence and builds local findings.
  4. Review offline. Results, detail views, and exports do not require Gmail or network access.

Current availability: public no-file onboarding is undergoing Google verification and is not yet available. Stable version 0.1.2 remains intended for advanced users who explicitly supply their own Google desktop OAuth client.

Current stable release

Install Castles 0.1.2

Python 3.12 or newer and uv are required. Verify the release checksum before installation when your environment requires artifact verification.

uv tool install https://github.com/luigiverona/castles/releases/download/v0.1.2/castles-0.1.2-py3-none-any.whl
castles --version

You remain in control

castles logout removes saved Castles authorization from the local device. You can separately revoke the Google grant in your Google Account and delete local findings or exports whenever you choose.

Read the retention and deletion instructions