feat: export and document codex-oauth-proxy user service

This commit is contained in:
Marmel Coder
2026-11-12 16:59:24 +03:00
parent 8c6897e66d
commit 48a19c55b8
2 changed files with 92 additions and 0 deletions
+91
View File
@@ -186,6 +186,97 @@ Note: the `node_modules` symlink is shared across everything in the plugins
directory; other manually-installed plugins with conflicting npm dependencies
cannot coexist with it.
### Codex OAuth Proxy (systemd user service)
On Linux with a running systemd user manager, the package provides
`lib/systemd/user/codex-oauth-proxy.service`. Installing the package alone does
not enable or start it. To use the packaged unit without Home Manager:
```bash
package=$(nix build --no-link --print-out-paths \
git+https://git.millerson.name/alex/millerson-overlay.nix.git#codex-oauth-proxy)
systemctl --user enable --now "$package/lib/systemd/user/codex-oauth-proxy.service"
systemctl --user status codex-oauth-proxy.service
```
Keep the selected package in a Nix profile or another garbage-collection root
while using its unit. To stop it and remove its enablement links:
```bash
systemctl --user disable --now codex-oauth-proxy.service
```
Do not manage the same unit with both this procedure and Home Manager.
#### Home Manager
Import the module and make the package available in Home Manager's `pkgs`:
```nix
imports = [ millerson-nix-overlay.homeManagerModules.default ];
nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ];
programs.codex-oauth-proxy.enable = true;
```
The module installs the package and manages the user unit and its
`default.target` link. Its package default selects
`pkgs.millerson-nix-overlay.codex-oauth-proxy`, falling back to
`pkgs.codex-oauth-proxy`. Importing `homeManagerModules.default` does not add an
overlay. Supply the overlay to the actual Home Manager package set, or set
`programs.codex-oauth-proxy.package` explicitly to this flake's package for your
system.
Apply the configuration with your normal Home Manager activation. Enabling
starts this service without changing `systemd.user.startServices`. To stop and
disable a previously module-managed service, keep the import and apply:
```nix
programs.codex-oauth-proxy.enable = false;
```
Removing the import also removes the cleanup hook, so first activate with
`enable = false`. A fresh disabled configuration leaves a manually managed
same-named service untouched. Starting or stopping a module-managed service
requires an available user manager; activation reports failure if it is unavailable. The module does not enable
lingering or change the global service activation policy.
#### State and security
Both units use persistent OAuth state at `%S/codex-oauth-proxy/auth.json`,
normally `~/.local/state/codex-oauth-proxy/auth.json` in a user manager. The state
directory has mode `0700` and the service umask is `0077`. Upstream may migrate
existing credentials when the destination is absent, and refreshes rewrite the
credential file. Keep it writable and outside the Nix store and immutable Home
Manager files. Disabling the service does not delete this credential state.
Missing credentials do not prevent startup, but successful upstream requests
require valid credentials.
The server binds all interfaces on port `9879` by default, not just loopback.
Restrict access with your network/firewall configuration. The service does not
add TLS or network access controls.
`ADMIN_API_KEY` protects upstream's admin endpoints. No default key is generated.
If unset or empty, protected requests return HTTP 500; the server can still
start. The packaged unit does not set this variable; a user-manager environment
can supply it. Home Manager has an optional literal setting (placeholder only):
```nix
programs.codex-oauth-proxy.admin_api_key = "REPLACE_WITH_NON_SECRET_PLACEHOLDER";
```
The default `null` omits the assignment. A non-null value must contain printable
ASCII; an empty string explicitly supplies an empty value. **A literal key in
this option is public in the Nix store, retained generations, and systemd
introspection. Do not put a confidential production key here.** This option is
not a runtime secret-delivery mechanism.
Both units discard stdout and stderr because upstream logs token previews and
other potentially sensitive request/response data. Production mode does not
establish redaction. Application logs are therefore unavailable in the journal;
systemd status and exit diagnostics remain. Do not override these output settings
without first addressing upstream token logging.
### PdfCraft (Home Manager)
`pdfcraft` is built from source (no upstream binaries are downloaded). A Home
+1
View File
@@ -66,6 +66,7 @@
homeManagerModules.default = {
imports = [
./modules/codex-oauth-proxy-hm.nix
./modules/open-code-review-hm.nix
./modules/pdfcraft-hm.nix
];