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
|
directory; other manually-installed plugins with conflicting npm dependencies
|
||||||
cannot coexist with it.
|
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 (Home Manager)
|
||||||
|
|
||||||
`pdfcraft` is built from source (no upstream binaries are downloaded). A Home
|
`pdfcraft` is built from source (no upstream binaries are downloaded). A Home
|
||||||
|
|||||||
Reference in New Issue
Block a user