Superlocal

Desktop-focused email, backed by a provider-agnostic Inbox SDK. Bring your mailboxes into one unified inbox while keeping their identities, credentials, and provider capabilities separate.

Run locally

Requires Bun 1.4+.

1. Install dependencies:

   bun --no-env-file install
   

2. Start the app:

    bun --no-env-file run start
   

3. Open http://localhost:5178.

The first run starts two fictional mailboxes through the real Inbox SDK. No provider credentials, OAuth setup, OpenCan, or machine-specific services are needed. Ctrl-C stops both the client and local host.

start builds and serves the optimized client locally. Use bun --no-env-file run dev for hot-reloading development; development-mode React diagnostics add overhead on large mailboxes. Both commands keep the same local-only host, sessions, and provider configuration.

Docker with persistent storage

Run docker compose up -d --build --wait, then open http://localhost:5178. The image contains the built app, not your configuration or mail. On first run, the app creates a fictional installation in the named volume superlocal-state:

/persist/superlocal.local.json
/persist/data/mock/             # Fictional mail, databases and generated keys
/persist/data/real/             # Created when real mode is selected

Each mode keeps host.sqlite, its mail database(s), runtime-secrets.json and SQLite journals together. Configure real providers in the retained config as described below; never replace its instance ID or keys during an update. Google OAuth client secrets can be supplied through the same explicit environment variables used locally. They are runtime inputs, not image build arguments.

After updating the checkout, run docker compose up -d --build --wait again. Compose replaces the app container and reattaches the same volume. A hosting platform's Git-triggered redeploy must likewise retain this volume at /persist; the GitHub workflow below publishes images but does not restart a remote host. docker compose down retains the volume; do not use down -v or delete the volume when updating. Back up config, databases and keys together with the app stopped. Existing Mac installations are not imported automatically.

Set SUPERLOCAL_DOCKER_PORT to use another local port and SUPERLOCAL_VOLUME_NAME only for a deliberately separate installation. Do not run two app instances on the same volume. Named volumes are initialized for the image's non-root bun user; a bind-mount replacement must be owned by that user's UID/GID (1000:1000), with private directories and 0600 config/key files.

Only the web port is published, on host loopback. The backend stays inside the container. Public hosting/authentication is unchanged. Browser-local settings and recovery copies remain in the browser; this volume preserves server state.

Published images

Pushes to main build and publish Linux AMD64 and ARM64 images at ghcr.io/r44vc0rp/superlocal:latest. The workflow can also be run manually on main. It uses GitHub's built-in GITHUB_TOKEN with package-write permission; no Docker Hub account or registry password is needed. Images also receive a sha-<full-commit-sha> tag, and the workflow records the digest for pinned deploys.

To run or update the published image without building it locally:

SUPERLOCAL_IMAGE=ghcr.io/r44vc0rp/superlocal:latest \
  docker compose up -d --no-build --pull always --wait

The same superlocal-state volume is retained. Set SUPERLOCAL_IMAGE to a commit-specific tag or digest to select a particular version; database migrations may still limit downgrades. Other container hosts can use the same image and mount /persist without Compose. Server restarts/webhooks remain host-specific.

GHCR packages initially default to private, even for a public repository. The package owner must set its visibility to public once for anonymous pulls. A private package instead requires a GitHub token with read:packages on the deployment host. This workflow never includes runtime mail, keys or config in the image, and does not change the application's local-only authentication.

One inbox, separate mailboxes

• Unified by default. Every added mailbox joins the unified view. Choose a smaller selection in Settings → Mailboxes when you want one.
• Keyboard-first navigation. Ctrl+0 opens Unified inbox; Ctrl+1–9 open your ordered pinned mailboxes.
• Many mailboxes, one view. Search and bulk-select provider mailboxes instead of creating hundreds of permanent tabs. Adding views triggers one initial sync per source, not one per domain.
• Source-aware actions. Overlapping views share one canonical message. Replies retain the correct sender; Done and snooze remain local mailbox workflows rather than upstream labels.
• Isolated email rendering. Received HTML stays in a script-disabled iframe. The SDK sanitizes content and serves eligible remote media through authenticated routes; image settings and known-tracker blocking remain authoritative.

See the reader and mailbox settings

Reading a conversation

Choosing mailboxes and shortcuts

The screenshots use only the included fictional mock data, at a slightly enlarged viewing scale.

Providers and roadmap

The goal is ready-to-connect providers out of the box: choose a service, complete its authorization, and select mailboxes in the same UI. You will still need the provider account, required permissions, and any domain/DNS setup that service requires.

Resend and Cloudflare support email workflows, but that does not automatically give them traditional IMAP folders or native read flags. Their adapters should expose real capabilities while the SDK supplies reusable local workflows.

What we are working toward

1. Less setup outside the app. Provider presets, guided authorization, connection checks, and useful reconnect errors instead of routine configuration-file editing.
2. More interchangeable providers. Finish IMAP/iCloud support, then add Resend and Cloudflare without introducing separate frontend mail APIs.
3. Better large-inbox progress. Keep cached mail usable while imports run, show meaningful progress and partial failures, and extend paging as mailbox collections grow.
4. Personalized Important / Other. Add optional per-user learning from explicit corrections, with reversible feedback and conservative handling of uncertain mail.

For current unified-inbox decisions, import limits, and open product questions, see unified-inbox-decisions.md. Apple's separate OAuth opportunity is recorded in apple-provider.ind.

Architecture

Client → Inbox SDK APIs → provider adapters

The SDK currently runs on Bun and SQLite. The included host is local-only; public deployment authentication and team access controls are not implemented.

Connect real providers

The current Gmail and Inbound connectors use the local host configuration:

1. Stop the app and open the generated, git-ignored superlocal.local.json.
2. Set mode to real and enable providers.gmail.enabled and/or providers.inbound.enabled.
3. For Gmail, configure the host's Google OAuth web client. Register http://localhost:5178/v1/oauth/google/callback for the default local setup. Google does not accept .local redirect domains; use the configured localhost origin for local authorization.
4. Restart the app and open Settings → Add Accounts. Inbound takes an API key, then offers discovered mailboxes. Gmail uses the host-managed OAuth flow.
5. Use Settings → Mailboxes to choose unified inclusion and pinned shortcuts.

Provider credentials are submitted to the host, encrypted per connection by the SDK, and not returned by the mail APIs. Mock and real modes stay separate. The Gmail OAuth defaults reference SUPERLOCAL_GOOGLE_CLIENT_ID and SUPERLOCAL_GOOGLE_CLIENT_SECRET; export them explicitly, or configure the corresponding providers.gmail.oauth values as private strings or { "env": "YOUR_VARIABLE_NAME" } references. No SDK .env file or unrelated ambient credentials are imported.

Real connections default to normal mail access (allowProviderWrites.real: true). For an optional read-only host, set it to false; Gmail can use https://www.googleapis.com/auth/gmail.readonly with openid and email rather than modify/send scopes. Reauthorize old read-only grants before sending or modifying mail. Provider capabilities and OAuth permissions still determine which native actions are available.

Runtime storage and advanced local configuration

Keep the generated instanceId with its data. Runtime databases, encryption keys, and session keys live outside the checkout:

Platform	Default location
macOS	~/Library/Application Support/superlocal/<instanceId>/
Linux	$XDG_DATA_HOME/superlocal/<instanceId>/, defaulting to ~/.local/share
Windows	%LOCALAPPDATA%/superlocal/<instanceId>/

dataDir can point to another private directory. Back up the whole instance together: missing or mismatched keys fail closed and are never silently regenerated. Old pilot databases and .env.local credentials are not imported automatically.

The launcher serves the client on port 5178 and the SDK host on 8790. web.port, backend.port, web.origin, and web.allowedOrigins control the local addresses. A null web.origin uses http://localhost:<web.port>. An existing OpenCan setup can expose https://super.local; Superlocal does not install or manage OpenCan.

For an isolated run, set SUPERLOCAL_CONFIG to a new configuration path and SUPERLOCAL_DATA_DIR to a separate private directory. The configuration's parent directory must exist. SUPERLOCAL_WEB_PORT, SUPERLOCAL_API_PORT, and SUPERLOCAL_WEB_ORIGIN override addresses. bun --no-env-file run dev:host starts only the backend.

Development

From the repository root:

bun --no-env-file run test:web
INBOX_TEST_LIVE=false bun --no-env-file run test:api
bun --no-env-file run typecheck
bun --no-env-file run build

Live-provider qualification is separate from deterministic tests. Never commit credentials, private configuration, runtime databases, real mail, or private diagnostic captures.