Contents

Running it

Running the API as a Windows service or a systemd unit, and what to set when it sits behind a reverse proxy.

01Running as a service

Windows. From an elevated prompt, prem setup --windows-service registers the API as the service Premagentic under its own virtual account, NT SERVICE\Premagentic. Setup gives that account read access to the application's and the search role's credentials files, the HTTPS settings and the certificate; the owner's credentials stay with administrators. The account is not confined to those files: like any service account it can read what the machine's Users group can read, and on a domain it reaches the network as the computer's own account. Its files default to C:\ProgramData\Premagentic. Start it with sc.exe start PremAgentic.

Setup makes that folder the administrators' own: owned by Administrators, changed by SYSTEM and administrators only, and read by the service. The files the service reads are owned by Administrators, and read by the service and by the account that ran setup, so prem can still be pointed at the application's credentials file from that account. The API checks this before it reads anything: when the folder of its PREM_CREDENTIALS_FILE, that file, or a file beside it that it reads is owned by anyone but administrators, SYSTEM or the account the API runs as, or anyone else may change it, it refuses to start with exit code 2 and a sentence naming the path. Running setup again from an elevated prompt puts it right, or says what stands in the way. Change anything in that folder from an elevated prompt. The folder's rules then reach https.crt too, the certificate clients are given: it is readable by administrators and the service only, so copy it out from an elevated prompt. A profile's golden set is never copied there: prem profile apply copies it to C:\ProgramData\Premagentic-golden-sets, beside it, which the Users group, and so the service, may read.

Linux. deploy/systemd/premagentic-api.service is a unit template: a system account, Type=notify, and the application's four files handed to the service by systemd, so they stay readable by root only. Run setup as root with --credentials-dir /etc/premagentic, then install and enable the unit.

Either way, the API refuses to start, with exit code 2 and a sentence saying what to set, when it has no database configured. The systemd unit has been run on a fresh Ubuntu 24.04 with systemd, and the Windows service on a clean Windows 11 in Windows Sandbox; the bundled database as a service has not yet been run on a clean machine with the rights it needs; see Known state.

02Behind a reverse proxy

Set PREM_TRUSTED_PROXIES to your proxies' addresses or ranges (10.0.0.5, 10.1.0.0/16). The API then believes their X-Forwarded-For and X-Forwarded-Proto, so sign-in over HTTPS that ends at the proxy works and the sign-in throttle counts each client. Nothing else is believed. Do not set ASPNETCORE_FORWARDEDHEADERS_ENABLED; the API refuses to start with it, because it believes anyone. The portal's origin check compares with the host the server sees, so a proxy that rewrites the host needs this setting too.

03Fully local

A deployment that must keep everything on its own hardware, the model included, runs PremAgentic beside a local model server and an MCP chat client. The layout, the chat client's agent registration, the connect snippet and the offline proof of the whole loop are in the repository under deploy/fully-local/ (its README). No model server or chat client is bundled. The offline proof can run the loop a second time with a real local model server (llama.cpp's llama-server with a 0.5B model), which answered from the passages, offline, with nothing connecting out; give it the release tarball and a GGUF model file as PREM_LLAMA_SERVER and PREM_LLAMA_MODEL, and the stand-in's run stays the default. No chat client has been tried against it yet.