Capturing traffic¶
Quena is a proxy: applications send their requests to Quena, and Quena forwards them to the server (or to the next proxy) and records both directions.
Start and stop¶
- The capture switch at the left of the toolbar shows Capturing or Paused. Click it,
press
F12, use Capture → Capture Traffic, or typestart/stopin the command field. - While the system proxy is being changed, the switch shows Starting… or Stopping….
- Stopping the capture also closes open client connections, tunnels and WebSockets (after the request in flight), so nothing more is recorded.
- Settings → General → Capture traffic on startup (on by default) decides whether Quena captures right after it starts.
Start a browser or terminal with Quena¶
Without changing the system proxy, Quena can start programs whose traffic goes through it: the globe button next to the capture switch, Capture → Start Browser…, Capture → Open Terminal and Capture → Start Agent…. Capturing starts if it is off.
- Browsers. Quena finds Chrome, Edge, Brave, Vivaldi, Chromium and Firefox and starts the
chosen one with its own profile (kept in Quena's data folder, so logins stay) and Quena as
proxy. Your normal browser windows are not affected.
- Chrome, Edge, Brave, Vivaldi and Chromium accept Quena's certificates in that profile
without the root certificate being trusted by the system
(
--ignore-certificate-errors-spki-list). Chromium shows a notice about this "unsupported command-line flag"; it applies to this profile only. Requests tolocalhostgo through Quena too. - Firefox uses the system's trusted roots: trust the Quena root certificate first (HTTPS and devices).
- Start with URL… opens the dialog to enter a start page.
- Chrome, Edge, Brave, Vivaldi and Chromium accept Quena's certificates in that profile
without the root certificate being trusted by the system
(
-
Terminal. A new terminal window (Terminal.app, Windows Terminal or
cmd, or the Linux terminal found) whose shell has:HTTP_PROXY,HTTPS_PROXY,ALL_PROXY(also in lower case) pointing to Quena, andQUENA_PROXYwith the same address for your own scripts;NO_PROXYandno_proxywith the hosts of Settings → Connections → Do not capture (empty when there are none, which also clears what your shell may set);NODE_EXTRA_CA_CERTSandCODEX_CA_CERTIFICATEwith Quena's root certificate (Node.js programs such as Claude Code and Gemini CLI, and Codex, add it to their own roots);- on macOS and Linux also
SSL_CERT_FILE,REQUESTS_CA_BUNDLE,CURL_CA_BUNDLE,GIT_SSL_CAINFO,AWS_CA_BUNDLE,PIP_CERTandCARGO_HTTP_CAINFOwith a bundle of the system's roots plus Quena's (quena-ca-bundle.pemin the data folder).
On Windows, curl, Git and Python use the system store: trust the Quena root certificate there. Java has its own trust store; import the certificate with
keytool -importcert -cacerts -alias quena -file quena-root-ca.pem. -
AI agent. Start Agent… (or Start Claude Code / Start Codex in the globe button's menu) opens such a terminal and runs the agent's command in it (
claude,codex,geminior any other command). On macOS and Linux it runs in an interactive login shell ($SHELL -l -i -c …), so what your.zprofileor.zshrcadds toPATH(nvm, for example) is found; when the agent ends, a fresh login shell stays open. Its calls to the model and to MCP servers over HTTP go through Quena and show in the Agents panel. HTTPS decryption must be on.Node.js agents such as Claude Code and Gemini CLI ignore the macOS and Windows system proxy, so Act as system proxy alone does not catch them: start them with Start Agent…, or set the variables above yourself. More in Get agent traffic into Quena.
AI agents can start a browser or a terminal too, with the MCP tools launch_browser and
open_terminal (a plain terminal; that tool takes no command, so it cannot start an agent).
Listen port¶
Quena listens on port 8866 by default (127.0.0.1:8866). Change it in
Settings → Connections → Listen port. The status bar shows the address Quena listens on.
System proxy¶
With Settings → Connections → Act as system proxy while capturing (on by default), Quena registers itself as the system proxy while it captures, so browsers and most desktop applications send their traffic through it automatically.
| Platform | What Quena changes |
|---|---|
| macOS | the proxy of all network services (changed at once) |
| Windows | the proxy of the current user |
| Linux | the GNOME or KDE Plasma proxy setting that browsers follow |
Quena's own exceptions while it captures: on macOS and Linux *.local and 169.254/16
(Bonjour names and link-local addresses, as in the macOS defaults); on Windows none. In
particular, Windows' Don't use the proxy server for local (intranet) addresses stays
off, so intranet and VPN hosts without a dot (http://appserver/) are recorded too. The
exceptions of the previous proxy are not lost: those hosts still go direct from Quena
instead of through the upstream proxy (see Upstream proxy and PAC).
The previous proxy setting is saved and restored when you quit — and, if Quena ever crashes, at the next start. On Windows, logging off or shutting down while Quena runs restores it as well.
Tools that ignore the system proxy¶
Command-line tools usually do not follow desktop proxy settings. Point them at Quena explicitly:
curl -x http://127.0.0.1:8866 https://example.com
export HTTP_PROXY=http://127.0.0.1:8866
export HTTPS_PROXY=http://127.0.0.1:8866
For HTTPS, such tools must also trust Quena's root certificate — see HTTPS and devices.
Clients that take no proxy at all (a backend with a fixed API URL, a container, a webhook sender, gRPC) can call a reverse proxy port of Quena instead: it forwards everything to one target (or one per path) and records it. Clients that speak SOCKS, and connections a firewall redirects, have ports of their own.
Upstream proxy and PAC¶
In a corporate network, Quena forwards to the proxy you used before. The options are in Settings → Connections:
| Option | Meaning |
|---|---|
| Chain to the previous system proxy (upstream gateway) | On by default: the proxy that was active before Quena took over becomes Quena's upstream. |
| Manual upstream proxy | host:port of a proxy to use instead. A manual upstream overrides PAC. |
| Bypass upstream for | Hosts that go direct instead of through the upstream. Default: localhost;127.0.0.1;::1;*.local. Patterns: *.corp.example, 10.1.*, networks (10.0.0.0/8, 169.254/16) and <local> for names without a dot. With the chained system proxy, its exceptions apply as well. |
| Use the system proxy auto-config (PAC) script | On by default: evaluate the PAC script the OS proxy settings point to. |
| PAC URL or file | A PAC script of your own (http://…/proxy.pac, file://… or a local path). Empty means the system PAC. |
PAC notes:
FindProxyForURL(url, host)is evaluated once per host and cached.https://PAC URLs are not fetched — download the file and enter its path instead.- The download must finish within 15 s and be at most 1 MB. A script that hangs or fails
falls back to
DIRECTfor that lookup, so a broken PAC file never stalls the app.
If the upstream proxy asks for authentication (407), Quena can answer it — see
Automatic authentication.
Remote computers and devices¶
Remote connections are off by default. To capture a phone, a tablet, a VM or another computer:
- Enable Settings → Connections → Allow remote computers to connect (or click the button in Capture → Connect Device…).
- Optionally restrict who may connect with Allowed remote networks: CIDR ranges or
addresses separated by
;(e.g.192.168.1.0/24; 10.0.0.5). Empty means local subnets. - Configure the device to use your computer's address and port 8866 as its HTTP proxy.
Capture → Connect Device… walks you through this with a QR code — see Phones, tablets and VMs.
Which application sent a request¶
Quena attributes each request to the process that sent it. The name appears in the Process column (hidden by default in the Quena layout, visible in Classic) and in the inspector header.
| Platform | Process attribution |
|---|---|
| macOS | ✅ |
| Windows | ✅ |
| Linux | ✅ for processes of your own user (via /proc) |
Use it to narrow the list:
- Status bar → process scope: All processes, Browsers only, Non-browsers or Remote clients.
- Filters → Client Process: the same choices, plus Show only traffic from and
Hide traffic from (e.g.
chrome; java). - Right-click a session → Filter Now → Hide this Process / Show only this Process.
- Right-click → Select → Same Process.
Streaming and storage¶
- Stream (toolbar toggle, on by default) passes response bodies to the client as they arrive. Turned off, Quena buffers the response first.
- Keep (toolbar button with the history icon) keeps only the newest 100, 200, 500, 1,000 or 10,000 sessions; the default is Keep all sessions.
- Bodies are stored on disk, not in memory, so large downloads do not fill the RAM. The status bar shows how much the capture uses and how much disk space is free. The limits are in Settings → Bodies & Storage; see Settings.