Osprin Proxy

Start observing.

Open-source API traffic platform for capturing, inspecting, mocking, scripting, and testing HTTP and WebSocket traffic.

Osprin Proxy is a desktop app: a Tauri + React interface over a Python interception engine. Point a
client at the local proxy and every request, response, SSE stream, and WebSocket frame shows up
live — with bodies, headers, timings, and the ability to annotate, replay, mock, and rewrite with
your own Python.

Status: early development. The interface reads live traffic from the engine — it no longer
renders fixture data. Interfaces will change without notice until 0.1.0. Not open to outside
contributions yet.

What it does

• Capture — every exchange through the proxy, with bodies, timings, and the local app that made
  it. TLS is decrypted once you trust the generated CA.
• Map data — answer a request from a canned response, with no server involved.
• Map remote — send a request to a different origin: a staging host, or a local port.
• Scripts — run your own Python on a matching exchange. on_request before it is sent,
  on_response before it is shown; change what you were handed or return a reply and skip the
  server entirely. One rule per path, each with its own two files and its own switch.

# response.py, on api.example.com/v1/orders/{id}
def on_response(request, response):
    data = response.json()
    data["status"] = "cancelled"
    response.set_json(data)

The editor is Monaco — VS Code's — with completion, hovers and signature help answered by Jedi
running inside the engine, so an import resolves against the same site-packages the script will
run against, and syntax errors and unresolvable imports surface as you type.

Requirements

Quick start

Install the tools in Requirements first — Node, pnpm, Rust (which provides
cargo), Python, and uv.

git clone https://github.com/prabhu369b/osprin-proxy.git
cd osprin-proxy
cp .env.example .env

pnpm install     # interface
uv sync          # engine

pnpm engine      # terminal 1 — engine on :8000, proxy on :9100
pnpm tauri dev   # terminal 2 — desktop app

To capture HTTPS you must trust the CA the engine generates on first run. It is written to
~/.mitmproxy/mitmproxy-ca-cert.pem; the app's Certificate page walks through installing it.

Installation

Requires pnpm and Rust (cargo) installed — see Requirements.

pnpm install
pnpm tauri build

Builds the installable desktop app for your platform, into src-tauri/target/release/bundle/.

Layout

osprin-proxy/
├── engine/            Python capture engine (FastAPI + mitmproxy)
│   ├── config/        Settings — env-driven, validated by pydantic
│   ├── core/          Logging, app lifespan and wiring
│   ├── modules/       One folder per feature, layered router → service → repository
│   │   ├── capture/   Capture buffer, annotations, SSE stream
│   │   ├── forward/   Map remote — rewrite a request's origin
│   │   ├── mock/      Map data — canned responses, matched host then path
│   │   ├── proxy/     mitmproxy lifecycle and the flow → domain translation
│   │   └── script/    User Python: runtime, matching, and editor intelligence
│   ├── shared/        Response envelope, exceptions, event broker
│   ├── tests/
│   └── main.py        App assembly and entrypoint
├── src/               React interface (see AGENTS.md for its conventions)
├── src-tauri/         Rust desktop shell
└── docs/              Architecture notes

Architecture and the reasoning behind it: docs/ARCHITECTURE.md.

Commands

pnpm dev             # interface only, in a browser
pnpm tauri dev       # full desktop app
pnpm build           # typecheck + build the interface
pnpm tauri build     # build the installable desktop app
pnpm lint            # eslint
pnpm gen:routes      # regenerate the TanStack route tree

pnpm engine          # run the engine
uv run pytest        # engine tests
uv run ruff check .  # engine lint

The engine's OpenAPI docs are at http://127.0.0.1:8000/docs while it runs.

Security

Osprin Proxy decrypts TLS by design and holds captured tokens and cookies in memory in plaintext. Read
SECURITY.md before pointing it at anything, and report vulnerabilities privately
rather than in a public issue.

Legal

MIT.

Osprin Proxy decrypts TLS traffic by design. Use it only on traffic you are authorised to inspect.