docs: add systemd user service and persistent env setup

Add templates/claude-tokenization-proxy.service (systemd user unit that runs
the proxy at login, restarts on failure) and README sections covering its
installation, lingering for boot-before-login, and permanently setting
ANTHROPIC_BASE_URL across fish, bash/zsh, and environment.d.
This commit is contained in:
2026-06-19 23:18:32 -04:00
parent d6f9a51513
commit afb739f061
2 changed files with 81 additions and 0 deletions
+59
View File
@@ -84,6 +84,65 @@ Treat them as opaque identifiers and preserve them exactly as they appear when
writing or reading files.
```
## Run at boot/login (systemd user service)
[`templates/claude-tokenization-proxy.service`](templates/claude-tokenization-proxy.service)
is a ready-to-use systemd **user** unit that runs the proxy in the background and
restarts it on failure.
```bash
# 1. Install the unit
mkdir -p ~/.config/systemd/user
cp templates/claude-tokenization-proxy.service ~/.config/systemd/user/
# 2. Edit WorkingDirectory= to point at your clone (and the node path if you
# use a version manager like nvm/fnm/asdf — see the comments in the unit)
$EDITOR ~/.config/systemd/user/claude-tokenization-proxy.service
# 3. Enable + start it
systemctl --user daemon-reload
systemctl --user enable --now claude-tokenization-proxy.service
# Check status / logs
systemctl --user status claude-tokenization-proxy.service
journalctl --user -u claude-tokenization-proxy.service -f
```
A user service starts when **you** log in. To keep it running at boot before
any login (and after you log out), enable lingering for your account:
```bash
sudo loginctl enable-linger "$USER"
```
## Permanently point claude-code at the proxy
Setting `ANTHROPIC_BASE_URL` per shell (as in [Setup](#setup)) only lasts for
that session. To make it stick:
- **fish** — set a universal variable once; it persists across sessions:
```fish
set -Ux ANTHROPIC_BASE_URL http://localhost:8080
```
- **bash/zsh** — add the export to your shell rc (or `~/.profile` for all
shells):
```bash
echo 'export ANTHROPIC_BASE_URL=http://localhost:8080' >> ~/.bashrc
```
- **All processes in a graphical session** (works regardless of shell) — drop
it in systemd's user environment:
```bash
mkdir -p ~/.config/environment.d
echo 'ANTHROPIC_BASE_URL=http://localhost:8080' >> ~/.config/environment.d/claude.conf
```
Takes effect on next login.
## Scripts
| Command | What it does |
@@ -0,0 +1,22 @@
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later
[Unit]
Description=claude-code tokenization proxy (ggshield DLP)
After=network-online.target
Wants=network-online.target
[Service]
# Edit this to the absolute path where you cloned the repo.
WorkingDirectory=%h/projects/claude-tokenization-proxy
# Requires Node >= 23.6 on PATH. If you use nvm/fnm/asdf, replace
# "/usr/bin/env node" with the absolute path to your node binary
# (run `which node` to find it).
ExecStart=/usr/bin/env node src/index.ts
Restart=on-failure
RestartSec=5
# Optional overrides (see README "Configuration"):
# Environment=PORT=8080
[Install]
WantedBy=default.target