squelch

KO | EN

gitlite — search

#pytorch #python #command-line #javascript #proxy #bash #large-language-models #openai #kotlin #github

(★ 9)

email for people who hate emails (and also have personal agents)

File Explorer

ZIP Download

- - ci-passband.yml
  - ci.yml
  - release-daemon.yml
  - release-passband-ios.yml
  - release-passband-mac.yml
- - icon-1024.png
  - icon-128.png
  - icon-16.png
  - icon-180.png
  - icon-256.png
  - icon-32.png
  - icon-48.png
  - icon-512.png
  - icon-64.png
  - icon-dark-1024.png
  - icon-dark-128.png
  - icon-dark-16.png
  - icon-dark-180.png
  - icon-dark-256.png
  - icon-dark-32.png
  - icon-dark-48.png
  - icon-dark-512.png
  - icon-dark-64.png
  - mark-1024.png
  - mark-256.png
  - mark-512.png
  - mark-light-1024.png
  - mark-light-256.png
  - mark-light-512.png
  - mark-line-1024.png
  - mark-line-256.png
  - mark-line-512.png
  - mark-line-light-1024.png
  - mark-line-light-256.png
  - mark-line-light-512.png
  - mark-mono-1024.png
  - mark-mono-256.png
  - mark-mono-512.png
- - icon-dark-flat.svg
  - icon-dark.svg
  - icon-flat.svg
  - icon.svg
  - mark-light.svg
  - mark-line-light.svg
  - mark-line.svg
  - mark-mono.svg
  - mark.svg
- build.sh
- generate.ts
- README.md
- - 00-namespaces.yaml
  - 05-traefik-metrics.yaml
  - 10-warden-rbac.yaml
  - 15-warden-config.yaml
  - 20-warden.yaml
  - 30-tenants-default-deny.yaml
  - 40-wildcard-certificate.yaml
  - 50-warden-networkpolicy.yaml
  - 60-models.yaml
  - 70-tenant-limits.yaml
  - 80-monitoring.yaml
  - 90-warden-roller.yaml
  - acme-dns-token.example.yaml
  - google-oauth-client.example.yaml
  - PRODUCTION.md
  - remote-write-auth.example.yaml
  - ROLLOUT.md
  - SETUP.md
  - warden-token.example.yaml
- - README.md
- DEPLOY.md
- DOCKER.md
- squelchd.service
- update.sh
- BROKER.md
- CHANGELOG.md
- EMBED-SERVICE.md
- GETTING-STARTED.md
- HOSTED.md
- NOTIFY.md
- RELEASING.md
- SEARCH.md
- SECURITY.md
- SHIPMENTS.md
- TRACKING.md
- UX-DIRECTIONS.md
- VERIFICATION.md
- - icon.json
- - project.pbxproj
- - AnthropicStreamTests.swift
  - AttachmentKindsTests.swift
  - CidImagesTests.swift
  - EmailImagesTests.swift
  - FromOperatorTests.swift
  - GmailHealthTests.swift
  - KeyDispatchTests.swift
  - MinimapGeometryTests.swift
  - NeedTodayTests.swift
  - PairingTests.swift
  - RecentSearchRingTests.swift
  - RecipientsTests.swift
  - ReleaseNotesTests.swift
  - RemindTimesTests.swift
  - RetriageRunTests.swift
  - RuleGroupingTests.swift
  - SealedEventTests.swift
  - SearchIntentTests.swift
  - SenderIdentityTests.swift
  - SettingsSearchTests.swift
  - ShareNudgeTests.swift
  - SitrepWindowTests.swift
  - SpamWireTests.swift
  - StagedAttachmentTests.swift
  - SubjectTextTests.swift
  - ThreadArrivalsTests.swift
  - ThreadStyleTests.swift
  - UsageSeriesTests.swift
- - ChangelogTool.swift
- - fetch-sparkle.sh
- .gitignore
- build-release.sh
- build.sh
- make-appcast.sh
- make-changelog.sh
- PARITY.md
- project.yml
- release-ios.sh
- release.sh
- RELEASING.md
- signing.sh
- test.sh
- VERSION
- vm.sh
- .dockerignore
- .gitignore
- about.html
- App.tsx
- appcast.xml
- bun.lockb
- Dockerfile
- icon-180.png
- icon-512.png
- icon-dark.svg
- icon.svg
- index.html
- main.tsx
- mark.png
- mark.svg
- newsreader-var.woff2
- package.json
- privacy.html
- selfhost.html
- server.ts
- terms.html
- retriage-foreclosed-2026-08.sql
- rules.sh
- - assistant.rs
  - auth.rs
  - console.rs
  - devices.rs
  - error.rs
  - events.rs
  - gmail_write.rs
  - group_send.rs
  - groups.rs
  - guard.rs
  - handlers.rs
  - http_metrics.rs
  - invite_mail.rs
  - lib.rs
  - markdown.rs
  - pair.rs
  - sharing.rs
  - state.rs
  - tracking.rs
  - unsubscribe.rs
- - client_api.rs
  - client_assistant.rs
  - client_devices.rs
  - client_events.rs
  - client_groups.rs
  - client_invites.rs
  - client_mail_activity.rs
  - client_tracking.rs
  - client_usage.rs
  - http_metrics.rs
- Cargo.toml
- README.md
- - config.rs
  - handlers.rs
  - lib.rs
  - ratelimit.rs
  - sessions.rs
  - state.rs
  - validate.rs
- - config_env.rs
  - consent.rs
- Cargo.toml
- docker-entrypoint.sh
- README.md
- - activation.rs
  - admin.rs
  - bifrost.rs
  - config.rs
  - cookie.rs
  - handlers.rs
  - import.rs
  - invites.rs
  - labels.rs
  - lib.rs
  - oauth.rs
  - pages.rs
  - ratelimit.rs
  - resend.rs
  - seal.rs
  - sessions.rs
  - share.rs
  - state.rs
  - store.rs
  - tenant.rs
  - warden.rs
- - console_auth.rs
  - import_sqlite.rs
  - share_flow.rs
  - signup_flow.rs
  - waitlist_flow.rs
- Cargo.toml
- docker-entrypoint.sh
- README.md
- - search_probe.rs
- - config.rs
  - credentials.rs
  - error.rs
  - lib.rs
  - mem.rs
  - metrics.rs
  - push.rs
  - text.rs
  - tracking.rs
  - types.rs
- - carrier_poll.rs
  - opens_relay.rs
  - push_relay.rs
- Cargo.toml
- - index.html
- - lib.rs
- Cargo.toml
- - lib.rs
  - main.rs
  - server.rs
- Cargo.toml
- README.md
- - lib.rs
- Cargo.toml
- - auth.rs
  - config.rs
  - handlers.rs
  - jwt.rs
  - lib.rs
  - opens.rs
  - ratelimit.rs
  - state.rs
- - config_env.rs
  - fixture_test_key.p8
  - fixture_test_key.pub.pem
  - opens.rs
  - push.rs
  - ratelimit.rs
- Cargo.toml
- docker-entrypoint.sh
- README.md
- - app.rs
  - input.rs
  - main.rs
  - ui.rs
- Cargo.toml
- README.md
- - auth.rs
  - cluster.rs
  - config.rs
  - devices.rs
  - drift.rs
  - handlers.rs
  - identity.rs
  - lib.rs
  - objects.rs
  - pair.rs
  - provision.rs
  - ratelimit.rs
  - testing.rs
  - validate.rs
- Cargo.toml
- README.md
- Cargo.toml
- docker-entrypoint.sh
- Dockerfile
- README.md
.dockerignore
.gitignore
AUTH-FINDINGS.md
Cargo.lock
Cargo.toml
CLAUDE.md
Dockerfile
Dockerfile.bifrost
Dockerfile.blackbox
Dockerfile.broker
Dockerfile.control
Dockerfile.grafana
Dockerfile.prometheus
Dockerfile.warden
LICENSE
ONBOARDING-FINDINGS.md
railway.bifrost.toml
railway.blackbox.toml
railway.control.toml
railway.grafana.toml
railway.prometheus.toml
railway.toml
README.md
rust-toolchain.toml

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Local-first email intelligence for your AI agent.**

squelch reads your Gmail (read-only), decides what actually deserves attention, catches bills and deadlines, and serves that intelligence over MCP to an agent you already run. Your agent never holds your Gmail credential and never gets raw access to your mailbox.

[![release](https://github.com/braelyn-ai/squelch/actions/workflows/release-daemon.yml/badge.svg)](https://github.com/braelyn-ai/squelch/actions/workflows/release-daemon.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/braelyn-ai/squelch/main/LICENSE)
[![rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://raw.githubusercontent.com/braelyn-ai/squelch/main/Cargo.toml)
[![container](https://img.shields.io/badge/ghcr.io-braelyn--ai%2Fsquelchd-2496ED.svg)](https://raw.githubusercontent.com/braelyn-ai/squelch/main/deploy/DOCKER.md)

[Quickstart](#quickstart) ·
[How it works](#how-it-works) ·
[Agent door](#the-agent-door) ·
[Passband](#passband-the-client) ·
[Security](#security-posture) ·
[Docs](#docs)

</div>

---

The name comes from the radio control that mutes everything below a signal threshold. Same idea here: noise stays below the squelch line, signal (the passband) comes through.

## Features

|     |     |
| --- | --- |
| 🚪 **Two doors, one daemon** | Agents get `/mcp`: ranked reads, no send/archive/delete. Humans get `/client`: bearer-authed search, threads, rules, and gated actions. |
| 🔐 **Sealed auth mail** | 2FA codes, password resets, and login alerts are sealed at ingest. They never reach an LLM, an MCP response, or a list endpoint. |
| ⚖️ **Deterministic first, models second** | Seal detection, then your sender rules, then heuristics. LLMs only refine. |
| 💬 **Natural-language sender rules** | "only tell me about school closures" is a rule. Your words are passed to the model verbatim, in either polarity. |
| 📅 **Bills, deadlines, shipments** | Extracted during triage and queryable as first-class tools. |
| 🖥️ **Native clients** | Passband for macOS and iOS over the human door, a no-JavaScript console your own daemon serves at `/console`, and a ratatui TUI for the box itself. |
| 🤖 **An assistant inside the app** | Passband carries its own agent — your key on self-host, a daemon-held one on hosted. It reads through the human door, so sealed mail is absent from it too, and it parks on a tap before anything writes. |
| 📬 **Opt-in read receipts** | Per-send open tracking whose records live in your daemon, not on shared infrastructure. |
| 🐳 **Self-host in one compose file** | Prebuilt multi-arch images on GHCR. No Rust toolchain on the box. |

## How it works

```mermaid
flowchart LR
 G["Gmail REST API (gmail.readonly)"] -->|history.list poll| D[squelchd]
 D --> S[(SQLite)]
 S --> T["triage seal ➜ rules ➜ 2-stage LLM"]
 T --> M["/mcp agent door"]
 T --> C["/client human door"]
 M --> A["your agent"]
 C --> P["Passband (macOS · iOS) /console · TUI"]
```

- **Sync**: polls Gmail every 5s with a read-only token. Sent mail seeds a "people I know" contact list, the strongest cheap triage signal.
- **Triage**: seal detection runs before anything else, so auth mail never reaches any LLM. Everything else gets a real model verdict: heuristics (bills, known contacts, alerts, newsletters, cold sales) write provisional seed values at ingest, then Stage-1 (default `claude-opus-5` at low effort) scores importance, tier, deadline, category, and a one-liner with a per-property "why". Those heuristics never stand as the answer unless the API is unreachable, and they never fire a notification on their own; what they do instead is act as a witness, because a model verdict that contradicts them is one of the strongest signals that a row needs a second look.
- **Escalation**: a router, not the model's own confidence, decides what gets that second look. It reads the settled verdict plus facts the model cannot see: what the deterministic detectors found, whether you have corrected this sender before, and where the score fell against the surface line. Stage-2 runs the *same* model at `xhigh` effort with more context (why it was flagged, the sender's track record, the rest of the thread) — escalation buys thinking and information, not a bigger brain. Your squelch/surface rules still settle visibility outright, applied over the verdict rather than instead of it.
- **Re-triage**: relevance expires. Alongside each verdict the model lists dates to look again ("this reservation is dead the morning after"), anything with a deadline schedules itself regardless, and anything sitting unactioned in the standing band gets swept. Verdicts you have corrected by hand are never re-evaluated. Every model pass also has an age horizon (7 days for Stage-1, 14 for Stage-2) so a fresh install cannot spend a day's cap on a decade of backlog, and a re-triage you ask for by hand outranks that horizon for 24 hours and jumps the queue ahead of the backlog: asking is the one thing the cutoff exists to wait for.
- Each stage has its own daily budget caps and cost ledger; no API key or an exhausted budget just means rows keep their heuristic values.
- **Two doors**: agents connect to `/mcp` and get ranked summaries, and they cannot send, archive, delete, or see auth-related mail. Your own clients connect to `/client` with a bearer token and get search, threads, sender rules, the sitrep lifecycle, and gated actions (archive, label, send) backed by a separate write-scoped credential that only the action handlers can load.

## Quickstart

Let us run it for you: [passband.app](https://passband.app)

Our hosted version is currently in alpha. Please join the waitlist.

The Mac client is the download on that page, or `brew install --cask
braelyn-ai/tap/passband`. It is signed, notarized, and updates itself, so the download
is the last one you have to think about; the iOS client ships through TestFlight. The
same client talks to a hosted daemon and a self-hosted one — it only ever knows a URL
and a token.

## Self-Hosting

Email is sensitive. Don't want to give it to us? Self-hosting has first-class support. Everything available in the hosted version is available to self-host.

> 🐳 **Prefer Docker?** Prebuilt images live at `ghcr.io/braelyn-ai/squelchd` (amd64 + arm64). [`deploy/DOCKER.md`](deploy/DOCKER.md) is the compose-file-and-env-vars path, no toolchain needed. And [`docs/GETTING-STARTED.md`](docs/GETTING-STARTED.md) walks a full setup end to end: daemon in Docker on a NAS, Passband on a Mac.

### 1. Create a Google Cloud OAuth client

1. Go to [console.cloud.google.com](https://console.cloud.google.com), create a project
2. Enable the **Gmail API** for the project
3. Configure the OAuth consent screen (External), add yourself as a test user
4. Create credentials: OAuth client ID, type **Desktop app**

### 2. Configure

Create a `.env` in the repo root (it is gitignored). Generate the API token
once, into the file — if you write the `$(...)` into `.env` itself, every
`source` mints a fresh token and yesterday's clients all start seeing 401:

```sh
cat > .env <<EOF
SQUELCH_CLIENT_ID=<your client id>
SQUELCH_CLIENT_SECRET=<your client secret>
SQUELCH_ACCOUNT_EMAIL=you@gmail.com
SQUELCH_API_TOKEN=$(openssl rand -hex 32)
EOF
```

`SQUELCH_API_TOKEN` is an optional master password for the human door. Without
it the door still serves and 401s everything until a device has its own token:
`squelchd pair` prints a short code (and a `passband://pair` link) that Passband
trades for one, and `squelchd token list` / `squelchd token revoke <id>` manage
them one device at a time. Keep a master token if you want a way in that survives
revoking every device.

Optional: `SQUELCH_DB_PATH` (default `~/.local/share/squelch/squelch.db`), `SQUELCH_BIND` (default `127.0.0.1:8848`), `SQUELCH_POLL_SECS` (default 45), `SQUELCH_MCP_ALLOWED_HOSTS` if you front the server with a proxy like `tailscale serve`, `SQUELCH_CRED_BACKEND` (`keyring` on macOS, `file` on Linux) and `SQUELCH_CREDENTIALS_PATH` (default `~/.config/squelch/credentials.json`) for the file backend.

`SQUELCH_METRICS_BIND` (unset by default, e.g. `127.0.0.1:9464`) opens a second listener serving Prometheus text metrics at `/metrics`: sync timestamps, Gmail error counts, LLM spend, store sizes. **That listener is plaintext and unauthenticated**, by design, because a scrape credential in a Prometheus config is its own problem. Bind it to loopback or to a private interface and let your collector reach it there; never bind it to a public one. Leave it unset and the daemon opens no such port at all.

The same listener answers `GET /healthz`, for an orchestrator that needs to know when this daemon is actually serving: `200 ok` once the sync engine is running and the embedder init has settled, `503` before that and `503` again if either stops. Two states and one word, deliberately — anything that reaches the port reads the answer, so it says nothing about the mailbox behind it. The daemon binds its doors before it finishes starting, so that a first-run model download cannot make them unreachable, which is exactly why "the port accepts" is not the same question.

To turn on LLM triage, provide an API key: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or the explicit `SQUELCH_STAGE2_API_KEY` (provider sniffed from the key prefix). Both stages share the one key; without a key, triage runs heuristic-only. Models, prices, and budgets are tunable under `[stage1]` / `[stage2]` in `~/.config/squelch/config.toml` or via `SQUELCH_STAGE1_*` / `SQUELCH_STAGE2_*` env vars, and the daily caps can be changed at runtime (no restart) from Passband's Settings.

### 3. Authorize and run

```sh
set -a; source .env; set +a

cargo run --bin squelchd -- auth     # one-time browser consent; token -> macOS keyring, mode-0600 JSON file on Linux
cargo run --bin squelchd -- serve    # sync + both doors on one port
```

Write scopes are a separate, later opt-in: `squelchd auth --write` (only needed for archive/send actions). It runs two consent flows, minting the write credential and re-minting the read one, so the two slots stay in sync.

<details>
<summary>Headless box (SSH port-forward)</summary>

Use `squelchd auth --headless` and forward the consent port: `ssh -L 8847:127.0.0.1:8847 yourbox`.

</details>

<details>
<summary>No browser can reach the box at all (docker on a NAS, a VPS): export/import</summary>

Consent runs on a machine that *does* have a browser, and the resulting token moves to the daemon:

```sh
# on your laptop, where the browser is:
squelchd auth --export --out cred.txt          # add --write for both credentials

# on the daemon's host:
docker exec -i squelchd squelchd auth --import < cred.txt
```

`--export` runs the normal consent flow and stores nothing. `--out` writes the one line it produces as mode 0600, which a `> cred.txt` redirect cannot do: that takes your umask, and the file is a live refresh token. (Without `--out` the line goes to stdout and everything else to stderr, so `umask 077; squelchd auth --export > cred.txt` also works.)

`--import` reads that line from stdin only (never an argument: arguments show up in `ps` and in shell history). Before it stores anything, it refreshes every credential in the blob against this host's OAuth client, asks Google which mailbox the result opens, and checks the granted scopes cover what each entry's slot requires — a floor, not an exact match, because Google unions grants across one project's consents. A blob is unsigned JSON, so what it says about itself is a claim; a wrong mailbox or a token that cannot do its slot's job is refused, and one bad entry stores none of them. What keeps the two credentials apart is which code path may load each slot, not a capability difference in the tokens. Delete `cred.txt` once it is in.

Both machines must use the same `SQUELCH_CLIENT_ID` and `SQUELCH_CLIENT_SECRET`. A refresh token is bound to the OAuth client that minted it, not to a host, so it travels fine between machines and not at all between clients.

If the laptop side is itself the published container image, run the export inside it with `-p 8847:8847` and add `--expose-consent-listener`: a listener on the container's own `127.0.0.1` is unreachable from your browser. That opens the port on every interface for the length of one consent, so it is opt-in.

There is a `--broker` flag that moves the code instead of the token, and it is a dead end you should not spend time on: Google only lets a Desktop-type OAuth client redirect to loopback, so a consent relay can never receive the code. [docs/BROKER.md](docs/BROKER.md) has the details and the replacement.

</details>

### 4. Connect an agent

Point any MCP client at the streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "squelch": { "type": "http", "url": "http://127.0.0.1:8848/mcp" }
  }
}
```

To reach it from another machine on a tailnet: `tailscale serve --bg 8848`, set `SQUELCH_MCP_ALLOWED_HOSTS=<your-host>.ts.net`, and use the `https://<your-host>.ts.net/mcp` URL.

### 5. Browse locally

Your daemon serves its own console at `http://127.0.0.1:8848/console`: server-rendered
HTML with no JavaScript and no external asset, for seeing what this mailbox is doing
and managing the devices allowed to reach it. Signing in is the same `squelchd pair`
code an app claims, so the browser is simply one more paired device and
`squelchd token revoke <id>` ends its session like any other.

For a terminal on the box itself:

```sh
cargo run --bin squelch-tui    # ranked digest, squelch line, sender rule tuning
```

## The agent door

Seven tools, no mailbox writes, sealed mail structurally absent:

| Tool | What it returns |
|---|---|
| `get_inbox_updates` | ranked updates since a timestamp, with importance, a one-line "why", and the sender's standing instruction |
| `get_thread` | a full thread by id, with the standing instructions covering the people in it |
| `search_mail` | full-text search over synced mail |
| `get_deadlines` | upcoming deadlines extracted during triage |
| `get_shipments` | package tracking status |
| `set_sender_rule` | squelch/surface/filter a sender, natural-language `want_text` supported |
| `list_sender_rules` | the current rule set |

Sender rules are the one thing an agent can write, and they only shape triage inside squelch's own database. Nothing an agent does can touch your actual mailbox.

A rule's `want_text` is a standing instruction in your own words — "the statement total, not the minimum payment" — and it is delivered **with the mail it applies to**, not just stored. Triage has read it since rules shipped; now the agent writing the sentence you read gets it too, resolved against the sender's address at the moment it answers, so a rule you write today applies to mail that arrived last week. The rule's verdict deliberately stays behind: surface/squelch/filtered has already been spent on the update's tier, and a bill outranks a squelch rule on purpose, so what crosses is the instruction and never the judgment.

## Passband, the client

[Download here](https://passband.app)

Passband is the native client over the human door: the sitrep, threaded reading with a rail and a minimap, compose with live markdown that sends as proper multipart HTML, contacts autocomplete, inline images with the system's own Quick Look panel for everything else, per-send read-receipt opt-in, sender rule tuning, sealed-mail reveal with an audit trail, and budget/usage dashboards. Released builds update themselves over an EdDSA-signed appcast, and a new version arrives as a card inside the app with one button on it rather than a second window asking the same question twice.

One daemon is one mailbox, so several mailboxes are several daemons: the app keeps an index of them, switches with ⌘1–⌘9, and keeps a background ear on the ones you are not looking at, which is what lets an auth code from an account you left in a background tab still reach you.

It also carries its own agent. On self-host you bring your own Anthropic key and the app calls the provider directly; on hosted, the daemon relays the same request with a credential the app never sees. Either way the assistant reads through the human door, so sealed mail is structurally absent from it, and every mutating tool parks on a confirm card before it runs.

**iOS** is the same client in four tabs (sitrep, records, mail, search) plus the agent, built from the same source tree as a second XcodeGen target, and shipped through TestFlight.

```sh
cd passband
./build.sh          # debug
./build.sh run      # build and launch
./build.sh release  # optimized
```

No Xcode needed for a Mac build, `swiftc` does the work. The iOS target does need it: run `xcodegen generate` (which is also what teaches the project about a newly added `.swift` file) and build `PassbandiOS` from Xcode, or `./release-ios.sh` for a TestFlight build.

<details>
<summary>Code signing notes (why local builds want a Developer ID cert)</summary>

Local builds sign with whatever `Developer ID Application` certificate is in the keychain, falling back to ad-hoc when there is none. That is deliberate and worth knowing about: keychain ACLs match on a bundle's *designated requirement*, and an ad-hoc signature's requirement is a hash of the build itself, so every recompile looks like a new app and re-prompts for access to the stored credentials. A Developer ID requirement is keyed to the team and stays constant across rebuilds. Local builds also get `get-task-allow` so a debugger can attach; it is injected into a throwaway copy of the entitlements and never reaches a release, which the notary service would reject for carrying it.

`VERSION` holds the user-facing version; the build number is the git commit count, so it only ever increases. Override either with `MARKETING_VERSION=` / `BUILD_NUMBER=`.

</details>

<details>
<summary>Releases (a tag, and CI does the rest)</summary>

A Mac release is a tag. Bump `passband/VERSION` and its mirror in `project.yml`, commit, then push `passband-mac-X.Y.Z`: the workflow refuses a tag the two files do not agree on, then builds, signs with the Developer ID, notarizes, staples, publishes the GitHub release, regenerates the signed Sparkle appcast, and bumps the Homebrew cask. iOS is the same shape under `passband-ios-*`, and the daemon owns `daemon-*`; the three namespaces never overlap.

`./release.sh` (`--dry` to rehearse) cuts the identical release from this machine when CI cannot, and `./build-release.sh` is just its signing step: Developer ID signature, hardened runtime, notarization, stapled ticket. Ad-hoc builds from `build.sh` get none of that, and Gatekeeper blocks them everywhere but the machine that built them.

The prerequisites, the five repo secrets, and what to do about a bad release that already shipped: [`passband/RELEASING.md`](passband/RELEASING.md) for this app, [`docs/RELEASING.md`](docs/RELEASING.md) for all four surfaces at once.

</details>

## Workspace layout

| Component | What it is |
|---|---|
| `squelch-core` | types, SQLite store, seal detection, two-stage triage (rules + LLM), Gmail sync, OAuth |
| [`squelch-mcp`](squelch-mcp/README.md) | the agent door (rmcp server, stdio or HTTP) |
| [`squelch-api`](squelch-api/README.md) | the human door (axum, bearer auth, actions, audit log) and the `/console` pages |
| `squelch-httpauth` | shared HTTP auth layer used by both doors |
| `squelch-ratelimit` | the per-IP token buckets the public-facing services share |
| [`squelchd`](squelchd/README.md) | the daemon binary: `auth`, `run`, `serve`, `pair`, `token` |
| [`squelch-tui`](squelch-tui/README.md) | local ratatui viewer for setup and debugging |
| `passband` | Passband, the native client: a macOS target and an iOS one over one source tree |
| [`squelch-relay`](squelch-relay/README.md) | blind APNs ping relay for the iOS app |
| [`squelch-broker`](squelch-broker/README.md) | consent relay — built but not deployed; see [docs/BROKER.md](docs/BROKER.md) |
| [`squelch-control`](squelch-control/README.md) | hosted only: waitlist, invite codes, signup, and the console's Google hop |
| [`squelch-warden`](squelch-warden/README.md) | hosted only: the in-cluster provisioner that runs one daemon per tenant |

## Security posture

- The sync credential is requested as `gmail.readonly`, and what holds the line is structural: sync and triage can only load the Read slot, ever. The write credential (`gmail.modify` + `gmail.send`) lives in a separate slot that is only reachable from the human door's action handlers, which require an explicit confirm flag, run an outbound secret scan on sends, and audit every attempt. (Google unions granted scopes across one project's consents, so the token in the Read slot may *carry* more than readonly after `auth --write` — which door can load which slot is the enforcement, not the token's scope list.)
- Auth emails (2FA codes, password resets, login alerts) are sealed at ingest and never appear in any MCP response, any LLM call, or any list endpoint. Revealing one takes an explicit authenticated request and writes an audit row.
- Email content is treated as untrusted input everywhere. Tokens never appear in logs.
- The console introduces no new credential type: its session cookie *is* an ordinary device token, HttpOnly and verified by the same check the bearer path runs, so a browser is one more paired device and `squelchd token revoke <id>` ends its session like any other. The pages ship no JavaScript and no external asset, and say so to the browser with a `default-src 'none'` CSP.
- Read tracking on mail you send is off by default and opt-in per send; the record lives in your daemon, never on shared infrastructure. Self-hosted deployments serve the pixel themselves and need no relay.

The full model is in [docs/SECURITY.md](docs/SECURITY.md).

## Docs

| Doc | Covers |
|---|---|
| [GETTING-STARTED.md](docs/GETTING-STARTED.md) | end-to-end walkthrough: daemon in Docker on a NAS, Passband on a Mac |
| [deploy/DOCKER.md](deploy/DOCKER.md) | prebuilt GHCR images, compose file, env-var config |
| [deploy/DEPLOY.md](deploy/DEPLOY.md) | deployment notes for a Linux server |
| [SECURITY.md](docs/SECURITY.md) | the threat model and the two-door design |
| [SHIPMENTS.md](docs/SHIPMENTS.md) | package tracking: BYOK carrier polling and how a package is identified |
| [TRACKING.md](docs/TRACKING.md) | opt-in read receipts, self-hosted pixel |
| [BROKER.md](docs/BROKER.md) | why the consent broker is a dead end, and what replaced it |
| [RELEASING.md](docs/RELEASING.md) | the four release surfaces, their tags, and what each one gates on |
| [HOSTED.md](docs/HOSTED.md) | the hosted tier: what was decided, why, and what self-host keeps |

## License

squelch

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

squelch

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README