Proxelar is a scriptable MITM proxy with a terminal, a GUI and a REST API

A proxy for looking at your own traffic

Proxelar is described as 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. The data path is a straightforward picture: your app talks to the proxy on port 8080, and the proxy talks to the upstream service.

The stated use cases are the ones a developer actually has. Debugging APIs, inspecting browser or mobile traffic, testing WebSocket clients, injecting headers, mocking local services, replaying captured requests, and automating request and response transforms with Lua.

What makes it different from the usual proxy is the scripting and the number of surfaces. Lua hooks named on_request and on_response can rewrite, block, short-circuit or mock traffic. Interactive intercept lets you pause a request and edit the method, URI, headers or body before forwarding, dropping or replaying it. HTTPS interception works through local certificate authority generation, per-host certificates and a built-in certificate install page. Rules and automation cover mapping local and remote URLs, mocking and redirecting requests, hot-reloading Lua, and driving the bearer-token REST API.

The design intent is explicit: terminal-first, scriptable, Rust-native, and usable either as a command line tool or as the proxyapi library. That is a deliberate positioning away from the heavyweight interception suites, aimed at the developer who wants to see a request, change one field and get on with the day.

The licence is MIT, the crate is on crates.io, there is a Homebrew formula, a winget package, a Docker and Podman image, and the documentation lives at proxelar.micheletti.io.

Four interfaces over one protocol core

The interfaces are chosen with the command line:

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

The TUI is the default and the primary one, with the browser GUI and a headless REST API as alternatives for a shared machine or for automation. The same instance serves both the proxy port and the interface port, which is why the container image exposes 8080 and 8081.

Underneath, the project is a Cargo workspace with four members: proxelar-cli, proxelar-proto, proxyapi and proxyapi_models, with the CLI as the default member. The protocol core is native rather than built on an off-the-shelf HTTP stack, and the README states that HTTP/1, HTTP/2 and a feature-gated HTTP/3 are supported without Hyper in the proxy data path. That is the kind of decision that shows up in latency and in behaviour under load, and it is why the crate is a proxy first and a library second.

Two of the modes in the option list show how much of the surface is not a plain HTTP proxy. There is a reverse mode that puts the proxy in front of a local service, and a WireGuard mode with its own endpoint option, alongside the SOCKS5 mode, the forward mode, DNS inspection and rewrite, and a fixed-target raw UDP mode. Six capture modes in total, which is a reminder that this is a network tool as much as an HTTP one.

The body size cap is also worth knowing about, because it is the kind of option that saves a machine from an out of memory kill when a client downloads a large asset through the proxy. The option caps captured and editable body bytes, and there is a separate option to trust an extra upstream certificate authority from a path.

Lua hooks are where the automation lives

The scripting model is the part that turns a proxy into a tool you can put in a test suite. A script defines on_request and on_response functions, and returning a table from on_request short-circuits the request with your own status, headers and body. This is the mock case:

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

The script is then pointed at with the --script option, and in reverse mode the proxy stands in front of a local service:

proxelar -m reverse --target http://localhost:3000 --script mock_user.lua

A request to the proxy for the mocked path then returns the local response instead of reaching the upstream service.

The examples/scripts/ directory in the repository shows the range: auth injection, CORS headers, HTML rewriting, cookie stripping, redirects, traffic logging and JSON body edits. Those are the tasks that otherwise end up as bespoke middleware in a service, and here they are scripts you can point a proxy at.

Two details make the scripting usable rather than a toy. Lua can be hot-reloaded, so you can edit a rule while traffic is flowing. And the project offers a more structured distribution format for these scripts, called portable addons, which use a versioned proxelar-addon.json manifest with semantic versioning, declared hooks and native code requirements, and SHA-256 coverage for every package file. The verification story is the interesting part: Proxelar rejects path traversal, symlinks, undeclared files and tampered content before installation or execution. The commands are:

proxelar addon verify ./examples/addons/header-tagger
proxelar addon install ./examples/addons/header-tagger
proxelar addon list
proxelar --addon header-tagger

Manifest-free script directories remain supported for local development, so the strict format is only needed when you are shipping a rule set to someone else.

HTTPS interception means a root certificate on your machine

To read HTTPS traffic, Proxelar generates a local certificate authority, issues per-host certificates from it, and serves the root certificate together with install instructions on a page you reach at http://proxel.ar while routing traffic through the proxy. The quick start is three steps: start the proxy with proxelar, point your client at 127.0.0.1:8080 as both the HTTP and the HTTPS proxy, and then visit the certificate page to install the CA.

The smoke test is two curl commands, one plain and one over TLS:

curl -x http://127.0.0.1:8080 http://httpbin.org/get
curl -x http://127.0.0.1:8080 https://httpbin.org/get

This is where the honest caveat belongs. Installing a root certificate on a machine means every application on that machine now trusts whoever holds the key to it, including the proxy in front of you. On a laptop where you are the only user and the proxy runs only while you are debugging, that is a reasonable trade. On a shared workstation, on a machine that visits untrusted sites, or where a browser profile is shared with a work environment, it is a meaningful risk.

The mitigations the tooling offers are worth knowing. The upstream trust option adds an extra certificate authority to trust rather than removing verification, which is the safe way to reach a server with a private CA. The body capture limit bounds how much of a payload is held in memory and on disk. The Docker documentation notes that the -v ~/.proxelar:/root/.proxelar mount reuses your existing trusted CA certificate so you do not get browser warnings after trusting the CA once, and that the container always keeps its state at /root/.proxelar, with a different mount required if XDG_CONFIG_HOME points elsewhere.

The same caution applies to the interactive intercept and the Lua hooks: they let you rewrite and block traffic, which is exactly what a debugging tool should do and exactly what you do not want enabled on a proxy that is left running for other users of the network.

Captures you can keep, replay and hand over

Sessions are portable in a way that matters for team work. You can save and reload native captures, and you can import and export HAR files, curl commands and raw HTTP files, with secret redaction applied. The redaction is the part that makes sharing a capture reasonable, since a captured session full of bearer tokens is the classic way a debugging tool leaks credentials into a chat channel.

The WebSocket support is narrower but useful. Connections are captured and frames can be browsed by direction, opcode and payload preview, which covers the questions a WebSocket client developer usually has, which is what arrives, in what order, and with what opcode.

For storage the project offers native sessions and the standard HAR format, and the export formats include curl, so a captured request can be pasted back into a terminal as a repeatable command. That is the bridge between the proxy and the rest of a debugging session: capture once, then work on the request in isolation.

The rules and automation layer sits on top of the same primitives: mapping local and remote URLs so a request for one host is served by another, mocking and redirecting requests, and the REST API, which is bearer-token protected, for driving the proxy from a script or a test harness. The GUI can also launch an isolated Chromium proxy profile, which is a small but practical detail, since it keeps the debugging browser's proxy configuration separate from your everyday browsing profile.

Installing it, and the quality gates behind the releases

Installation covers the usual ground. Homebrew for macOS and Linux, winget for Windows with the package id EmanueleMicheletti.Proxelar, and Cargo:

brew install proxelar
cargo install proxelar

The published container image supports linux/amd64 and linux/arm64, with Lua and HTTP/3 enabled, and Docker and Podman select the matching architecture automatically:

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

The image is built from a Rust 1.97.1 slim builder stage that compiles the proxelar binary with the http3 feature, and the runtime stage is a Debian bookworm slim image with only the certificate authorities installed.

The repository also shows a level of engineering discipline that is worth reading. The justfile defines a test recipe that runs the full workspace suite, a recipe for a single crate, a scripting-gated recipe that runs the proxyapi scripting tests with a vendored Lua, a recipe that runs the suite with default features disabled, lint via cargo fmt and cargo clippy, a docs recipe that matches the CI warnings-as-errors gate, and dependency recipes for cargo-deny and cargo-audit. The coverage targets are explicit, with a minimum of 80 percent of lines overall and 90 percent for the core coverage target.

Licence checks and advisories are part of the same local gate, backed by a deny.toml in the repository root, and the project carries a SECURITY.md, a CHANGELOG.md generated with a cliff.toml, a ROADMAP.md, a code of conduct, a contributing guide and an AGENTS.md.

The release history shows steady work: v0.5.1 on 2026-07-31, v0.6.0 on 2026-09-13 and v0.6.1 on 2026-09-22. The last push was on 2026-10-16 and the repository is not archived, so the tool is actively developed and still below version 1.0, which is the usual signal that command line flags and file formats may still move.

Editorial conclusion

Proxelar suits a developer who debugs third party APIs, writes WebSocket clients, or needs to mock or rewrite traffic for tests, and it suits a team that wants the same inspection surface available from a terminal, a browser and a headless REST API. It is the wrong choice if your environment forbids installing a trusted root certificate, since HTTPS interception depends on it, and a poor match if you want a full security testing suite, because the project positions itself as a lightweight alternative to one. Before adopting, install the root certificate only on a machine where you control the traffic, check that the upstream trust option does not disable verification for hosts you do not control, and read the addon manifest rules if you plan to run third party scripts.

Frequently asked questions

Official sources

1. emanuele-em/proxelar on GitHub
2. License: MIT
3. Project website
4. README
5. Releases