proxyapi 0.4.4

What is Proxelar?

Proxelar sits between your application and the internet, giving you full visibility into every HTTP/HTTPS request — and the power to transform it on the fly with Lua.

Your App  ──►  Proxelar :8080  ──►  Internet
                    │
              Inspect · Modify · Mock

Useful for debugging APIs, reverse engineering third-party services, testing mobile apps, injecting headers, mocking responses, or automating any request/response transform without touching your source code.

Features

• Lua scripting — write on_request / on_response hooks to modify, block, or mock traffic at runtime
• HTTPS interception — automatic CA generation and per-host certificate minting
• Forward & reverse proxy — CONNECT tunneling or upstream URI rewriting
• Three interfaces — terminal (stdout), interactive TUI (ratatui), web GUI (axum + WebSocket)
• WebSocket inspection — connections captured alongside HTTP traffic; browse frames by direction, opcode, and payload
• Column-scoped filtering — time:14:, proto:https, method:POST, host:github, path:/api, status:404, type:json, size:1KB, duration:slow or plain text search
• Easy CA install — visit http://proxel.ar through the proxy to download and install the root cert

Installation

Homebrew (macOS / Linux)

brew install proxelar

Cargo

cargo install proxelar

Docker / Podman

# 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 won't get browser warnings.

Quick Start

1. Start the proxy

proxelar

2. Install the CA certificate

Visit http://proxel.ar while routing traffic through the proxy — it serves the cert with install instructions.
Or install it manually: ~/.proxelar/proxelar-ca.pem

3. Configure your system proxy

Set HTTP and HTTPS proxy to 127.0.0.1:8080 in your OS, browser, or tool of choice.

Traffic will start appearing in the TUI immediately.

Interfaces

proxelar              # interactive TUI (default)
proxelar -i terminal  # plain terminal output
proxelar -i gui       # web GUI at http://localhost:8081

Usage

proxelar -m reverse --target http://localhost:3000   # 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

Scripting

Write Lua scripts to intercept and transform traffic. Define on_request and/or on_response hooks:

function on_request(request)
    -- request.method, request.url, request.headers, request.body
    -- Return the request to forward it (modified or not)
    -- Return a response table to short-circuit: { status = 403, headers = {}, body = "Blocked" }
    -- Return nil to pass through unchanged
end

function on_response(request, response)
    -- response.status, response.headers, response.body
    -- Return the response (modified or not), or nil to pass through
end

local blocked = { "ads%.example%.com", "tracker%.example%.com" }

function on_request(request)
    for _, pattern in ipairs(blocked) do
        if string.find(request.url, pattern) then
            return { status = 403, headers = {}, body = "Blocked" }
        end
    end
end

function on_response(request, response)
    response.headers["Access-Control-Allow-Origin"] = "*"
    response.headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, DELETE, OPTIONS"
    return response
end

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": "Test User"}',
        }
    end
end

More examples in examples/scripts/ — header injection, cookie stripping, HTML rewriting, request body modification, traffic logging, and more. Full scripting API reference at proxelar.micheletti.io.

Documentation

Latest release: Proxelar 0.4.4 — Body Capture Limits for Large Traffic

Full documentation at proxelar.micheletti.io:

• Getting started
• Forward & reverse proxy modes
• Lua scripting API reference
• CA certificate installation

Contributing

Contributions are welcome. Open an issue or submit a pull request.

License

MIT