Airpost
Overview

Building from source

Prerequisites, toolchains and make targets for building Airpost, and running the desktop app against your own engine.

Development happens on macOS and Linux, and the Makefile needs bash. On Windows the engine only has to compile; CI checks that.

Prerequisites

  • git, Python 3, and the Node major version in .node-version (currently 22). make setup checks it.
  • Rust through rustup. rust-toolchain.toml pins the version (1.92, with rustfmt and clippy), and rustup installs it on first use.
  • A C/C++ toolchain and make: the Xcode Command Line Tools on macOS, build-essential on Debian and Ubuntu. npm ci rebuilds better-sqlite3 against Electron.
  • cargo install --locked cargo-deny, for make lint.
  • Docker, optionally. make stack and the engine harness’s Docker tier use it.

Build and run

git clone https://github.com/airpost-mail/airpost.git
cd airpost
make setup     # npm ci for apps/desktop and apps/web, Python deps in .venv, debug Rust builds
make desktop   # the desktop on a sandbox profile in .dev/profile, with the debug engine
make help      # every target

make desktop never touches your real profile. It builds the debug binaries, symlinks airpost-engine, airpost, airpost-mcp and airpost-gateway from target/debug/ into apps/desktop/, and starts the app with --config-dir-path=.dev/profile.

Make targets

TargetDoes
make setupChecks tools, installs JS and Python dependencies, and builds the Rust binaries
make buildDebug builds of airpost-engine, airpost, airpost-mcp, airpost-gateway, airpost-backend and the sample service
make releaseRelease builds of the same
make desktopThe desktop on .dev/profile with the debug engine
make airpost ARGS="status"The debug CLI against the dev desktop’s engine
make webVite dev server for apps/web on an in-browser mock engine
make mailFake IMAP and SMTP accounts without Docker
make stackLocal stack in Docker: fake mail, plus the backend with PROFILE=backend
make stack-down / make stack-resetStop the stack, keeping or deleting its data
make testRust workspace tests and the engine harness quick tier
make test-desktopThe desktop’s Jasmine specs; SPEC=<regex> picks spec files
make lintrustfmt, clippy, cargo deny, the npm licence check, and the desktop and web linters
make gateThe merge gate: lint, tests, release builds, and the harness on a serve engine

Test mail accounts

make mail runs fake IMAP and SMTP servers without Docker, with two accounts: alice@airpost.test and bob@airpost.test, password airpostpass. make stack runs the same servers in Docker. make stack PROFILE=backend also starts the backend at http://127.0.0.1:5101 with the user alice@airpost.test (password airpostpass).

Running the desktop against the engine

The desktop needs an engine binary at apps/desktop/airpost-engine. make desktop links the debug one. To work on the desktop alone:

cd apps/desktop
npm ci
npm start

npm start runs Electron with --dev on the Airpost-dev profile (~/Library/Application Support/Airpost-dev on macOS, ~/.config/Airpost-dev on Linux, %APPDATA%\Airpost-dev on Windows). Pass --config-dir-path to pick another profile, and --lang to force a language:

npm start -- --lang=de

Use npm ci or npm install in apps/desktop, never a bare npm rebuild: that rebuilds better-sqlite3 for Node’s ABI instead of Electron’s. npm run check:native checks it.

While the app is running:

  • Developer > Toggle Developer Tools opens the console, where $m is mailspring-exports.
  • Developer > Reload (Cmd+Option+L on macOS, Ctrl+Alt+L on Linux, Ctrl+Shift+R on Windows) reloads the window and picks up renderer changes. Main-process code (src/main, src/engine/supervisor) needs a restart.
  • Developer > Open Engine Logs opens the folder with the engine’s logs.

To run the CLI against the same engine, use make airpost ARGS="...", which sets AIRPOST_CONFIG_DIR to .dev/profile. See CLI commands.

Desktop scripts

From apps/desktop:

CommandDoes
npm run lintESLint with Prettier, fixing what it can (lint:check only reports)
npm run typechecktsc on src/, plugins/, themes/ and tests/, then the plugin API .d.ts check
npm testAll Jasmine specs; npm test -- --spec-file-pattern='calendar' for a subset
npm run buildProduction build

In apps/web: npm test, npm run lint and npm run typecheck.

Engine harness

make test runs the Rust tests and the harness quick tier (fake servers, no Docker, a few minutes). To run one harness case:

AIRPOST_ENGINE_BIN=target/debug/airpost-engine \
  .venv/bin/python -m pytest apps/engine/test -n 0 -k <name>

python3 -m pytest apps/engine/test --all runs both tiers against every server kind. apps/engine/test/README.md describes the tiers.

Release builds of the engine exit with status 2 unless the lowercased program name contains airpost. Debug builds skip the check.

Debugging the engine

Engine logs, protocol logging, watching deltas, raw RPC calls and running the engine under a debugger are covered in Contributing. The engine’s crates, protocol and task pipeline are in Architecture.

Nix

The repository is a flake that packages airpost, airpost-engine, airpost-mcp and airpost-gateway (with the web client) for x86_64 and aarch64 Linux and macOS. The package is packaging/nix/package.nix.

nix build .#airpost          # from a checkout
nix run github:airpost-mail/airpost -- status

The flake builds the command-line programs only, not the desktop app, and skips the workspace tests (they need the Python harness). For installing released builds, see Installing the CLI.