streamline AGENTS.md

add librechat-oci
2026-05-19 00:26:45 +02:00 · 2026-05-19 00:26:20 +02:00
4 changed files with 89 additions and 75 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,7 +1,6 @@
 # AGENTS.md

-This file teaches AI agents how to navigate and work with this NixOS
-configuration repository (`sid.ovh`).
+This file teaches AI agents how to navigate and work with this NixOS configuration repository (`sid.ovh`).

 ---

@ -10,13 +9,12 @@ configuration repository (`sid.ovh`).
 This is a NixOS flake managing three hosts:

 | Host  | IP (Tailscale) | Role                                                 |
-|-------|----------------|---------------------------------------------------|
-| `sid` | `100.64.0.6`   | VPS — reverse proxy, mail, matrix, headscale      |
-| `rx4` | `100.64.0.10`  | Home server — open-webui, forgejo, vaultwarden, … |
+|-------|----------------|------------------------------------------------------|
+| `sid` | `100.64.0.6`   | VPS - reverse proxy, mail, matrix, headscale         |
+| `rx4` | `100.64.0.10`  | Home server - open-webui, forgejo, vaultwarden, etc. |
 | `vde` | `100.64.0.1`   | Desktop / workstation (not in use at the moment)     |

-Deployment is done via `deploy-rs` through a Forgejo CI pipeline
-(`.forgejo/workflows/deploy-configs.yml`).
+Deployment is done via `deploy-rs` through a Forgejo CI pipeline (`.forgejo/workflows/deploy-configs.yml`).

 ---

@ -24,25 +22,20 @@ Deployment is done via `deploy-rs` through a Forgejo CI pipeline

 ### What it is

-`synix` is the owner's **personal NixOS library flake**, hosted at:
+`synix` is a **NixOS library flake**, hosted at:

 ```
 https://git.sid.ovh/sid/synix.git
 ```

 It provides:
- **NixOS modules** (`inputs.synix.nixosModules.*`) — opinionated,
-  reusable service configurations used heavily across all three hosts.
- **Home Manager modules** (`inputs.synix.homeModules.*`) — desktop /
-  user-space configurations (Hyprland, nixvim, waybar, …).
- **Packages** (`inputs.synix.packages.<system>.*`, also accessible via
-  the `synix-packages` overlay as `pkgs.synix.*`) — custom packages not
-  in nixpkgs.
- **Overlays** (`inputs.synix.overlays.*`) — nixpkgs modifications.
- **A utility library** (`inputs.synix.lib` / `lib.utils`) — helper
-  functions such as `mkVirtualHost` and `mkReverseProxyOption`.
- **Templates** — starter flake templates for servers, desktops, VMs, etc.
- **Apps** — convenience scripts (`deploy`, `rebuild`, `install`, …).
+- **NixOS modules** (`inputs.synix.nixosModules.*`): opinionated, reusable service configurations used heavily across all three hosts.
+- **Home Manager modules** (`inputs.synix.homeModules.*`): desktop / user-space configurations (Hyprland, nixvim, waybar, etc.).
+- **Packages** (`inputs.synix.packages.<system>.*`, also accessible via the `synix-packages` overlay as `pkgs.synix.*`): custom packages not in nixpkgs.
+- **Overlays** (`inputs.synix.overlays.*`): nixpkgs modifications.
+- **A utility library** (`inputs.synix.lib` / `lib.utils`): helper functions such as `mkVirtualHost` and `mkReverseProxyOption`.
+- **Templates**: starter flake templates for servers, desktops, VMs, etc.
+- **Apps**: convenience scripts (`deploy`, `rebuild`, `install`, etc.).

 ### How it is consumed in `sid.ovh`

@ -59,16 +52,13 @@ inputs = {
 };
 ```

-The active branch is **`release-25.11`**, aligned with `nixpkgs`
-`nixos-25.11`. A `develop` branch exists for unstable work. A local
-checkout can be used for testing by switching to the `git+file://` URL.
+The active branch is **`release-25.11`**, aligned with `nixpkgs` at `nixos-25.11`. A `develop` branch exists for unstable work. A local checkout can be used for testing by switching to the `git+file://` URL.

 ---

 ## `synix` Module Reference

-All NixOS modules are under `modules/nixos/` in the synix repo and
-exposed as `inputs.synix.nixosModules.<name>`.
+All NixOS modules are under `modules/nixos/` in the synix repo and exposed as `inputs.synix.nixosModules.<name>`.

 ### Infrastructure / base modules

@ -107,18 +97,13 @@ exposed as `inputs.synix.nixosModules.<name>`.

 ### Other available modules (not currently active in `sid.ovh`)

-`audio`, `bluetooth`, `amd`, `nvidia`, `jellyfin`, `i2pd`,
-`ftp-webserver`, `webPage`, `windows-oci`, `librechat-oci`,
-`nostr-relay`, `ollama`, `cifsMount`, `hyprland` (NixOS-level),
-`normalUsers`.
+`audio`, `bluetooth`, `amd`, `nvidia`, `jellyfin`, `i2pd`, `ftp-webserver`, `webPage`, `windows-oci`, `librechat-oci`, `nostr-relay`, `ollama`, `cifsMount`, `hyprland` (NixOS-level), `normalUsers`.

 ---

 ## `synix` Packages (`pkgs.synix.*`)

-Custom packages provided by synix and available via the
-`synix-packages` overlay (applied in
-`modules/nixos/common/overlays.nix`):
+Custom packages provided by synix and available via the `synix-packages` overlay (applied in `modules/nixos/common/overlays.nix`):

 | Package name                  | What it is |
 |-------------------------------|------------|
@ -135,15 +120,13 @@ Custom packages provided by synix and available via the
 | `pkgs.synix.bulk-rename`      | Batch file renaming script |
 | `pkgs.synix.pyman`            | Python man-page helper |

-The full list lives in `pkgs/default.nix` in the synix repo. All
-packages are also accessible as `inputs.synix.packages.<system>.<name>`.
+The full list lives in `pkgs/default.nix` in the synix repo. All packages are also accessible as `inputs.synix.packages.<system>.<name>`.

 ---

 ## `synix` Utility Library (`lib.utils`)

-Exposed as `inputs.synix.lib` and merged into the flake's `lib` in
-`flake.nix`:
+Exposed as `inputs.synix.lib` and merged into the flake's `lib` in `flake.nix`:

 ```nix
 lib = nixpkgs.lib.extend (final: prev: inputs.synix.lib or { });
@ -170,8 +153,7 @@ virtualHosts."${constants.services.forgejo.fqdn}" = mkVirtualHost {

 ## How `synix` Modules Are Imported

-In each host's `default.nix`, synix modules are imported directly from
-the `inputs` special arg:
+In each host's `default.nix`, synix modules are imported directly from the `inputs` special arg:

 ```nix
 # hosts/rx4/default.nix
@ -179,7 +161,7 @@ imports = [
  inputs.synix.nixosModules.common          # base system config
  inputs.synix.nixosModules.device.server   # server profile
  inputs.synix.nixosModules.openssh         # hardened SSH
-  # …service-specific modules in hosts/rx4/services/
+  # service-specific modules in hosts/rx4/services/
 ];
 ```

@ -207,18 +189,15 @@ imports = [
 | `old-stable-packages`   | `nixpkgs-25.05`  | `pkgs.old-stable.*`  |
 | `unstable-packages`     | `nixos-unstable` | `pkgs.unstable.*`    |

-`synix` also supplies its own `modifications` overlay
-(`inputs.synix.overlays.modifications`), merged into the local
-`modifications` overlay in `overlays/default.nix`.
+`synix` also supplies its own `modifications` overlay (`inputs.synix.overlays.modifications`), merged into the local `modifications` overlay in `overlays/default.nix`.

 ---

 ## Centralized Logging Architecture

-All hosts ship their systemd journal to a **central receiver running on
-`sid`** over HTTP using `systemd-journal-remote` / `systemd-journal-upload`.
+All hosts ship their systemd journal to a **central receiver running on `sid`** over HTTP using `systemd-journal-remote` / `systemd-journal-upload`.

-### Receiver (`sid`)
+### Receiver (local host `pc` which is not part of this flake)

 ```nix
 services.journald.remote = {
@ -248,19 +227,15 @@ services.journald.upload = {
 };
 ```

-> **Note:** The upload URL uses `100.64.0.5` — the Tailscale transport
-> IP for `sid` (distinct from the advertised IP `100.64.0.6` in
-> `constants.nix`; verify with `ip addr show tailscale0` on `sid` if
-> queries fail).
+> **Note:** The upload URL uses `100.64.0.5` - the Tailscale transport IP for host `pc` (which is not part of this flake). Verify with `ip addr show tailscale0` and `hostname` if you are on host `pc` with IP `100.64.0.5`.

-This module is applied to **every host** via
-`outputs.nixosModules.common` → `modules/nixos/common/default.nix`.
+This module is applied to **every host** via `outputs.nixosModules.common` -> `modules/nixos/common/default.nix`.

 ---

 ## Querying Remote Journals

-All queries run **on `sid`**, reading from `/var/log/journal/remote/`.
+All queries run **on `pc`**, reading from `/var/log/journal/remote/`.

 ### General pattern

@ -293,13 +268,10 @@ journalctl \
 ```

 This works because:
-1. `rx4` uploads its journal to `sid:19532`.
-2. The receiver stores it under `/var/log/journal/remote/` with
-   `SplitMode=host`, preserving the `_HOSTNAME` field.
+1. `rx4` uploads its journal to `pc:19532`.
+2. The receiver stores it under `/var/log/journal/remote/` with `SplitMode=host`, preserving the `_HOSTNAME` field.
 3. `_HOSTNAME=rx4` narrows to that host's entries.
-4. `SYSTEMD_UNIT=podman-open-webui.service` targets the OCI container
-   unit for Open WebUI (defined in
-   `hosts/rx4/services/open-webui-oci.nix`).
+4. `SYSTEMD_UNIT=podman-open-webui.service` targets the OCI container unit for Open WebUI (defined in `hosts/rx4/services/open-webui-oci.nix`).

 ### Other useful queries

@ -308,30 +280,24 @@ This works because:
 journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 --no-pager -S "1 hour ago"

 # Forgejo on rx4
-journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \
-  SYSTEMD_UNIT=forgejo.service --no-pager -n 50
+journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=forgejo.service --no-pager -n 50

 # Vaultwarden on rx4
-journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \
-  SYSTEMD_UNIT=vaultwarden.service --no-pager -n 50
+journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=vaultwarden.service --no-pager -n 50

 # Nginx on rx4
-journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \
-  SYSTEMD_UNIT=nginx.service --no-pager -n 50
+journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=nginx.service --no-pager -n 50

 # Matrix-synapse on sid
-journalctl -D /var/log/journal/remote/ _HOSTNAME=sid \
-  SYSTEMD_UNIT=matrix-synapse.service --no-pager -n 50
+journalctl -D /var/log/journal/remote/ _HOSTNAME=sid SYSTEMD_UNIT=matrix-synapse.service --no-pager -n 50

 # Follow logs live
-journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \
-  SYSTEMD_UNIT=podman-open-webui.service -f
+journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=podman-open-webui.service -f
 ```

 ### OCI container unit names

-Containers managed by `virtualisation.oci-containers` get units named
-`podman-<container-attr>.service`:
+Containers managed by `virtualisation.oci-containers` get units named `podman-<container-attr>.service`:

 | Container attr         | Unit name                              | Host |
 |------------------------|----------------------------------------|------|
@ -345,8 +311,7 @@ Containers managed by `virtualisation.oci-containers` get units named

 ## Permissions

-User `sid` must be in both `systemd-journal` and
-`systemd-journal-remote` to read `/var/log/journal/remote/`:
+User `sid` must be in both `systemd-journal` and `systemd-journal-remote` to read `/var/log/journal/remote/`:

 ```nix
 users.users.sid.extraGroups = [
@ -355,7 +320,7 @@ users.users.sid.extraGroups = [
 ];
 ```

-Verify with `id sid` on `sid`.
+Verify with `id sid` on `pc`.

 ---

--- a/constants.nix
+++ b/constants.nix
@ -25,6 +25,10 @@ rec {
      subdomain = "f";
      fqdn = subdomain + "." + domain;
    };
+    librechat-oci = {
+      fqdn = "lc." + domain;
+      port = 3080;
+    };
    mailserver = rec {
      subdomain = "mail";
      fqdn = subdomain + "." + domain;
--- a/hosts/rx4/services/default.nix
+++ b/hosts/rx4/services/default.nix
@ -13,6 +13,7 @@

    ./forgejo.nix
    ./jirafeau.nix
+    ./librechat-oci.nix
    ./miniflux.nix
    ./netdata.nix
    ./nginx.nix
--- a/hosts/rx4/services/librechat-oci.nix
+++ b/hosts/rx4/services/librechat-oci.nix
@ -0,0 +1,44 @@
+{
+  inputs,
+  constants,
+  config,
+  ...
+}:
+
+let
+  inherit (constants) domain;
+  inherit (constants.hosts.rx4) ip;
+  inherit (constants.services.librechat-oci) fqdn port;
+in
+{
+  imports = [
+    inputs.synix.nixosModules.librechat-oci
+  ];
+
+  services.librechat-oci = {
+    enable = true;
+    inherit port;
+    externalUrl = "https://${fqdn}";
+  };
+
+  services.nginx.virtualHosts."${fqdn}" = {
+    useACMEHost = fqdn;
+    forceSSL = true;
+    listen = [
+      {
+        addr = "${ip}:443";
+        ssl = true;
+      }
+    ];
+    locations."/" = {
+      proxyPass = "http://127.0.0.1:${toString port}";
+      proxyWebsockets = true;
+    };
+  };
+
+  security.acme.certs."${fqdn}" = {
+    domain = fqdn;
+    postRun = "systemctl restart podman-librechat.service";
+    group = "nginx";
+  };
+}
Author	SHA1	Message	Date
sid	6b4474e1ca	streamline AGENTS.md All checks were successful Build hosts / build-hosts (pull_request) Successful in 19s Details Flake check / flake-check (pull_request) Successful in 19s Details	2026-05-19 00:26:45 +02:00
sid	aa51907812	add librechat-oci	2026-05-19 00:26:20 +02:00