mailrust Docs
/
Install

Getting started

Install with an AI agent

Claude Code, Cursor, Codex or any coding agent with shell access can install mailrust on your server for you. It runs the same installer you would and gives you the first-run link at the end.

Paste this into your agent

Replace the server and the domain with yours.

Install mailrust on my server: ssh root@SERVER_IP. The mail address will be mail.example.com, its DNS A record points to the server. Follow https://mailrust.com/docs/getting-started/agent-install.md step by step and give me the first-run link at the end.

Without a domain, say so: mailrust will run behind your web server instead.

Steps for the agent

  1. Check the server. uname -m prints x86_64, systemctl --version works, and you are root (id -u prints 0).
  2. Pick the mode.
    • Nothing listens on ports 80 and 443 (ss -tlnp | grep -E ':(80|443) ' prints nothing) and the person gave a domain whose A record points to this server: HTTPS by itself.
    • nginx, Caddy or a hosting panel already uses those ports: behind the web server.
  3. Install.
    • HTTPS by itself: 
      curl -fsSL https://mailrust.com/install.sh | sh -s -- --domain mail.example.com --email you@example.com
    • Behind the web server: 
      curl -fsSL https://mailrust.com/install.sh | sh
      Then proxy the domain to 127.0.0.1:8420, keeping the Host header and the client's address. Examples for nginx and Caddy: HTTPS and proxies.
  4. Check. systemctl is-active mailrust prints active. curl -fsS -o /dev/null https://mail.example.com/login succeeds (behind a web server, check http://127.0.0.1:8420/login first).
  5. Hand over the first-run link. Run sudo -u mailrust mailrust setup-link and give the link to the person. They open it in the browser and create the administrator: do not open it yourself.

What the agent must not do on its own

  • Change DNS records, open firewall ports or restart other services: ask the person first. With HTTPS by itself, ports 80 and 443 must be open in the firewall (ufw, firewalld, the provider's panel).
  • Install over an existing mailrust without asking: running the installer again updates the program and keeps the data, which is safe, but the person should know.

After the install

If something fails

  • No certificate. The A record does not point here yet, or port 80 is closed. Look at journalctl -u mailrust -n 50.
  • Port already in use. Install behind the web server instead.
  • Anything else: Troubleshooting.