Installation

OxiMail is a single Rust binary. Installing it means getting one executable onto a server, placing a config file next to it, and running it as a service. There is no Postfix, no Dovecot, and no web server to install alongside it. This page covers getting OxiMail onto a host. Once it is running, the first boot and setup wizard walks you through DNS, DKIM, TLS, and your first account.

Requirements

Requirement	Value
Operating system	Debian 13 (Trixie)
Privileges	root access
RAM	2 GB minimum (compiling from source needs the headroom)
Disk	10 GB or more free
Network	a domain name and a public IP

OxiMail is built and tested on Debian 13. The installer refuses to run on other distributions or Debian versions, because the build dependencies and library versions are pinned to that target. The setup wizard measures the host again at its first step (distribution, systemd, memory, free space on the volume of /var/lib/oximail, architecture) and shows the result as recommendations: less than 2 GiB of memory, less than 10 GiB free, or a distribution outside those it is tested on (Debian 12 and 13, Ubuntu 24.04) is a warning, never a refusal.

OxiMail is built for Debian 13 only. The installer refuses any other target, and the release path checks that the binary depends on no system crypto, TLS or SQLite library. Build on a Debian 13 machine (a VPS, an LXC container, or a VM).

System dependencies

The build needs a C toolchain and a C compiler for the bundled SQLite; since ADR-148 neither OpenSSL nor SQLCipher is in the dependency graph:

apt install -y build-essential pkg-config clang curl git

You also need a stable Rust toolchain. If rustc is not already present, install it with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
source "$HOME/.cargo/env"

Ports

OxiMail listens on the standard mail and web ports. Open them in your firewall (and any cloud provider security group) before you start the server. The setup wizard checks these and warns you about anything blocked.

Port	Protocol	Purpose
25	TCP	SMTP inbound (receiving mail)
80	TCP	HTTP, used for ACME certificate challenges
443	TCP	HTTPS, serving JMAP and the admin API
587	TCP	SMTP submission (sending mail, authenticated)
465	TCP	SMTPS (implicit-TLS submission)
993	TCP	IMAPS (legacy mail clients)
143	TCP	IMAP with STARTTLS (optional)

Ports 25, 443, and 587 are the minimum for a working mail server. The IMAP ports (143/993) only matter if you enable the legacy feature for IMAP clients. CalDAV and CardDAV are served over the same HTTPS port (443) as JMAP, so they need no extra ports.

Getting the binary

There is no published prebuilt-binary download today: you build OxiMail from source. The build produces a single self-contained executable (around 70 MB) that you copy to the server.

A public source repository and a one-line installer are part of the project roadmap, not something you can rely on yet. Build from source as described below. If you see a one-liner referenced elsewhere, treat it as not-yet-live and verify before depending on it.

Build from source

From a clone of the source tree on a Debian 13 host:

cargo build --release --features passkey,legacy

The two feature flags are:

Flag	Effect	Default
`passkey`	WebAuthn / FIDO2 passwordless authentication	on
`legacy`	IMAP, CalDAV, and CardDAV protocol support	off

Build with --features passkey,legacy if you want legacy mail clients (IMAP) and DAV clients to connect. The release build takes roughly 5 to 15 minutes depending on the machine, and the binary lands at target/release/oximail. A clone also ships an install.sh at the repository root that runs the whole sequence (system packages, Rust, compile, install, then launch the setup wizard) in one go. It is convenient on a fresh VPS, but the manual steps below give you control over each stage.

Placing and running the binary

Install the binary and its directories

Copy the compiled binary into place and create the runtime directories. A dedicated system user keeps the service from running as root:

# system user (no login shell)
useradd --system --shell /sbin/nologin --home-dir /var/lib/oximail oximail

# runtime directories
mkdir -p /etc/oximail/dkim
mkdir -p /var/lib/oximail/blobs
mkdir -p /var/lib/oximail/search
chown -R oximail:oximail /var/lib/oximail /etc/oximail
chmod 700 /etc/oximail/dkim

# the binary
cp target/release/oximail /usr/local/bin/oximail
chmod 755 /usr/local/bin/oximail

Because OxiMail binds to privileged ports (25, 443, 587) but runs as a non-root user, grant the binary the capability to bind low ports instead of running it as root:

setcap 'cap_net_bind_service=+ep' /usr/local/bin/oximail

If setcap is missing, install libcap2-bin first.

Configuration file

OxiMail reads a single TOML config file. The conventional location is /etc/oximail/oximail.toml. The source tree ships a fully commented example at config/oximail.example.toml that you can copy as a starting point:

cp config/oximail.example.toml /etc/oximail/oximail.toml
chown oximail:oximail /etc/oximail/oximail.toml
chmod 600 /etc/oximail/oximail.toml

A minimal production config sets the hostname, the bind addresses, the storage paths, and ACME for TLS:

[server]
hostname = "mail.example.com"
bind = "0.0.0.0:443"

[storage]
sqlite_path = "/var/lib/oximail/data.db"
blob_path = "/var/lib/oximail/blobs"

[smtp]
hostname = "mail.example.com"
bind = "0.0.0.0:25"

[tls]
acme_enabled = true
acme_email = "admin@example.com"

The full reference, including every key and the TOML-plus-database override model, is in Configuration. In most cases you let the setup wizard generate the config rather than writing it by hand. For an unattended install, the source tree also ships config/setup.example.toml, the reference of every key the wizard’s own setup file accepts (oximail setup --config-file), where the admin password, the Cloudflare token and the relay credentials are given by reference (a file or an environment variable), never inline.

Run as a systemd service

Install a systemd unit so OxiMail starts at boot and restarts on failure. Logs go to the journal (run journalctl -u oximail), so there is no log file to rotate. Create /etc/systemd/system/oximail.service:

[Unit]
Description=OxiMail JMAP Mail Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/oximail serve --config /etc/oximail/oximail.toml
Restart=on-failure
RestartSec=5
LimitNOFILE=65535
WorkingDirectory=/var/lib/oximail
StandardOutput=journal
StandardError=journal
SyslogIdentifier=oximail

[Install]
WantedBy=multi-user.target

Then enable and start it:

systemctl daemon-reload
systemctl enable --now oximail
journalctl -u oximail -f

The local validating resolver. The server asks every DNS question to unbound on 127.0.0.1 and believes a DNSSEC answer only once its own probe has proven that resolver. The wizard installs and configures it (host checks). On a hand install, install unbound with its root trust anchor, order oximail.service after unbound.service, and run oximail resolver check: the same probe, with the server stopped or not (exit 0 reliable, 1 unmeasured, 2 unreliable or mute). An unproven resolver does not stop the server from starting, but it believes no DNSSEC answer and holds the mail to DANE domains until the probe passes. For interactive setup the first time, you can run oximail setup directly instead of starting the service. The wizard creates the config, your admin account, and your DKIM keys, then hands off to the service. On a capable terminal it takes the whole screen, and everything it prints is also kept in /var/log/oximail-setup.log; this is the setup’s own log, the server itself still logs to the journal only.

What’s next

First boot and setup wizard — configure DNS, DKIM, TLS, and create your first account.
Configuration — the full TOML reference and the runtime override model.

Get Started

Operator Manual

Developer / JMAP API

Architecture Reference

Reference

Requirements

System dependencies

Ports

Getting the binary

Build from source

Placing and running the binary

Install the binary and its directories

Configuration file

Run as a systemd service

What’s next

​Requirements

​System dependencies

​Ports

​Getting the binary

​Build from source

​Placing and running the binary

​Install the binary and its directories

​Configuration file

​Run as a systemd service

​What’s next

Requirements

System dependencies

Ports

Getting the binary

Build from source

Placing and running the binary

Install the binary and its directories

Configuration file

Run as a systemd service

What’s next