---
## What is Proxelar?
Proxelar is a single-binary MITM proxy for developers who need to see and change what an app is doing on the wire without running a full security suite.
```
Your app ──► Proxelar :8080 ──► Upstream service
│
Inspect · Intercept · Rewrite · Mock
```
It is useful for debugging APIs, inspecting browser or mobile traffic, testing WebSocket clients, injecting headers, mocking local services, replaying captured requests, and automating request/response transforms with Lua.
Proxelar is intentionally developer-oriented: terminal-first, scriptable, Rust-native, and usable as a CLI tool or as the `proxyapi` library.
---
## Why use it?
- **One local binary** — install with Homebrew, winget, Cargo, Docker/Podman, or GitHub releases.
- **Four interfaces** — TUI, plain terminal output, browser GUI, or a headless REST API.
- **Lua scripting** — `on_request` and `on_response` hooks can rewrite, block, short-circuit, or mock traffic.
- **Interactive intercept** — pause requests, edit method/URI/headers/body, forward, drop, or replay.
- **HTTPS MITM** — local CA generation, per-host certificates, and a built-in certificate install page.
- **Forward and reverse modes** — inspect configured clients or put Proxelar in front of a local service.
- **Native protocol core** — HTTP/1, HTTP/2, and feature-gated HTTP/3 without Hyper in the proxy data path.
- **Six capture modes** — forward, reverse, WireGuard, SOCKS5, DNS inspection/rewrite, and fixed-target raw UDP.
- **WebSocket inspection** — capture connections and browse frames by direction, opcode, and payload preview.
- **Portable sessions** — save/reload native captures or import/export HAR, curl, and raw HTTP files with secret redaction.
- **Rules and automation** — map local/remote URLs, mock and redirect requests, hot-reload Lua, or drive the bearer-token REST API.
---
## Installation
### Homebrew (macOS / Linux)
```bash
brew install proxelar
```
### winget (Windows)
```bash
winget install --id EmanueleMicheletti.Proxelar --exact
```
### Cargo
```bash
cargo install proxelar
```
### Docker / Podman
The published image supports `linux/amd64` and `linux/arm64`, with Lua and HTTP/3 enabled. Docker and Podman select the matching architecture automatically.
```bash
# Web GUI
docker run --rm -it -v ~/.proxelar:/root/.proxelar -p 8080:8080 -p 127.0.0.1:8081:8081 ghcr.io/emanuele-em/proxelar --interface gui --addr 0.0.0.0
# Terminal
docker run --rm -it -v ~/.proxelar:/root/.proxelar -p 8080:8080 ghcr.io/emanuele-em/proxelar --interface terminal --addr 0.0.0.0
```
The `-v ~/.proxelar:/root/.proxelar` mount reuses your existing trusted CA certificate so you do not get browser warnings after trusting the CA once. The container always keeps its state at `/root/.proxelar`; if your host state directory differs (because `XDG_CONFIG_HOME` is set), mount that path instead of `~/.proxelar`.
---
## Quick Start
**1. Start the proxy**
```bash
proxelar
```
**2. Configure a client**
Set HTTP and HTTPS proxy to `127.0.0.1:8080` in your browser, OS, mobile device, app, or tool.
**3. Install the CA certificate for HTTPS**
Visit `http://proxel.ar` while routing traffic through Proxelar. It serves the generated root certificate and install instructions.
Traffic appears in the TUI immediately.
```bash
# quick smoke test
curl -x http://127.0.0.1:8080 http://httpbin.org/get
curl -x http://127.0.0.1:8080 https://httpbin.org/get
```
---
## Example: mock an API response
Create `mock_user.lua`:
```lua
function on_request(request)
if request.method == "GET" and string.find(request.url, "/api/user/me") then
return {
status = 200,
headers = { ["Content-Type"] = "application/json" },
body = '{"id":1,"name":"Local Test User"}',
}
end
end
```
Run Proxelar in front of a local service:
```bash
proxelar -m reverse --target http://localhost:3000 --script mock_user.lua
```
Then call `http://127.0.0.1:8080/api/user/me` to receive the mocked response.
More scripts are in [`examples/scripts/`](examples/scripts/), including auth injection, CORS headers, HTML rewriting, cookie stripping, redirects, traffic logging, and JSON body edits.
Portable addons use a versioned `proxelar-addon.json` manifest with semantic
versioning, declared hooks/native-code requirements, and SHA-256 coverage for
every package file. Proxelar rejects traversal, symlinks, undeclared files, and
tampered content before installation or execution:
```bash
proxelar addon verify ./examples/addons/header-tagger
proxelar addon install ./examples/addons/header-tagger
proxelar addon list
proxelar --addon header-tagger
```
See [`examples/addons/header-tagger/`](examples/addons/header-tagger/) for a
minimal distributable package. Existing manifest-free `--script` directories
remain supported for local development.
---
## Interfaces
```bash
proxelar # interactive TUI (default)
proxelar -i terminal # plain terminal output
proxelar -i gui # web GUI at http://localhost:8081
proxelar -i api # headless REST API at http://localhost:8081
```
Common options:
```bash
proxelar -m reverse --target http://localhost:3000 # reverse proxy
proxelar -m reverse --target http3://localhost:4433 # UDP-only H3 reverse proxy
proxelar -b 0.0.0.0 -p 9090 # custom bind/port
proxelar --script examples/scripts/block_domain.lua # with a Lua script
proxelar --body-capture-limit 1048576 # cap captured/editable body bytes
proxelar --upstream-trust default+ca:/path/ca.pem # trust an extra upstream CA
proxelar --save-session debug.proxelar.json # save on Ctrl+C
proxelar -i gui --launch-browser # isolated Chromium proxy profile
proxelar -m wireguard -b 0.0.0.0 -p 51820 \
--wireguard-endpoint 192.168.1.10:51820 # mobile/IoT capture
```
