InboxQL
Email for engineers — a mailbox you can query. Installed as your own background service, served at
http://localhost:8420.
Read the documentation — the same guides as Help → Documentation in the application.
Install
One command. It verifies the download against the release's published checksums, installs to
~/.iql, and starts InboxQL when you log in.
Then open http://localhost:8420. Works on Apple Silicon and Intel.
xattr -d com.apple.quarantine iql before running it.Then open http://localhost:8420. Release builds are for x86-64; on other architectures, build from source.
The service is a systemd user unit and runs while you are logged in. To have it start at boot
instead: loginctl enable-linger $USER.
In PowerShell:
Then open http://localhost:8420. Release builds are for x86-64.
The service is a task that runs at logon with no window. Unlike macOS and Linux it is not
restarted after a crash — iql service start starts it again.
What it installs, and where
| Path | What it is |
|---|---|
~/.iql/bin/iql | The program — the server and every command. |
~/.iql/settings.json | Which mailbox this machine uses, the address, the models folder.
Every iql command and the service read it. |
~/.iql/data | Your mailbox: the database, its encryption key, attachments, backups. |
~/.iql/models | Model weights, downloaded once per machine when first needed. |
~/.iql/logs/service.log | What the service printed. |
Back up ~/.iql/data — the database and vault.key together. Without the key,
stored account passwords cannot be decrypted.
The service
InboxQL runs as your background service, not a system one: it starts when you log in, stops when you log out, and restarts itself if it crashes (macOS and Linux). It never keeps a laptop awake — closing the lid sleeps the machine and the service with it.
On battery it also holds off the heavy work nobody asked for: the annotation pass that follows a sync waits
for mains power. Set "heavyWorkOnBattery": true in settings.json to let it run anyway.
Updating
It checks the newest release, verifies it, backs up your mailbox, stops the service, replaces the
binary and starts it again. iql update --check only says whether there is one. Running the install
command again does the same thing.
~/.iql/bin/iql. Because
InboxQL is not signed with an Apple Developer ID, macOS forgets that grant whenever the binary is replaced —
re-grant it in System Settings → Privacy & Security → Full Disk Access after each update.A name instead of a port
Give the site an address you can remember:
That records the name and adds two lines to your hosts file. Changing the hosts file needs administrator rights,
so the command tells you exactly what to run next — on macOS and Linux, sudo iql hosts set inboxql.localhost;
on Windows, the same command from a PowerShell opened with “Run as administrator”. Then open
http://inboxql.localhost:8420.
Use a name ending in .localhost or .test. Names ending in .local
are refused: macOS looks those up on the network before reading the hosts file, so every page would wait.
iql hosts remove takes the lines out again.
Uninstalling
That leaves your mailbox in ~/.iql/data. Delete ~/.iql to remove everything, and
iql hosts remove first if you set a name. The installer also added one line to your shell's profile,
marked # added by the InboxQL installer.
When something is wrong
The page does not load
Run iql service status. If it is installed but not running, the reason is at the end of
~/.iql/logs/service.log. The most common one is another program using port 8420: change
"addr" in ~/.iql/settings.json, then iql service restart.
“InboxQL is already running”
One server per mailbox. Typing iql start while the service runs points you at the running one
rather than starting a second copy that would sync the same mail twice.
A command uses a different mailbox than I expected
iql where says which mailbox and why. The order is: --data, then
$INBOXQL_DATA, then ~/.iql/settings.json, then a ./data folder — the last only
when there are no settings.
macOS says the program cannot be opened
It was downloaded through a browser, which marks it as quarantined. Install with the curl command
above, or run xattr -d com.apple.quarantine ~/.iql/bin/iql.
Apple Mail import says it is blocked
Grant Full Disk Access to ~/.iql/bin/iql in System Settings → Privacy & Security, then
iql service restart. After an update, grant it again.