llm-mitm-proxy 2026.9.0__tar.gz

llm_mitm_proxy-2026.9.0/.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+  "name": "llm-mitm-proxy",
+  "image": "mcr.microsoft.com/devcontainers/python:3.14",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "lts"
+    },
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
+  "forwardPorts": [8081, 9090],
+  "postCreateCommand": "pip install -e '.[dev]' && npm install && npm run build"
+}

llm_mitm_proxy-2026.9.0/.dockerignore

@@ -0,0 +1,9 @@
+.venv/
+node_modules/
+llm_proxy/web/
+**/__pycache__/
+*.pyc
+.devcontainer/
+build/
+*.egg-info/
+dist/

llm_mitm_proxy-2026.9.0/.github/workflows/checks.yml

@@ -0,0 +1,64 @@
+name: Code Quality Checks
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+# Kill existing jobs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install black isort
+      - run: black --check --diff llm_proxy
+      - run: isort --check-only --diff llm_proxy
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run verify:js
+
+  run-unittest:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      fail-fast: true
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # History/tags required to generate version info
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: python -c "import sys; print(sys.version)"
+      # Build the UI so the in-package serving + packaging tests run (they
+      # skip when llm_proxy/web is absent).
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: |
+          python -m pip install --upgrade pip
+          pip install --editable .
+      - run: python -m unittest

llm_mitm_proxy-2026.9.0/.github/workflows/deploy-docker.yml

@@ -0,0 +1,65 @@
+name: Publish Docker Images
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["*"]
+
+  pull_request:
+    branches: ["main"]
+
+# Kill existing jobs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: mill1000/llm-mitm-proxy
+  # No linux/arm/v7: esbuild (the UI build stage) has no armv7 binary.
+  PLATFORMS: linux/amd64,linux/arm64
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+
+    permissions:
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # History/tags required to generate version info
+          fetch-depth: 0
+
+      - uses: docker/metadata-action@v6
+        id: meta
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # Generate tags for latest commit, version tags and PRs
+          tags: |
+            type=edge
+            type=pep440,pattern={{version}}
+            type=ref,event=pr
+
+      - uses: docker/setup-qemu-action@v4
+        with:
+          platforms: ${{ env.PLATFORMS }}
+
+      - uses: docker/setup-buildx-action@v4
+
+      - uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ env.PLATFORMS }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

llm_mitm_proxy-2026.9.0/.github/workflows/prune-ghcr.yml

@@ -0,0 +1,55 @@
+name: Prune GHCR
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    types: [closed]
+
+  schedule:
+    - cron: "20 4 * * 0"
+
+  workflow_dispatch:
+
+env:
+  CONTAINER_NAME: llm-mitm-proxy
+
+jobs:
+  prune-pr-images:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - uses: vlaurin/action-ghcr-prune@v0.6.0
+        with:
+          container: ${{ env.CONTAINER_NAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          prune-tags-regexes: ^pr-${{github.event.pull_request.number}}
+          # dry-run: true
+
+  prune-old-images:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - uses: vlaurin/action-ghcr-prune@v0.6.0
+        with:
+          container: ${{ env.CONTAINER_NAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # Keep PRs, CalVer releases, latest and edge
+          keep-tags-regexes: |
+            ^pr-
+            ^\d{4}\.\d{2}\.\d{2}
+          keep-tags: |
+            edge
+            latest
+          # dry-run: true
+
+      - uses: dataaxiom/ghcr-cleanup-action@v1
+        with:
+          package: ${{ env.CONTAINER_NAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # dry-run: true
+          validate: true

llm_mitm_proxy-2026.9.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,49 @@
+name: Publish Python Package
+permissions:
+  contents: read
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # History/tags required to generate version info
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      # The wheel ships the WebUI as in-package build output (llm_proxy/web),
+      # so the UI must be built before the wheel.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - run: npm ci
+      - run: npm run build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+  publish-package:
+    needs: build-package
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Mandatory for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # with:
+        #   repository-url: https://test.pypi.org/legacy/

llm_mitm_proxy-2026.9.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+node_modules/
+llm_proxy/web/
+.env
+.DS_Store
+devcontainer-lock.json

llm_mitm_proxy-2026.9.0/Dockerfile

@@ -0,0 +1,48 @@
+# UI build
+FROM node:alpine AS ui
+
+WORKDIR /src
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY ui ./ui
+RUN npm run build
+
+# Backend build
+FROM python:3.14-alpine AS build
+
+RUN apk add --no-cache --update git
+RUN pip install --no-cache-dir build
+
+ARG VERSION
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}
+
+WORKDIR /app
+COPY . .
+COPY --from=ui /src/llm_proxy/web llm_proxy/web
+RUN python -m build --wheel
+
+# Runtime
+FROM alpine:3.24
+
+RUN apk add --no-cache --update python3 pipx tini
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+ENV PIPX_HOME=/opt/pipx
+ENV PIPX_BIN_DIR=/usr/bin
+
+COPY --from=build /app/dist/llm_mitm_proxy-*.whl /tmp/
+RUN pipx install /tmp/llm_mitm_proxy-*.whl && rm /tmp/llm_mitm_proxy-*.whl
+
+RUN adduser -D -u 1000 -h /dev/null -s /sbin/nologin appuser
+USER appuser
+
+EXPOSE 8081 9090
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s \
+  CMD python3 -c "import urllib.request;urllib.request.urlopen('http://127.0.0.1:9090/health', timeout=8)"
+
+ENTRYPOINT ["/sbin/tini", "--"]
+
+CMD ["/bin/sh", "-c", "llm-mitm-proxy ${UPSTREAM_BASE_URL:+$UPSTREAM_BASE_URL} ${UPSTREAM_API_KEY:+--upstream-api-key $UPSTREAM_API_KEY} ${LISTEN_HOST:+--host $LISTEN_HOST} ${PROXY_PORT:+--proxy-port $PROXY_PORT} ${WEB_PORT:+--web-port $WEB_PORT} ${LOG_LEVEL:+--log-level $LOG_LEVEL}"]

llm_mitm_proxy-2026.9.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tucker Kern
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_mitm_proxy-2026.9.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: llm-mitm-proxy
+Version: 2026.9.0
+Summary: A simple transparent MITM proxy for LLM APIs with a live Web UI
+Project-URL: Repository, https://github.com/mill1000/llm-mitm-proxy
+Project-URL: Issues, https://github.com/mill1000/llm-mitm-proxy/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: httpx2>=2
+Provides-Extra: dev
+Requires-Dist: isort>=5; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Dynamic: license-file
+
+# llm-mitm-proxy
+A simple transparent MITM proxy for LLM APIs with a live Web UI for inspecting, replaying, and exporting "conversations" between clients and an upstream server.
+
+**Trusted networks or testing only**
+There is no authentication, no SSL/TLS termination, or other "reverse proxy" feature set. Its primary intent is to provide visibility between an agent and the server.
+
+![llm-mitm-proxy WebUI](./docs/screenshot.png)
+
+## Client Identification
+Clients are identified by their source IP, user agent, and API key (if provided), which determines which "conversation" traffic appears under in the Web UI. An API key is not required, IP and user agent are enough to tell many clients apart, but an API key can be used as a further split for clients sharing the same IP, and user agent.
+
+## Dissectors
+The proxy forwards all traffic verbatim and decodes requests and responses for the Web UI with per-request dissectors that match on method + path.
+
+Supported dissectors:
+- `openai`: OpenAI-compatible chat completions
+- `generic`: everything else, captured as raw data
+
+## Vibe Warning
+This project was entirely **vibe coded** with Qwen 3.8 27B and the Zed Agent on local hardware.
+
+Work proceeded milestone by milestone according to the [PLAN.md](./docs/PLAN.md) with design, key decisions, and open questions. Occasional updates were made to the plan as direction shifted. Each milestone was tested against a llama.cpp server by a human before committed.
+
+The full agent conversation log is preserved in [CONVERSATION.md](./docs/CONVERSATION.md).
+
+## Quick Start
+### Docker Compose
+```yaml
+services:
+  llm-mitm-proxy:
+    image: ghcr.io/mill1000/llm-mitm-proxy:latest
+    restart: unless-stopped
+    ports:
+      - "8081:8081" # LLM API
+      - "9090:9090" # Web UI
+    environment:
+      UPSTREAM_BASE_URL: "http://<your-llamacpp>:8080"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+### Docker
+```bash
+docker run -d --name llm-mitm-proxy -p 8081:8081 -p 9090:9090 -e UPSTREAM_BASE_URL=http://<your-llamacpp>:8080 ghcr.io/mill1000/llm-mitm-proxy:latest
+```
+
+## pipx/uvx
+```bash
+# uvx
+uvx llm-mitm-proxy http://<your-llamacpp>:8080
+
+# pipx
+pipx install llm-mitm-proxy
+llm-mitm-proxy http://<your-llamacpp>:8080
+```
+
+## Usage
+1. Start the proxy
+2. Point an agent at the proxy
+3. Open the Web UI and look at the requests go brrr.
+
+See [Configuration](#configuration) for more information on specifying an upstream API key, changing ports, and other options.
+
+## Configuration
+### Command Line
+```
+usage: llm-mitm-proxy [-h] [--version] [--host HOST] [--proxy-port PORT] [--web-port PORT]
+                      [--upstream-api-key KEY] [--log-level LEVEL] [--ui-dir DIR]
+                      [UPSTREAM_BASE_URL]
+```
+
+| Arg | Notes |
+|---|---|
+| `UPSTREAM_BASE_URL` (positional) | upstream base URL (default `http://host.docker.internal:8080`) |
+| `--host` | listen host for both listeners (default `0.0.0.0`) |
+| `--proxy-port` | proxy listener port (default `8081`, the transparent catch-all; llama.cpp's own default is `8080`) |
+| `--web-port` | WebUI + `/api/*` + `/ws` + `/health` listener port (default `9090`) |
+| `--upstream-api-key` | optional server-side fallback key, injected only when a client sends no key |
+| `--log-level` | app loggers, incl. the `llm_proxy.ws` connection trace at `debug` (connect/focus/disconnect) |
+| `--ui-dir` | static UI directory (default: the in-package `llm_proxy/web` build) |
+| `--help` / `--version` | usage / package version |
+
+### Docker Environment Variables
+
+The Docker image maps the following environment variables to command line options:
+| Var | CLI arg |
+|---|---|
+| `UPSTREAM_BASE_URL` | positional upstream |
+| `UPSTREAM_API_KEY` | `--upstream-api-key` |
+| `LISTEN_HOST` | `--host` |
+| `PROXY_PORT` | `--proxy-port` |
+| `WEB_PORT` | `--web-port` |
+| `LOG_LEVEL` | `--log-level` |

llm_mitm_proxy-2026.9.0/README.md

@@ -0,0 +1,93 @@
+# llm-mitm-proxy
+A simple transparent MITM proxy for LLM APIs with a live Web UI for inspecting, replaying, and exporting "conversations" between clients and an upstream server.
+
+**Trusted networks or testing only**
+There is no authentication, no SSL/TLS termination, or other "reverse proxy" feature set. Its primary intent is to provide visibility between an agent and the server.
+
+![llm-mitm-proxy WebUI](./docs/screenshot.png)
+
+## Client Identification
+Clients are identified by their source IP, user agent, and API key (if provided), which determines which "conversation" traffic appears under in the Web UI. An API key is not required, IP and user agent are enough to tell many clients apart, but an API key can be used as a further split for clients sharing the same IP, and user agent.
+
+## Dissectors
+The proxy forwards all traffic verbatim and decodes requests and responses for the Web UI with per-request dissectors that match on method + path.
+
+Supported dissectors:
+- `openai`: OpenAI-compatible chat completions
+- `generic`: everything else, captured as raw data
+
+## Vibe Warning
+This project was entirely **vibe coded** with Qwen 3.8 27B and the Zed Agent on local hardware.
+
+Work proceeded milestone by milestone according to the [PLAN.md](./docs/PLAN.md) with design, key decisions, and open questions. Occasional updates were made to the plan as direction shifted. Each milestone was tested against a llama.cpp server by a human before committed.
+
+The full agent conversation log is preserved in [CONVERSATION.md](./docs/CONVERSATION.md).
+
+## Quick Start
+### Docker Compose
+```yaml
+services:
+  llm-mitm-proxy:
+    image: ghcr.io/mill1000/llm-mitm-proxy:latest
+    restart: unless-stopped
+    ports:
+      - "8081:8081" # LLM API
+      - "9090:9090" # Web UI
+    environment:
+      UPSTREAM_BASE_URL: "http://<your-llamacpp>:8080"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+### Docker
+```bash
+docker run -d --name llm-mitm-proxy -p 8081:8081 -p 9090:9090 -e UPSTREAM_BASE_URL=http://<your-llamacpp>:8080 ghcr.io/mill1000/llm-mitm-proxy:latest
+```
+
+## pipx/uvx
+```bash
+# uvx
+uvx llm-mitm-proxy http://<your-llamacpp>:8080
+
+# pipx
+pipx install llm-mitm-proxy
+llm-mitm-proxy http://<your-llamacpp>:8080
+```
+
+## Usage
+1. Start the proxy
+2. Point an agent at the proxy
+3. Open the Web UI and look at the requests go brrr.
+
+See [Configuration](#configuration) for more information on specifying an upstream API key, changing ports, and other options.
+
+## Configuration
+### Command Line
+```
+usage: llm-mitm-proxy [-h] [--version] [--host HOST] [--proxy-port PORT] [--web-port PORT]
+                      [--upstream-api-key KEY] [--log-level LEVEL] [--ui-dir DIR]
+                      [UPSTREAM_BASE_URL]
+```
+
+| Arg | Notes |
+|---|---|
+| `UPSTREAM_BASE_URL` (positional) | upstream base URL (default `http://host.docker.internal:8080`) |
+| `--host` | listen host for both listeners (default `0.0.0.0`) |
+| `--proxy-port` | proxy listener port (default `8081`, the transparent catch-all; llama.cpp's own default is `8080`) |
+| `--web-port` | WebUI + `/api/*` + `/ws` + `/health` listener port (default `9090`) |
+| `--upstream-api-key` | optional server-side fallback key, injected only when a client sends no key |
+| `--log-level` | app loggers, incl. the `llm_proxy.ws` connection trace at `debug` (connect/focus/disconnect) |
+| `--ui-dir` | static UI directory (default: the in-package `llm_proxy/web` build) |
+| `--help` / `--version` | usage / package version |
+
+### Docker Environment Variables
+
+The Docker image maps the following environment variables to command line options:
+| Var | CLI arg |
+|---|---|
+| `UPSTREAM_BASE_URL` | positional upstream |
+| `UPSTREAM_API_KEY` | `--upstream-api-key` |
+| `LISTEN_HOST` | `--host` |
+| `PROXY_PORT` | `--proxy-port` |
+| `WEB_PORT` | `--web-port` |
+| `LOG_LEVEL` | `--log-level` |

llm_mitm_proxy-2026.9.0/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  llm-mitm-proxy:
+    image: ghcr.io/mill1000/llm-mitm-proxy:latest
+    restart: unless-stopped
+    ports:
+      - "8081:8081" # LLM API
+      - "9090:9090" # Web UI
+    environment:
+      UPSTREAM_BASE_URL: "http://<your-llamacpp>:8080"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"