External/tutabridge
1
0
Fork 0
mirror of https://github.com/spartanz51/tutabridge.git synced 2026-06-24 10:54:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

README: end-user install + getting-started

Browse Source 
Add a download-and-run path for non-developers: per-OS install from the
Releases page (desktop app vs CLI binary, with the Gatekeeper / SmartScreen
one-time override each needs), a step-by-step getting-started with the
IMAP/SMTP connection table and Thunderbird / Apple Mail notes, and an
unofficial-&-unsigned disclaimer up top. Reframe the old cargo-centric
sections as 'Build from source', and document that body search covers
downloaded messages while metadata search covers the whole mailbox.
This commit is contained in:
Anthony
2026-06-01 14:44:13 +02:00
parent 3d4ef0efad
commit 17502c829c
1 changed files with 110 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+110 -31
View File
@@ -7,6 +7,12 @@ encryption transparently.
Available as a **CLI** and a **desktop GUI** (Tauri).
> ⚠️ **Unofficial & unsigned.** TutaBridge is an independent project — not
> affiliated with, endorsed by, or supported by Tuta. It logs into your account
> and decrypts your mail locally, outside Tuta's official apps; use it at your
> own risk. The released binaries are **not code-signed**, so macOS and Windows
> warn on first launch — see [Install](#install) for how to get past that.
## Features
- **IMAP + SMTP** servers on localhost (TLS), so any standard mail client works.
@@ -22,6 +28,96 @@ Available as a **CLI** and a **desktop GUI** (Tauri).
encrypted `.eml.enc` files. Subsequent launches load from cache and only fetch
the delta, so the client is usable immediately.
- **Complete mailbox backup** to portable `.eml` files (see below).
- **Full mailbox + search** — the whole account is listed over IMAP and
searchable by subject, sender, date and (full-text) body from your mail client.
## Install
Download the latest build from the [**Releases**](../../releases) page. Every
platform ships two flavours:
- a **desktop app** — a normal double-click GUI, recommended for most people;
- a **CLI binary** — a single executable you run from a terminal, for
headless / server use.
| Platform | Desktop app | CLI binary |
|----------|-------------|------------|
| **macOS** (Apple Silicon) | `TutaBridge_*_universal.dmg` | `tutabridge-macos-arm64` |
| **Windows** (x64) | `TutaBridge_*_x64-setup.exe` (or `.msi`) | `tutabridge-windows-x86_64.exe` |
| **Linux** (x64) | `*.AppImage` / `*.deb` / `*.rpm` | `tutabridge-linux-x86_64` |
Because the binaries aren't signed, each OS needs a one-time nudge to run them:
### macOS
Open the `.dmg` and drag TutaBridge to Applications. On first launch macOS says
the app "cannot be opened because the developer cannot be verified" — **right-click
the app → Open → Open**, which whitelists it permanently. (Plain double-click
won't offer the override.)
### Windows
Run the `.exe` / `.msi`. SmartScreen shows "Windows protected your PC" — click
**More info → Run anyway**.
### Linux
```bash
chmod +x TutaBridge_*_amd64.AppImage && ./TutaBridge_*_amd64.AppImage
# or: sudo dpkg -i TutaBridge_*_amd64.deb (Debian/Ubuntu)
# or: sudo rpm -i TutaBridge-*.x86_64.rpm (Fedora/RHEL)
```
### CLI binary (any OS)
The CLI files have **no extension**, so double-clicking does nothing useful (your
OS may even open them in a text editor). Run them from a terminal:
```bash
chmod +x tutabridge-macos-arm64 # make it executable
xattr -d com.apple.quarantine tutabridge-macos-arm64 # macOS only: clear Gatekeeper
./tutabridge-macos-arm64 # run
```
## Getting started
1. **Launch** the app (or run the CLI). On first run it asks for your Tuta email,
then your password and TOTP code if there's no saved session. The session is
stored in your OS keychain, so later launches resume automatically.
2. TutaBridge shows the **local connection details**. Note the **bridge password** —
this is generated by TutaBridge for local IMAP/SMTP auth and is **not** your
Tuta password. (CLI: it's printed in the logs; GUI: it's on the main screen.)
3. **Add the account** in your mail client with these settings:
| | Server | Port | Security | Auth |
|---|---|---|---|---|
| **IMAP** (incoming) | `127.0.0.1` | `1143` | SSL/TLS | normal password |
| **SMTP** (outgoing) | `127.0.0.1` | `1025` | SSL/TLS | normal password |
- **Username**: your Tuta email
- **Password**: the **bridge password** from step 2
- Accept the **self-signed certificate** when the client prompts.
Keep TutaBridge running while you use your mail client — it's the local server
the client talks to.
### Client-specific notes
- **Thunderbird**: add the account manually (don't let auto-config probe public
servers). Set both servers to `127.0.0.1` with SSL/TLS + "Normal password",
and accept the certificate exception on first connect.
- **Apple Mail**: add an "Other Mail Account", then in *Server Settings* turn
**off** "Automatically manage connection settings" so you can pin host
`127.0.0.1`, the ports above, and TLS.
### Notes & limitations
- **Search** runs in your mail client and is honest: subject / sender / date
search covers the whole mailbox; **body** (full-text) search covers messages
whose body has been **downloaded**. Keep "every message body offline" enabled
(or raise the offline-bodies limit) for full-mailbox body search.
- **Self-signed cert** is expected — the bridge only listens on `127.0.0.1`, so
traffic never leaves your machine.
## Architecture
@@ -43,50 +139,33 @@ Tuta API ←── Syncer (background) ──→ MailStore (in-memory) ←
The storage encryption key is derived from your Tuta session, so there's no extra
password to manage; the cache is encrypted at rest.
## Build
## Build from source
Requires the Rust toolchain and the `tuta-repo` submodule
(`git clone --recursive`, or `git submodule update --init --recursive`).
```bash
cargo build # CLI + core
cargo build -p tutabridge-core # core library only
cargo run # run the CLI from source
./dev.sh # GUI in dev mode (cargo tauri dev)
```
GUI (Tauri + React) in dev mode:
## Files & locations
```bash
./dev.sh # cargo tauri dev — opens the desktop app
```
## Running the bridge
CLI:
```bash
cargo run # or: ./target/debug/tutabridge
```
On first run it prompts for your Tuta email; the session is then stored in the OS
keychain so later launches resume without a password (TOTP is prompted when
required). The bridge prints the local connection details:
```
IMAP server: 127.0.0.1:1143 (SSL/TLS)
SMTP server: 127.0.0.1:1025 (SSL/TLS)
Username: <your tuta email>
Password: <bridge password — shown in the logs / GUI>
```
Point your mail client at those, accept the self-signed certificate, and use the
**bridge password** (not your Tuta password) for IMAP/SMTP auth.
Config and cache live under
`~/Library/Application Support/tutabridge/` (macOS):
Config and cache live under your platform's app-data directory — on macOS
`~/Library/Application Support/tutabridge/`:
```
config.toml account + ports + bridge_password + sync_limit
store.db SQLCipher metadata index
store.db SQLCipher metadata + full-text body index
mails/<id>.eml.enc per-mail encrypted bodies
```
`sync_limit` controls how many recent message **bodies** are kept offline; the
full mailbox is always listed and metadata-searchable regardless. Set it to `0`
(or tick "keep every message body offline" in the GUI) to download everything.
## Backup
Export **every** email to a folder of plain `.eml` files — one file per message,