Skip to content
Menestrel

Deploy to your own server (Menestrel agent)

The Menestrel agent is a small open source daemon (MIT) that runs on your own server. When you publish, Menestrel sends it a signed ping; the agent pulls your Git repository, rebuilds the static site, health-checks the output and swaps it live atomically. Your hosting never leaves your machine, and the timeline in Menestrel still reads “Live at 14:32”.

Requirements, honestly: Node 22 or newer, git, about 2 GB of free RAM for an Astro build with local image processing (prefer the Menestrel image pipeline otherwise), outbound access to your Git host and the Menestrel API, and an HTTPS path to the agent (a reverse proxy in front of it).

  1. Create the target in Menestrel

    In your site settings, open Deployment and connect a host of type “Your server (Menestrel agent)”. Enter the public URL the agent will be reachable at, for example https://vps.example.com/menestrel-agent. Menestrel generates the shared secret (agt_...) and shows it once: copy it now.

  2. Install the agent on the server

    Terminal window
    npm install -g @menestrel/agent
    sudo menestrel-agent init

    init checks the prerequisites, creates the menestrel-agent system user, asks for your repository, branch, build command and the secret from step 1, then writes /etc/menestrel-agent/<site>.toml (mode 600) and the systemd unit. It also prints the Caddy and nginx snippets for the reverse proxy.

  3. Start and test

    Terminal window
    sudo systemctl enable --now menestrel-agent-<site>

    Back in Menestrel, use the “Test (dry-run build)” button on the target: the agent runs a full build without touching the live site and reports the reference duration.

Day two

Section titled “Day two”
  • The queue coalesces: publishes arriving mid-build collapse into exactly one final rebuild.
  • A broken build never goes live: the output is health-checked before the atomic swap, and the previous releases (5 by default) stay on disk.
  • Local rollback, for when even the rebuild is broken: menestrel-agent rollback re-points the live release; menestrel-agent status shows the current one. The normal rollback stays “republish a previous version” from the admin.
  • After 3 failed builds the target pauses and the admins get an email; re-enable it from the site settings.

Security in one paragraph: the agent exposes exactly two endpoints (POST /deploy, signed, and a deliberately uninformative GET /health), never receives code or commands over the wire, only pulls the repository written in its local config, verifies every request with an HMAC signature and a 5 minute replay window, and only calls back the API address pinned in that same config.