proxelar

Proxelar

Rust-based MITM proxy for intercepting and transforming HTTP/HTTPS traffic via Lua scripting. Provides TUI, terminal, and web GUI interfaces. Installed via brew install proxelar.

Category

Infrastructure Operations

Modes

Mode	Command	When to use
Forward proxy	proxelar	Intercept outbound traffic from any app configured to use 127.0.0.1:8080
Reverse proxy	proxelar -m reverse --target http://localhost:3000	Inspect traffic to a local dev server without configuring the client
Web GUI	proxelar -i gui	Agent-visible network inspector at http://localhost:8081 — screenshot for visual feedback
Scripted	proxelar --script path/to/hook.lua	Automated request/response transformation via Lua hooks

Combine modes: proxelar -m reverse --target http://localhost:3000 -i gui --script scripts/log_to_jsonl.lua

CLI Reference

Flag	Description	Default
-i, --interface	terminal, tui, gui	tui
-m, --mode	forward, reverse	forward
-p, --port	Listening port	8080
-b, --addr	Bind address	127.0.0.1
-t, --target	Upstream target (required for reverse mode)	--
--gui-port	Web GUI port	8081
--ca-dir	CA certificate directory	~/.proxelar
-s, --script	Lua script for request/response hooks	--

Lua Scripting

Define on_request and/or on_response hooks:

function on_request(request)
    -- request.method, request.url, request.headers, request.body
    -- Return request to forward (modified or not)
    -- Return 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 response (modified or not), or nil to pass through
end

Bundled Lua Scripts

Run any script with proxelar --script ~/.claude/skills/proxelar/scripts/<name>.lua

Script	Purpose
log_to_jsonl.lua	Log request/response pairs as JSONL to ~/.proxelar/traffic.jsonl
capture_for_eval.lua	Capture LLM API calls (Anthropic/OpenAI/Gemini) as structured JSONL for eval pipelines
mock_api.lua	Template for mocking API endpoints — edit the mocks table
inject_cors.lua	Add permissive CORS headers to all responses
latency_inject.lua	Add configurable artificial latency to matching URLs
block_telemetry.lua	Block analytics and telemetry domains

Agent Integration

Agent-Browser Bridge

Route agent-browser traffic through Proxelar for combined page + network visibility:

# Terminal 1: start proxelar in reverse mode
proxelar -m reverse --target http://localhost:3000 -i gui --script ~/.claude/skills/proxelar/scripts/log_to_jsonl.lua &

# Terminal 2: navigate through proxelar, then snapshot
agent-browser --proxy "http://127.0.0.1:8080" open http://127.0.0.1:8080 && agent-browser snapshot

Agent Visual Feedback via Web GUI

Start Proxelar with -i gui, then screenshot http://localhost:8081 via Claude-in-Chrome or agent-browser to give the agent network-layer visibility into what the application is doing.

Frametime + Network Correlation

Inject scripts/frametime_bench.js into a running page via mcp__claude-in-chrome__javascript_tool or agent-browser eval. Read console output with pattern p50 to get percentile data. Run alongside latency_inject.lua to correlate network latency with rendering jank.

CA Certificate

First run auto-generates ~/.proxelar/proxelar-ca.pem. Trust it once:

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

Or visit http://proxel.ar through the proxy for guided install.

Gotchas

• Check port 8080 is free before starting: lsof -i :8080
• Reverse mode requires --target — CLI errors immediately if omitted
• Lua scripts are loaded once at startup; edit requires restart
• Web GUI binds to 127.0.0.1:8081 by default; use --addr 0.0.0.0 for remote access
• WebSocket traffic passes through but Lua hooks only fire on HTTP request/response, not individual WS frames
• TUI and Web GUI support interactive request inspection, editing, and dropping — not just passive viewing