# aiproxy
[](https://buymeacoffee.com/cucoo)
> aiproxy is free and keeps your data on your machine. If it saves you from
> leaking PII to an LLM provider, **[buy me a coffee ☕](https://buymeacoffee.com/cucoo)** —
> it funds the time that keeps the project maintained.
Anonymizing reverse proxy for LLM APIs. Point Claude Code (or any AI tool)
at aiproxy; it scrubs people/company names and other sensitive content with
a **local** LLM before forwarding to Anthropic, then restores the originals
in the reply. Pluggable filter/processor interface. Handles text, images,
PDFs.
```
AI tool ──▶ aiproxy ──(redacted)──▶ Anthropic
▲ │ │
└─(restored)─┴───────(tokens)────────┘
```
- Reversible anonymization: originals ↔ tokens kept in a local encrypted store.
- One `Processor` interface — drop in your own filters (or reviewed [plugins](docs/WRITING_A_PROCESSOR.md)).
- Ships: `secrets_regex`, `anonymizer` (local-LLM NER), `image_redactor`, `logger`.
- `/dryrun` endpoint to preview redactions before trusting it.
- Scales to a shared org service: per-user identity + isolation, self-service
term lists (`/terms`), SQLite **or** Postgres store, config hot-reload
(`SIGHUP`), secrets-manager key sourcing, `/readyz`. See
[`docs/ORG_DEPLOYMENT.md`](docs/ORG_DEPLOYMENT.md).
Full install + usage: [`docs/MANUAL.md`](docs/MANUAL.md).
> ⚠️ **Use at your own risk — no warranty.** aiproxy is provided *as is*,
> without warranty of any kind (see the **No Liability** clause in
> [`LICENSE`](LICENSE)). Detection is **not guaranteed**: a local LLM can miss
> an entity, so a real value can still reach the upstream provider. You are
> responsible for validating redaction for your own data and for any
> obligations you have to the people whose data you process. Run it in
> `fail_closed` mode, verify with `/dryrun`, and treat the mapping store as a
> secret. See the [threat model](docs/MANUAL.md#threat-model).
## Architecture
The pipeline redacts on the way out and restores on the way in; the upstream
API only ever sees tokens. Both directions share the encrypted store and the
local NER model.
```mermaid
flowchart LR
C["AI client"] --> I["Ingress · identity
resolve user_id
session = user/raw"]
I --> P
subgraph P["Pipeline"]
direction TB
L["logger"] --> S["secrets_regex"] --> A["anonymizer · NER → ⟦TOKEN⟧"] --> IR["image_redactor"]
end
P -- "redacted + tokens" --> U["Upstream LLM
(sees tokens only)"]
U -- "tokens" --> P
P -- "originals restored" --> C
A <-- "detect" --> N["Local NER (Ollama)"]
P <-- "put / token_for · cache · terms" --> ST[("Store · encrypted
sqlite | postgres")]
K["Key source
env | file | command"] -. "at-rest key" .-> ST
```
Scaled to a shared org service it runs stateless frontends behind a load
balancer over a shared Postgres store and NER service — diagrams and design in
[`docs/MANUAL.md#1b-architecture`](docs/MANUAL.md#1b-architecture) and
[`docs/ORG_DEPLOYMENT.md`](docs/ORG_DEPLOYMENT.md).
## Install
First get the code (needs `git` and Python ≥ 3.11):
```bash
git clone https://github.com/cucooOnGithub/aiproxy.git aiproxy
cd aiproxy
```
Then pick a deployment shape. Full detail for each is in the manual:
[single workstation](docs/MANUAL.md#2-install--single-workstation) ·
[organization](docs/MANUAL.md#2b-install--organization).
### A · Single workstation
One person, one machine; local SQLite store and local NER model.
**Requirements**
| | Minimum | Comfortable |
|---|---|---|
| OS | macOS, Linux, or Windows 10+ | same |
| Python | 3.11+ | 3.11+ |
| RAM free | 6 GB (CPU-only NER) | 8 GB+ |
| GPU | none — runs on CPU | any GPU with ≥ 4 GB VRAM (much faster NER + pre-warm) |
| Disk | ~4 GB (deps + the 3B NER model) | SSD |
| Also installed | Ollama (local LLM runtime) and the Tesseract OCR binary — the installer handles both | |
The default NER model is `qwen2.5:3b-instruct` (~2 GB). OCR runs on CPU.
**One-command install** — sets up the venv + deps, Ollama (and starts it),
Tesseract, the NER model, a store key, and `config.yaml`:
```bash
./install.sh # macOS / Linux
powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows
```
Then verify and run:
```bash
python -m aiproxy doctor --config config.yaml # check everything is set up
python -m aiproxy serve --config config.yaml
export ANTHROPIC_BASE_URL=http://127.0.0.1:8080 # match listen.port
```
Up and running? If aiproxy is now keeping your data private, consider
[**buying me a coffee ☕**](https://buymeacoffee.com/cucoo) to support it.
Manual quick start (skip the installer)
```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[media]" # core; needs the tesseract binary
ollama pull qwen2.5:3b-instruct
cp config.example.yaml config.yaml
export AIPROXY_STORE_KEY="$(python -m aiproxy genkey)" # if store.encrypt: true
python -m aiproxy serve --config config.yaml
```
Build a standalone binary (optional)
```bash
./build.sh # -> dist/aiproxy (macOS/Linux)
powershell -ExecutionPolicy Bypass -File .\build.ps1 # -> dist\aiproxy.exe (Windows)
./dist/aiproxy serve --config config.yaml
```
PyInstaller can't cross-compile — build on each target OS. Tesseract and
Ollama are **not** bundled. Details in
[docs/MANUAL.md](docs/MANUAL.md#build-a-standalone-binary-optional).