Docs: add systemd agent service configuration to Polykey CLI guide

[xrissoula]

Description

This PR adds comprehensive documentation for the new systemd-based service management modules introduced in Polykey-CLI PR #138. It includes:

• A detailed guide to configuring and managing the Polykey Agent via systemd, both at the user level (programs module) and system level (services module)
• Context and rationale for introducing these modules
• Usage examples, best practices, and recommended paths for secure credential handling
• Guidance for users to select the appropriate service scope (user vs. system)
• A section for troubleshooting common issues with system service execution

This improves usability, aligns the documentation with the latest features, and sets the foundation for broader secure deployment patterns.

Issues Fixed

• Fixes Polykey-CLI: Documentation for Systemd Service Modules in Polykey-CLI #40

Tasks

• 1. Create new documentation section for systemd agent modules
• 2. Explain differences between programs and services modules
• 3. Document credential file handling, scope selection, and security warnings
• 4. Include service definition examples and command snippets
• 5. Lint and format documentation
• 6. Review and approve with @tegefaulkes, @CMDragonkai, and @aryanjassal @brynblack
• 7. Integrate into Deployment or Usage section of docs site after review

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

[CMCDragonkai]

The proper person to review this isn't me anymore. It's @brynblack. And very importantly you must actually confirm that this is true. Don't just write docs blindly. You have to sanity check what you're writing to confirm that it actually works.

[brynblack]

I think it looks good apart from the instructions, which are more intended for a Linux-agnostic solution, which we don't really have yet. The Polykey Agent is designed primarily at the moment for NixOS.

A few modifications will need to be made to the instructions to clarify the setup for NixOS devices instead of a generic solution. However, the explanations on most things look good.

[brynblack]

This section needs to explain how to set up Polykey using Nix configurations, as that is how the service is actually set up. It does not use .service files. Instead, you configure it like the following, under your home-manager service (at least for the user-level service):

    polykey = {
      enable = true;
      passwordFilePath = "%h/.polykeypass";
      recoveryCodeOutPath = "%h/.polykeyrecovery";
    };

• enable will enable the service.
• passwordFilePath will set the path to grab the vault password from.
• recoveryCodeOutPath will set where to create/grab the recovery code from.

There may need to be an explanation on how Polykey is integrated into a NixOS system.

Take a look at:

• https://github.com/MatrixAI/nixpkgs-matrix-private/blob/staging/README.md
• https://graph.matrix.ai/infrastructure/platforms/user-profile#home-manager
• https://github.com/MatrixAI/Polykey-CLI/blob/staging/modules.nix

[brynblack]

This needs to also be inline with the comment I put above. There is typically no need to manually modify service files under a NixOS system. Unless in the future we make a generic Linux-agnostic version of the Polykey Agent.

But make sure to distinguish the system-level service from the user-level service.

[brynblack]

The service can be customised, but not through service files. It is done using the home-manager configuration, as described in my first comment. Make sure to look at the links I put in it.

[brynblack]

This technically is valid, as services can be manually restarted or analysed if there are problems. However, the daemon-reload part is if you are manually editing the service files, which isn't really needed for NixOS.

Definitely add an explainer on how to check the status of the service, using commands such as:

systemctl status --user polykey.service - checks the status of the service
systemctl restart --user polykey.service - restarts the service

[aryanjassal]

Christina doesn't have a nix system or even a linux system, so she can't run the systemctl commands herself.

This is the output of systemctl status --user polykey.service on my system which you can use for reference.

[aryanj@zenith:~]$ systemctl --user status polykey.service    
● polykey.service - Polykey Agent
     Loaded: loaded (/home/aryanj/.config/systemd/user/polykey.service; enabled; preset: ignored)
     Active: active (running) since Wed 2025-05-21 06:02:43 AEST; 5h 23min ago
 Invocation: 4bb789c30b8d4a398da384b83e7bbb34
    Process: 1007615 ExecStartPre=/nix/store/2y0dbl6jmvcwrv4h549d0pgcm3dl8p4k-polykey-cli-0.18.13/bin/polykey --password-file /home/aryanj/.pkpass --node-path /home/ary>
   Main PID: 1007651 (polykey-agent)
      Tasks: 41 (limit: 37944)
     Memory: 497.7M (peak: 715.4M)
        CPU: 1h 41min 59.690s
     CGroup: /user.slice/user-1000.slice/[email protected]/app.slice/polykey.service
             └─1007651 polykey-agent
May 21 11:24:19 zenith polykey[1007651]: WARN:polykey.PolykeyAgent.task v0q1d4u6t5to0193h3sb26b4810:Failed - Reason: ErrorProviderCall
May 21 11:24:19 zenith polykey[1007651]: WARN:polykey.PolykeyAgent.task v0q1d4u6trdo01efitk10jlvfdg:Failed - Reason: ErrorProviderCall
May 21 11:24:52 zenith polykey[1007651]: WARN:polykey.PolykeyAgent.task v0q1d4unqqho014bu3oicllik2k:Failed - Reason: ErrorProviderCall
May 21 11:25:12 zenith polykey[1007651]: WARN:polykey.PolykeyAgent.task v0q1d4v1h09o0137uglrcpi2dno:Failed - Reason: ErrorProviderCall
(... more logs)

When you run systemctl restart --user polykey.service, it should not give you any output but polykey should be restarted in the background automatically.