feat: export and document codex-oauth-proxy user service
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user