Introduction

Proxelar is a man-in-the-middle proxy written in Rust. It intercepts, inspects, and optionally modifies HTTP and HTTPS traffic flowing between a client and a server.

What can it do?

• Inspect traffic — see every request and response in real time, including headers and bodies
• Intercept HTTPS — automatic CA certificate generation and per-host certificate minting
• Modify traffic with Lua scripts — write on_request and on_response hooks to transform, block, or mock traffic at runtime
• Forward and reverse proxy — use as a system proxy (forward) or put it in front of your service (reverse)
• Three interfaces — interactive TUI, plain terminal output, or web GUI

Architecture

Proxelar is built as a three-crate Rust workspace:

• proxelar-cli — the CLI binary with three interface modes
• proxyapi — the core proxy engine, usable as a standalone library
• proxyapi_models — shared request/response data types

The proxy engine is built on hyper 1.x, rustls 0.23, and tokio. HTTPS interception uses OpenSSL for certificate generation and rustls for TLS termination. Lua scripting is powered by mlua with a vendored Lua 5.4.

Installation

Homebrew (macOS / Linux)

brew install proxelar

From crates.io

cargo install proxelar

This builds and installs the proxelar binary. Lua 5.4 and OpenSSL are vendored and compiled from source, so no system dependencies are required beyond a Rust toolchain.

From source

git clone https://github.com/emanuele-em/proxelar.git
cd proxelar
cargo build --release

The binary is at target/release/proxelar.

Without Lua scripting

If you don’t need scripting and want a smaller build:

cargo install proxelar --no-default-features

Requirements

• Rust 1.94 or later
• Works on Linux, macOS, and Windows

Quick Start

1. Start the proxy

proxelar

This starts Proxelar in forward proxy mode with the interactive TUI on 127.0.0.1:8080.

2. Install the CA certificate

Configure your system or browser proxy to 127.0.0.1:8080, then visit http://proxel.ar through the proxy. The page provides direct certificate downloads and platform-specific installation instructions.

Alternatively, manually install ~/.proxelar/proxelar-ca.pem. See CA Certificate for all platforms.

3. Browse through the proxy

All HTTP and HTTPS traffic now flows through Proxelar and appears in the TUI. Press ? for the full keybinding reference, or see Interfaces for details on the TUI, terminal, and web GUI modes.

4. Try a Lua script

Create a file called script.lua:

function on_request(request)
    request.headers["X-Proxied-By"] = "proxelar"
    return request
end

Run Proxelar with the script:

proxelar --script script.lua

Every request passing through the proxy now has the X-Proxied-By header injected.

CA Certificate

Proxelar intercepts HTTPS traffic by generating a local Certificate Authority (CA) and minting per-host leaf certificates on the fly. For this to work, your system must trust the Proxelar CA.

Automatic generation

On first run, Proxelar generates a 4096-bit RSA CA certificate and private key in ~/.proxelar/:

• ~/.proxelar/proxelar-ca.pem — CA certificate
• ~/.proxelar/proxelar-ca.key — CA private key (mode 0600)

If these files already exist, they are reused.

Certificate download server

The easiest way to install the CA is through the built-in download server. With the proxy running, visit:

http://proxel.ar

This page provides:

• Direct download links for PEM and DER formats
• Platform-specific installation instructions for macOS, Linux, Windows, iOS, and Android

Manual installation

macOS

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/.proxelar/proxelar-ca.pem

Linux (Debian/Ubuntu)

sudo cp ~/.proxelar/proxelar-ca.pem /usr/local/share/ca-certificates/proxelar.crt
sudo update-ca-certificates

Linux (Fedora/RHEL)

sudo cp ~/.proxelar/proxelar-ca.pem /etc/pki/ca-trust/source/anchors/proxelar.pem
sudo update-ca-trust

Windows

certutil -addstore -f "ROOT" %USERPROFILE%\.proxelar\proxelar-ca.pem

Firefox

Firefox uses its own certificate store. Go to Settings > Privacy & Security > Certificates > View Certificates > Import, and select ~/.proxelar/proxelar-ca.pem.

Custom CA directory

Use --ca-dir to store the CA files in a different location:

proxelar --ca-dir /path/to/certs

Per-host certificate caching

Leaf certificates are cached in memory (up to 1,000 hosts). Repeated connections to the same host reuse the cached certificate instead of generating a new one.

Forward Proxy

Forward proxy is the default mode. Clients send their traffic to Proxelar, which forwards it to the destination server. This is the standard setup for inspecting browser or application traffic.

Usage

proxelar

Configure your client (browser, curl, application) to use 127.0.0.1:8080 as the HTTP/HTTPS proxy.

How it works

1. The client sends a request to the proxy
2. For HTTPS, the client sends a CONNECT request. Proxelar upgrades the connection and detects the protocol:
   • TLS ClientHello — generates a leaf certificate for the target host, terminates TLS, and inspects the decrypted traffic
   • Plain HTTP (e.g., GET prefix) — serves the stream directly
   • Unknown protocol — tunnels the raw TCP connection without inspection
3. For plain HTTP, the request is forwarded directly
4. Lua on_request / on_response hooks run at each step (if a script is loaded)

Examples

# Start forward proxy on default port
proxelar

# Custom port and bind address
proxelar -p 9090 -b 0.0.0.0

# With terminal output instead of TUI
proxelar -i terminal

# With a Lua script
proxelar --script block_ads.lua

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

Reverse Proxy

In reverse proxy mode, Proxelar sits in front of a backend service. Clients connect to Proxelar directly (without proxy configuration), and all requests are forwarded to the specified target.

This is useful for debugging local APIs, injecting headers, mocking endpoints, or testing how your frontend handles modified responses.

Usage

proxelar -m reverse --target http://localhost:3000

Clients connect to http://127.0.0.1:8080 and Proxelar forwards everything to http://localhost:3000.

How it works

1. The client sends a request to 127.0.0.1:8080
2. Proxelar rewrites the URI to the target (preserving path and query)
3. The Host header is updated to match the target
4. Lua on_request / on_response hooks run (if a script is loaded)
5. The response is returned to the client

Examples

# Reverse proxy to a local service
proxelar -m reverse --target http://localhost:3000

# Custom port (clients connect to 4000, forwarded to 3000)
proxelar -m reverse --target http://localhost:3000 -p 4000

# With a Lua script that injects auth headers
proxelar -m reverse --target http://localhost:3000 --script auth_dev.lua

# With web GUI
proxelar -m reverse --target http://localhost:3000 -i gui

Common use cases with scripting

Inject authentication

function on_request(request)
    request.headers["Authorization"] = "Bearer dev-token-12345"
    return request
end

Add security headers

function on_response(request, response)
    response.headers["Strict-Transport-Security"] = "max-age=31536000"
    response.headers["X-Content-Type-Options"] = "nosniff"
    response.headers["X-Frame-Options"] = "DENY"
    return response
end

Simulate errors

function on_request(request)
    if string.find(request.url, "/api/payments") then
        return {
            status = 500,
            headers = { ["Content-Type"] = "application/json" },
            body = '{"error": "Internal Server Error"}',
        }
    end
end

Intercept & Modify Traffic

Intercept mode pauses requests mid-flight so you can inspect, edit, and decide what to do before they reach the server.

How it works

When intercept is on, every request is held until you act on it. Nothing is forwarded automatically. When intercept is off, traffic flows through normally (still captured and displayed).

TUI

Toggle intercept

Press i to turn intercept on or off. The status bar shows a red INTERCEPT badge when active.

Act on a request

When a request arrives it appears as a ⏸ row. Navigate to it with j/k, then:

Edit inline

Press e to open the editor. The full raw HTTP request is shown and fully editable — method, URI, headers, and body.

POST /api/login HTTP/1.1
host: example.com
content-type: application/json

{"user":"alice","pass":"secret"}

• Arrow keys / Home / End — move the cursor
• Enter — insert a new line
• Backspace / Delete — delete characters
• Esc — finish editing (request stays held, ready to forward)
• f — forward (with your edits applied)
• d — drop
• Esc (again, when not typing) — discard your edits

Binary bodies — if the original body is not valid UTF-8 the editor shows a ⚠ warning. The content is displayed lossily; edits may corrupt binary data.

Web GUI

Click the ⏸ Intercept: OFF button in the toolbar to enable intercept. The button turns red and shows a pending-request count.

Pending requests appear in the table with an amber left border. Click a row to open the editor panel:

• Edit the method, URI, headers, and body directly
• Click Forward to send (with any edits you made)
• Click Drop (504) to block the request
• Press Ctrl+Enter as a keyboard shortcut for Forward
• Press Esc or × to close the panel without acting (request stays pending)

Turning intercept off

Press i (TUI) or click the intercept button (web) again. All pending requests are forwarded immediately so clients do not hang.

Lua Scripting

Proxelar supports Lua scripts that hook into the request/response lifecycle. You can modify headers, rewrite URLs, block requests, mock API responses, transform bodies, and more — all without recompiling or changing your application.

Running a script

proxelar --script my_script.lua

The script is loaded once at startup. It applies to all traffic flowing through the proxy, in both forward and reverse modes.

Writing a script

A script defines one or both of these global functions:

function on_request(request)
    -- Called before forwarding the request to the upstream server.
    -- Modify and return the request, return a response to short-circuit,
    -- or return nil to pass through unchanged.
end

function on_response(request, response)
    -- Called before returning the response to the client.
    -- Modify and return the response, or return nil to pass through unchanged.
end

Both functions are optional. If a function is not defined, traffic passes through unchanged.

Request hook

on_request receives a request table and can return one of three things:

• The request table — forward it (modified or not)
• A response table (with a status field) — short-circuit and return that response directly, without contacting the upstream server
• nil (or no return) — pass through unchanged

function on_request(request)
    -- Pass through logging only
    if string.find(request.url, "blocked%.com") then
        return { status = 403, headers = {}, body = "Blocked" }  -- short-circuit
    end

    request.headers["X-Custom"] = "value"
    return request  -- forward modified request
end

Response hook

on_response receives both the request (for context) and the response. It can modify and return the response, or return nil to pass through.

function on_response(request, response)
    response.headers["X-Proxy"] = "proxelar"
    return response
end

Error handling

Script errors are caught, logged, and the request passes through unchanged. A buggy script can never crash the proxy. Check the log output (set RUST_LOG=debug for details) to see script errors.

Feature flag

Lua scripting is behind the scripting feature flag, enabled by default. To build without it:

cargo install proxelar --no-default-features

API Reference

Request table

The on_request function receives a table with these fields:

All fields are readable and writable. Modify them in place and return the table to forward the modified request.

Response table

The on_response function receives two arguments:

1. request — a table with method and url fields (for context)
2. response — a table with these fields:

Short-circuit response

To respond immediately without contacting the upstream server, return a table with a status field from on_request:

return {
    status = 403,
    headers = { ["Content-Type"] = "text/plain" },
    body = "Forbidden",
}

The presence of the status field is what distinguishes a response from a modified request.

Headers

Headers are Lua tables mapping lowercase header names to values.

Single-value headers are plain strings:

request.headers["content-type"]     -- "application/json"
request.headers["authorization"]    -- "Bearer token123"

Multi-value headers (like Set-Cookie) are arrays:

response.headers["set-cookie"]      -- {"session=abc", "lang=en"}

When setting headers, both forms are accepted:

-- Single value (most common)
request.headers["x-custom"] = "value"

-- Multiple values
response.headers["set-cookie"] = {"a=1", "b=2"}

-- Remove a header
request.headers["cookie"] = nil

Return values

on_request

on_response

Available Lua standard libraries

Scripts run in a standard Lua 5.4 environment with access to:

• string — pattern matching, formatting, manipulation
• table — array/table operations
• math — mathematical functions
• os.date(), os.time(), os.clock() — time functions
• print() — output to proxy stdout
• tostring(), tonumber(), type() — type conversion

Script Examples

All examples below are complete, working scripts. They are also available in the examples/scripts/ directory.

Add headers to requests

function on_request(request)
    request.headers["X-Forwarded-By"] = "proxelar"
    request.headers["X-Request-Time"] = os.date("%Y-%m-%dT%H:%M:%S")
    return request
end

Block domains

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

function on_request(request)
    for _, pattern in ipairs(blocked) do
        if string.find(request.url, pattern) then
            return {
                status = 403,
                headers = { ["Content-Type"] = "text/plain" },
                body = "Blocked by Proxelar: " .. request.url,
            }
        end
    end
end

Mock API endpoints

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", "email": "test@example.com"}',
        }
    end
end

Redirect requests to a different host

function on_request(request)
    request.url = string.gsub(request.url, "old%-api%.example%.com", "new-api.example.com")
    return request
end

Inject CORS headers

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

Log traffic to stdout

function on_request(request)
    print(string.format("[REQ] %s %s", request.method, request.url))
end

function on_response(request, response)
    local ct = response.headers["content-type"] or "unknown"
    local size = #response.body
    print(string.format("[RES] %s %s -> %d (%s, %d bytes)",
        request.method, request.url, response.status, ct, size))
end

Inject authentication

local TOKEN = "Bearer my-dev-token-12345"

function on_request(request)
    if string.find(request.url, "api%.example%.com") then
        request.headers["Authorization"] = TOKEN
    end
    return request
end

Modify JSON response bodies

function on_response(request, response)
    local ct = response.headers["content-type"] or ""
    if not string.find(ct, "application/json") then return end

    if string.sub(response.body, 1, 1) == "{" then
        response.body = '{"proxied":true,' .. string.sub(response.body, 2)
    end
    return response
end

Inject a banner into HTML pages

function on_response(request, response)
    local ct = response.headers["content-type"] or ""
    if not string.find(ct, "text/html") then return end

    local banner = '<div style="position:fixed;top:0;left:0;right:0;'
        .. 'background:#ff6b35;color:white;text-align:center;'
        .. 'padding:4px;z-index:99999;font-size:12px;">'
        .. 'Proxied by Proxelar</div>'

    response.body = string.gsub(response.body, "<body>", "<body>" .. banner, 1)
    return response
end

Only allow GET and HEAD

function on_request(request)
    if request.method ~= "GET" and request.method ~= "HEAD" then
        return {
            status = 405,
            headers = {
                ["Content-Type"] = "text/plain",
                ["Allow"] = "GET, HEAD",
            },
            body = "Method " .. request.method .. " not allowed by proxy policy",
        }
    end
end

Strip tracking cookies

local tracking_cookies = { "fbp", "_ga", "_gid", "fr", "datr" }

function on_request(request)
    local cookie = request.headers["cookie"]
    if not cookie then return end

    local parts = {}
    for pair in string.gmatch(cookie, "([^;]+)") do
        pair = string.match(pair, "^%s*(.-)%s*$")
        local name = string.match(pair, "^([^=]+)")
        local dominated = false
        for _, tc in ipairs(tracking_cookies) do
            if name == tc then dominated = true; break end
        end
        if not dominated then table.insert(parts, pair) end
    end

    if #parts > 0 then
        request.headers["cookie"] = table.concat(parts, "; ")
    else
        request.headers["cookie"] = nil
    end
    return request
end

Modify POST request bodies

function on_request(request)
    if request.method ~= "POST" then return end
    local ct = request.headers["content-type"] or ""

    if string.find(ct, "application/json") and string.sub(request.body, 1, 1) == "{" then
        request.body = '{"injected_by":"proxelar",' .. string.sub(request.body, 2)
    end
    return request
end

CLI Reference

proxelar [OPTIONS]

Options

Environment variables

Examples

# Default: forward proxy with TUI
proxelar

# Terminal output on custom port
proxelar -i terminal -p 9090

# Web GUI accessible from the network
proxelar -i gui -b 0.0.0.0

# Reverse proxy with script
proxelar -m reverse --target http://localhost:3000 --script auth.lua

# Forward proxy with logging script
proxelar --script log_traffic.lua

# Capture only the first 1 MiB of large bodies while streaming traffic through
proxelar --body-capture-limit 1048576

Interfaces

Proxelar provides three interface modes, all showing the same live traffic data.

TUI (default)

proxelar
# or
proxelar -i tui

An interactive terminal interface built with ratatui. Shows a table of all captured requests and WebSocket connections with nine columns: time, protocol, method, host, path, status, content-type, size, and duration.

Key bindings

The detail panel shows the full request or response including headers and body. For WebSocket connections the Frames tab lists every captured frame with its direction (↑ client→server, ↓ server→client), opcode, size, and payload preview.

Filtering

Press / to enter filter mode. Plain text searches across method and URL. Use column:value to scope the search to a single column:

Column names are case-insensitive. Press Enter to apply, Esc to cancel.

Terminal

proxelar -i terminal

Prints each request/response as a colored line to stdout. Useful for quick inspection or when piping output to other tools.

Output includes timestamp, HTTP method (color-coded), URL, status code, and response size.

Web GUI

proxelar -i gui

Opens a web interface at http://127.0.0.1:8081 (configurable with --gui-port). Built with axum and WebSocket for real-time streaming.

Features:

• Interactive request table with live updates — nine columns: Time, Proto, Method, Host, Path, Status, Type, Size, Duration
• WebSocket inspection — connections appear as live/closed rows; click to browse frames
• Unified column:value search bar — same syntax as the TUI filter (e.g. status:404, type:json, proto:https)
• Click a row to view full request/response detail
• Intercept mode — pause requests, edit method/URI/headers/body, then forward or drop
• JSON pretty-printing in the detail view
• Light and dark mode (follows system preference)

To make the web GUI accessible from other machines:

proxelar -i gui -b 0.0.0.0