NixOS

Run self-hosted Maple as a NixOS service from the flake in the Maple repository, with its secrets read from files.

The Maple repository is a Nix flake. It packages the released maple binary and ships a NixOS module, services.maple, which runs the same server as the container image under systemd.

Add the module

In your system flake:

{
  inputs.maple.url = "github:MapleTechLabs/maple";

  outputs = { nixpkgs, maple, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        maple.nixosModules.maple
        ./configuration.nix
      ];
    };
  };
}

Then in configuration.nix:

services.maple = {
  enable = true;
  host = "127.0.0.1";
  ingestKeyFile = "/run/secrets/maple-ingest-key";
  accessTokenFile = "/run/secrets/maple-access-token";
};

services.caddy = {
  enable = true;
  virtualHosts."maple.example.com".extraConfig = "reverse_proxy localhost:4318";
};

Each secret file holds one of the two secrets, at least 16 characters. Create them with openssl rand -hex 32, or manage them with sops-nix or agenix. The service reads them through systemd credentials, so they never enter the Nix store. Listening on anything other than loopback requires both files.

Options

Option	Default	Meaning
`host`	`127.0.0.1`	Address to listen on. Use `0.0.0.0` without a proxy on a private network
`port`	`4318`	OTLP ingest, the dashboard and the query API
`advertiseHost`	none	The hostname exporters and browsers use, when it differs from `host`
`openFirewall`	`false`	Open `port` in the firewall
`ingestKeyFile`	none	File holding the ingest key
`accessTokenFile`	none	File holding the access token
`checkpointInterval`	`30m`	How often to refresh the recovery checkpoint, or `off`
`onDirtyStore`	automatic	After an unclean stop: restore the last checkpoint once one exists, start fresh before that (as the image)
`extraArgs`	`[]`	Extra arguments for `maple start`

Telemetry and checkpoints live in /var/lib/maple, owned by the maple system user. Back it up as described in Operations, and run commands that change the store as that user:

sudo -u maple HOME=/var/lib/maple maple checkpoint

Read-only commands such as maple services can run as any user with MAPLE_LOCAL_URL=http://127.0.0.1:4318 and MAPLE_LOCAL_ACCESS_TOKEN set.

Upgrades

The flake follows Maple releases. Run nix flake update maple and rebuild. maple update is disabled in a Nix install. Roll back with your previous generation like any other NixOS change, but note that a store opened by a newer version may refuse to start on an older one.

Without NixOS

nix run github:MapleTechLabs/maple -- start runs Maple Local on any Linux machine with Nix, and on Apple Silicon macOS when the pinned release has a bundle for it. Maple’s license is the FSL, which nixpkgs counts as unfree: the flake’s own package builds without any setting, but the overlays.default overlay needs maple allowed in your allowUnfreePredicate.