Capture
Connect clients
Open Connect (Ctrl/⌘ 4) and pick a card. Some cards launch a client that is already set
up (browsers, terminals, Electron apps). Others configure a device or your operating system,
or give you the settings to enter yourself.
For HTTPS, a client must also trust Akev's certificate authority (CA). Clients that Akev launches trust it automatically. For everything else, see Certificates.
Everything that is active shows up at the top of the Connect page, with a button to stop it, and Stop all when there is more than one. Browser and Fresh Terminal cards also have a Stop button of their own.
At a glance
| Card | What Akev changes | How to undo it |
|---|---|---|
| Chrome, Edge, Brave and other Chromium browsers | Nothing outside Akev: the browser gets its own profile in Akev's data directory | Stop, or quit Akev: the browser closes |
| Firefox | Nothing outside Akev: a dedicated profile in Akev's data directory | Stop, or quit Akev: Firefox closes |
| Fresh Terminal | Nothing: the variables exist only in that terminal | Close the window. Stop, or quitting Akev, closes it |
| Existing Terminal | Variables in the one shell session you paste the command into | akev-off in that terminal, or close it |
| Android Device via ADB | The device's global HTTP proxy, a USB tunnel, a certificate file in Download; on rooted devices and emulators, a system CA until reboot |
Stop next to the device, or quit Akev. After a crash, the next start undoes it; a reboot removes the system CA |
| iOS via Manual Setup | Nothing: you change the device's settings | Turn the Wi-Fi proxy off and remove the profile |
| iOS Simulator (macOS) | The Akev CA as a trusted root in booted simulators | Erase the simulator or reset its keychain; Stop only forgets it |
| Anything | Nothing: it shows the settings to use | — |
| Docker & Podman Containers | Two CA files in /tmp of a container you attach to |
Detach, or quit Akev |
| Electron Application | Nothing outside Akev | Quit next to the app, or quit Akev: the app closes |
| System Proxy | Your operating system's proxy settings | Switch it off, or quit Akev. After a crash, the next start restores them |
Certificates you install yourself (on a phone, in a system trust store) stay until you remove them. See remove trust again.
Chromium-family browsers
Chrome, Chromium, Brave, Microsoft Edge, Opera and Vivaldi on Linux,
macOS and Windows, and Arc on macOS and Windows (experimental: Arc may ignore some flags).
Akev looks for them on PATH, in the standard install locations and in Snap and Flatpak on
Linux, in /Applications and ~/Applications on macOS, and in Program Files and AppData on
Windows.
Click Launch. Akev starts a separate instance of the browser:
- With its own profile, in
profiles/<browser>in Akev's data directory. Your normal profile is untouched, and logins in the Akev profile are kept between sessions. Snap and Flatpak browsers keep the profile inside their sandbox (~/snap/<name>/current/akev-profilesor~/.var/app/<id>/data/akev-profiles). - Proxied through Akev,
localhostincluded (--proxy-server,--proxy-bypass-list=<-loopback>). - Trusting Akev's CA by its public key (
--ignore-certificate-errors-spki-list), in this instance only. No trust store is changed. - Quieter: no first-run page, default-browser check or what's-new page, and some background traffic (optimisation hints and models, domain reliability reports) is switched off, so it doesn't fill Traffic.
Click Launch again to open another window in the same instance. If the instance still runs with an old proxy address or an old CA (the port changed, or you regenerated the CA), Akev restarts it instead.
Stop closes every window of the browser's Akev profile. Quitting Akev does the same.
Firefox
Firefox, Firefox Developer Edition and Firefox Nightly. Firefox has its own
certificate store and ignores Chromium's switches, so Akev prepares a dedicated profile in
profiles/<id> in the data directory:
- A generated
user.js, rewritten on every launch, sets a manual HTTP and HTTPS proxy with no exceptions (localhostincluded). It also turns off DNS over HTTPS, lets Firefox use CAs from the system store (security.enterprise_roots.enabled), and switches off telemetry, studies, captive-portal checks, automatic updates and first-run pages. - If NSS
certutilis installed, Akev adds the CA to the profile's certificate database before it launches Firefox. Otherwise, the first tab openshttp://akev.cert/ca.crtand Firefox asks whether to trust it: tick Trust this CA to identify websites and click OK. You do this once per profile. Where to getcertutil.
Firefox runs as a separate instance, so Akev can't open a second window in it: while it runs, Launch only tells you so. If it is running with an old proxy address or CA, Akev restarts it. Stop, or quitting Akev, closes it.
Fresh Terminal
Fresh Terminal opens a new terminal window. The command-line tools, scripts and runtimes you start in it use Akev and trust its CA: curl, git, npm and yarn, Node.js, Python and pip, Ruby and Bundler, Go, Rust and cargo, Deno, Java, the AWS and Google Cloud CLIs, and more.
| Platform | Terminal Akev opens |
|---|---|
| Linux | $TERMINAL if it is set. Otherwise your desktop's own terminal (Ptyxis, GNOME Console or GNOME Terminal on GNOME, Konsole on KDE, Xfce Terminal on Xfce), then xdg-terminal-exec, then the first one installed of a list of common terminals (kitty, Alacritty, WezTerm, foot, Ghostty, Tilix, Terminator, XTerm…). |
| macOS | iTerm if it is installed, otherwise Terminal. Both start a login shell. |
| Windows | Windows Terminal with PowerShell, otherwise a PowerShell window, otherwise Command Prompt. |
The window runs a small launcher script from terminal/ in the data directory. It sets the
proxy and CA variables, prints Akev interception enabled, deletes itself and starts your
shell. Which variables.
For Java, Akev first builds a trust store with keytool if it can find one, waiting up to 10
seconds, so JVMs started in the terminal trust the CA too. See
Java.
To stop, close the window. Stop on the card, and quitting Akev, close the shells of the
terminals Akev opened, as closing their windows would. Programs started with nohup or
setsid, and tmux sessions, keep running.
Existing terminal
Existing Terminal gives you one command to paste into a terminal that is already open. Pick your shell: bash, zsh, fish or PowerShell on Linux and macOS, or PowerShell, Command Prompt or Git Bash on Windows.
The command downloads a setup script from Akev's local API (/api/setup/terminal) and runs it
in the current shell: with eval in bash and zsh, source in fish and iex in PowerShell.
In Command Prompt, it saves the script to %TEMP%\akev-setup.cmd and runs it with call.
- The API token travels in a request header. curl reads it from standard input, and Command
Prompt uses a temporary file in
%TEMP%that it deletes afterwards, so the token never appears on a command line that other users could read. - The download ignores any proxy that is already set, so the token never passes through Akev itself.
The script then:
- saves the current value of every variable it is about to change, as
__AKEV_OLD_<NAME>. It only saves once, so running the command twice is harmless; - sets the same proxy and CA variables as a Fresh Terminal.
JAVA_TOOL_OPTIONSis extended rather than replaced, so flags like-Xmxstay; - in Windows PowerShell 5.x, also sets the proxy for
Invoke-WebRequestandInvoke-RestMethod, which ignore the variables there; - defines
akev-offand prints Akev interception enabled.
Only that session, and the programs you start from it afterwards, are affected. Nothing is installed.
PowerShell's web cmdlets check HTTPS against the system trust store, except PowerShell 6 and later on Linux. To intercept their HTTPS traffic, trust the CA system-wide.
To undo, run akev-off in the same terminal. Every variable gets its previous value back,
and variables that weren't set before are removed. Closing the terminal works too. In Command
Prompt, akev-off is a doskey macro that runs terminal\akev-off.cmd from the data
directory.
Android over ADB
Android Device via ADB sets up a phone or emulator over USB, with no Wi-Fi settings to change.
You need:
- adb, from the Android SDK platform-tools: on
PATH, in$ANDROID_HOMEor$ANDROID_SDK_ROOT, or in Android Studio's default SDK folder. - A device with USB debugging on. On the device, open Settings → About phone and tap Build number seven times, then turn on Settings → System → Developer options → USB debugging. Connect the cable and accept the Allow USB debugging? prompt. Emulators from Android Studio need no setup.
The panel lists every device adb devices reports, with hints for devices that aren't ready
(unauthorized: accept the prompt on the device; no permissions: missing udev rules on
Linux).
Click Intercept next to a device. Akev:
- Copies the CA certificate (DER) to the device as
/sdcard/Download/akev-ca.crt. On a rooted device or an emulator, it also trusts the CA as a system CA until the device restarts; see system trust on rooted devices and emulators. - Opens a USB tunnel with
adb reverse tcp:<port> tcp:<port>, so the device reaches the proxy at127.0.0.1:<port>. The tunnel is lost when you replug the cable, so Akev re-creates it every 5 seconds while the device is intercepted. If the tunnel can't be set up, an emulator uses10.0.2.2instead, and a phone uses this computer's network address, which needs Allow other devices. - Sets the device's global HTTP proxy:
adb shell settings put global http_proxy 127.0.0.1:<port>. Akev first records the device in a journal file, so it can undo the change even after a crash.
Unless the device got the system CA, install the certificate on it: Settings → Security &
privacy → More security settings → Encryption & credentials (the wording varies by vendor) →
Install a certificate → CA certificate. Confirm the warning and pick
Download/akev-ca.crt.
This installs a user CA, and not every app trusts one:
- Chrome trusts user CAs. Firefox only does with its own setting turned on.
- Apps targeting Android 7 or later trust user CAs only if their network security config allows it. For your own debug builds:
<!-- res/xml/network_security_config.xml -->
<network-security-config>
<debug-overrides>
<trust-anchors>
<certificates src="user" />
</trust-anchors>
</debug-overrides>
</network-security-config>On a device without root, apps that don't opt in reject Akev's certificate and their HTTPS requests fail.
System trust on rooted devices and emulators
When Akev can run commands as root on the device, it also makes the CA a system CA, which release apps trust too, without changing the system partition:
- Root access means
adb shellalready runs as root (you ranadb root, an emulator image without Google Play, a userdebug build) or the device hassu(Magisk and the like; the device may ask you to allow it). Akev doesn't root anything itself. - Akev puts a temporary copy of the system certificate store, with its CA added, over the real
one. On Android 14 and later, whose CAs come from the Conscrypt module
(
/apex/com.android.conscrypt/cacerts), it does the same for the running apps and for apps started later. - It lasts until the device restarts. Stop removes it for apps started afterwards; apps already running keep trusting the CA until they restart, and a reboot removes it everywhere.
- To keep it a user CA only, pass
"systemTrust": falsein the interceptor's options (API, CLI or MCP; see below).
This is new in 0.1.0 and has been tested with emulators, not yet with physical phones. Apps that pin their certificates still reject Akev's.
To undo, click Stop next to the device, or quit Akev. Akev resets the proxy
(settings put global http_proxy :0), removes the USB tunnel, and removes the system CA if it
added one (a reboot does too). If Akev crashed or was
killed, the next start resets the device as soon as it is connected again. A device proxied by
another Akev that is still running is left alone. If a device has no internet after Akev
quits, run this yourself:
adb shell settings put global http_proxy :0The user certificate you installed, and the file in Download, stay on the device until you
remove them.
Without USB, set the device up by hand over Wi-Fi, or use WireGuard mode (Pro).
iPhone and iPad
iOS via Manual Setup sends the device's traffic through Akev over Wi-Fi. The device must be on the same network as this computer, Allow other devices must be on (on the Connect page, or in Settings → Proxy), and your firewall must let other devices reach the proxy port.
- Join the Wi-Fi network this computer is on.
- Settings → Wi-Fi → tap ⓘ next to the network → Configure Proxy → Manual. Enter the server and port from the panel (this computer's network address and the proxy port), leave Authentication off, and save.
- Scan the QR code in the panel with the camera, or open the setup page
(
http://<address>:<port>/) in Safari. Tap iPhone / iPad / Mac, then Allow. You can also openhttp://<address>:<port>/ca.mobileconfigdirectly. Once the proxy is set,http://akev.certopens the same page. - Open Settings → Profile Downloaded and tap Install.
- Settings → General → About → Certificate Trust Settings → turn on full trust for the Akev CA. Without this step, HTTPS fails.
The profile, akev-ca.mobileconfig, contains only the Akev CA as a trusted root, and you can
remove it at any time. Downloading it again for the same CA gives the same profile, not a
second one.
To undo, set Configure Proxy back to Off. Otherwise the device loses its connection once Akev stops. Remove the profile in Settings → General → VPN & Device Management.
Apps that pin their certificates don't work through any proxy.
To capture every app on the device, on any network, with no Wi-Fi proxy to set, use WireGuard mode (Pro) instead.
iOS Simulator (macOS)
iOS Simulator trusts the Akev CA in the simulators that are running, in one click: it runs
xcrun simctl keychain <device> add-root-cert with Akev's CA for each booted simulator (or
the one you pick). It needs Xcode's command-line tools, and only lists simulators that are
booted.
Simulators use your Mac's network settings, so their traffic reaches Akev through the system proxy: turn that on too (or point the app under test at the proxy itself).
simctl can't remove a single root certificate, so Stop only forgets the simulator: the CA
stays trusted in it until you erase the simulator (Device → Erase All Content and
Settings) or reset its keychain (xcrun simctl keychain <device> reset). This interceptor is
new in 0.1.0 and hasn't been tried with every Xcode version yet.
Other devices on your network
Phones, tablets, VMs and other computers can use the proxy too. First turn on Allow other devices on the Connect page (or Settings → Proxy → Allow other devices). The proxy then listens on all network interfaces.
By default it then serves this computer and devices on private networks (your LAN, Docker, Tailscale), and refuses everyone else; a device it serves can't reach services that only listen on this computer. When a device connects for the first time, Akev shows New device connected with a Block button. To limit it further, list the allowed devices or set a username and password in Settings → Proxy → Who can connect: see who can connect. Devices allowed to use the proxy see its traffic, so turn Allow other devices off on networks you don't trust.
The Anything card collects what a client needs:
- The proxy address: on this computer (
127.0.0.1:8000by default) and on your network. The same port accepts HTTP proxy requests (withCONNECTfor HTTPS) and, by default, SOCKS4 and SOCKS5. There is also a PAC URL,http://<address>:<port>/proxy.pac(also served as/wpad.dat), for tools that only take one. The PAC script sends everything to Akev and falls back to a direct connection when Akev can't be reached. - The certificate: the path of the CA file, the path of a combined bundle (your system's roots plus the Akev CA), Download PEM and Download DER (.crt).
- Per-tool guides: environment variables, Node.js, Python, Java, Go, Rust, curl, iOS and Android.
Every device can also use the setup page, which the proxy serves itself: open
http://<address>:<port>/ (the Phone & tablet setup card on the Connect page shows it as a
QR code), or http://akev.cert/ from a device that already uses the proxy. The page shows the
proxy settings, offers the certificate as iPhone / iPad / Mac (configuration profile),
Android / Firefox (DER, served so that Android and Firefox offer to install it) or
Other (PEM), and has trust steps for iOS, Android, macOS, Windows, Linux and Firefox.
Android over Wi-Fi: in the Wi-Fi network's settings, set the proxy to Manual with the address and port. Or set it over ADB, and undo it the same way:
adb shell settings put global http_proxy <address>:<port>
adb shell settings put global http_proxy :0 # undoThen download ca.crt from the setup page and install it as described in Android over
ADB.
Other computers and VMs: point their system or app proxy at the network address, and trust the CA with the instructions for each OS.
Docker and Podman
Docker & Podman Containers works with the docker and podman command-line tools, found
on PATH or in their usual install locations. A docker command that is really Podman's
compatibility wrapper counts as Podman. The panel lists the running containers of every engine
Akev can reach.
A running container's main process keeps the environment it was started with. Akev can't re-point it without recreating the container, and doesn't recreate containers for you. So there are two ways in:
New containers
New containers in the panel shows ready-made commands. Pick docker run, podman run,
Compose or, on Linux, Host network. For example, Docker on Linux:
docker run --rm -it --add-host=host.docker.internal:host-gateway \
--env-file ~/.local/share/akev/docker/akev-docker.env \
-v ~/.local/share/akev/ca.pem:/akev/ca.pem:ro,z \
-v ~/.local/share/akev/ca-bundle.pem:/akev/ca-bundle.pem:ro,z IMAGEThe panel shows the exact paths for your machine.
- Env files live in
docker/in the data directory:akev-docker.env(proxy athost.docker.internal),akev-podman.env(host.containers.internal) and, on Linux,akev-hostnet.env(127.0.0.1, for--network host). They contain the same variables as a terminal, with the CA at/akev/ca.pemand the bundle at/akev/ca-bundle.pem, both mounted read-only. Java gets the proxy settings but no trust store. When the proxy requires a username and password, the env files for bridge networks carry them in the proxy address (http://user:pass@host:port), since those containers connect from another address; the host-network file doesn't need them. - Docker Desktop (macOS, Windows) forwards
host.docker.internalto this computer, so the default proxy settings work. - Bridge networks on Linux: containers reach this computer through
host.docker.internal(Docker, with--add-host …:host-gateway) orhost.containers.internal(Podman). The proxy must accept network connections, so turn on Allow other devices; Docker's networks are private addresses, which the default who can connect setting allows. - Host network on Linux (
--network host): the container shares this computer's network and reaches the proxy at127.0.0.1. This works with the default, local-only proxy. - The Compose snippet adds the env file, the host alias and the two certificate volumes to a service.
Containers started with these settings are marked Attached in the list.
Running containers
Click Attach next to a container. Akev copies the CA and the bundle into the container
(/tmp/akev-ca.pem and /tmp/akev-ca-bundle.pem) and shows a docker exec -it -e … sh (or
podman exec) command. Run it to get a shell inside the container whose programs use Akev and
trust its CA (with the proxy's username and password in it, when one is set). The container's
main process is not affected.
The shell reaches the proxy at 127.0.0.1 in host-network containers, at the bridge gateway
for Docker on Linux (172.17.0.1 if it can't be read), and at host.docker.internal or
host.containers.internal otherwise. If copying fails, for example on a read-only file
system, only plain HTTP from that shell is intercepted.
Detach, or quitting Akev, deletes the copied files from the container.
Electron apps
Electron Application launches an Electron app (Slack, VS Code, Discord, Postman, Figma, your own app…) with all its traffic going through Akev. Quit the app first if it is running. Enter the full path and click Launch:
- macOS: the
.appbundle, e.g./Applications/Slack.app. - Linux and Windows: the app's main executable, the one next to
resources/app.asar, e.g./usr/share/code/code. A launcher in the app'sbinfolder (VS Code'sbin/code) and Slack'sslack.exestub on Windows are resolved to the real executable.
The panel suggests common paths on macOS and Linux, and remembers the last ones you used. Akev checks that the path really is an Electron app (following symlinks) and refuses scripts and other programs. It starts the app with:
--proxy-serverand--proxy-bypass-list=<-loopback>, for the Chromium side of the app,localhostincluded;--ignore-certificate-errors-spki-list, to trust the CA without changing any trust store;- the terminal's proxy and CA environment variables, for the app's Node.js main process.
Over the API, args can add a few harmless switches, and nothing else: --disable-gpu,
--enable-logging (or =stderr), --ozone-platform=wayland|x11,
--ozone-platform-hint=auto|wayland|x11, --lang=<language tag> and
--force-device-scale-factor=<0.25–5>. Switches that run commands, open debugging ports or
load code are refused.
Single-instance apps hand a second launch to the copy that is already running, which doesn't have Akev's settings. If the app's launcher exits straight away, Akev says so: quit the app completely and launch it again.
Quit next to a running app closes it. Stopping the Electron Application interceptor at the top of the Connect page, or quitting Akev, closes every app Akev launched.
AI agents can't launch Electron apps unless you allow it, because captured traffic could
otherwise talk an agent into starting programs. Start Akev with akev start --mcp-allow-launch,
or use akev mcp --allow-launch when akev mcp runs its own instance. Without that, launch the
app from the Connect page. See MCP.
System proxy
System Proxy points your operating system's proxy setting at Akev. Turn on Use Akev as the system proxy in the panel. Browsers and most desktop apps follow this setting, so their traffic shows up in Traffic. Many command-line tools and runtimes read environment variables instead: use a Fresh Terminal for those.
For HTTPS, these apps must also trust the CA system-wide. The panel shows the commands for your OS; see Certificates. Akev never changes a trust store itself.
| OS | What Akev changes |
|---|---|
| Linux (GNOME) | org.gnome.system.proxy with gsettings: manual mode, HTTP and HTTPS proxy host and port, and localhost, 127.0.0.0/8 and ::1 as exceptions. Used whenever gsettings and GNOME's proxy schema are installed. Akev reads the values back and only counts a change once it stuck. |
| Linux (KDE Plasma) | [Proxy Settings] in kioslaverc, written with kwriteconfig6 or kwriteconfig5: a manual HTTP and HTTPS proxy, with localhost,127.0.0.1,::1 as exceptions. Only in a KDE session. |
| macOS | For every enabled network service (Wi-Fi, Ethernet…), with networksetup: the web proxy and the secure web proxy, and automatic proxy configuration (PAC) is turned off. |
| Windows | Your user's Internet settings (HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings): ProxyEnable, ProxyServer and ProxyOverride (localhost;127.*;[::1]). A PAC AutoConfigURL is removed while Akev is active, because it would take precedence. Running apps are notified of the change. |
Local addresses stay direct, so Akev's own UI and API keep working. On Linux without either backend, the card is unavailable.
Restoring your settings. Before it changes anything, Akev saves the previous value of
every setting it touches to a backup file, system-proxy-backup.json in the data directory.
Switching the proxy off, or quitting Akev, puts those values back and deletes the file. If Akev
crashed or was killed, the next start restores them, and retries anything that couldn't be
restored. A backup that belongs to another Akev that is still running is left alone.
If the proxy port changes while the system proxy is on, the panel warns that the system still points at the old address and offers to update it.
More ways to capture
Pro feature. Running JVMs, WireGuard mode and transparent capture need Akev Pro or its 14-day trial.
- Running JVMs: attach to a Java, Kotlin or Scala app that is already running, without restarting it.
- WireGuard mode: scan one QR code to capture every app on a phone, tablet or second computer, on any network the device can reach this computer from.
- Transparent capture (Linux): capture programs that ignore proxy settings, per app, per user or for the whole machine.
From the command line and API
Every card is an interceptor with an id, which you can use from the CLI (while Akev is running) and the API:
akev intercept list # ids, and whether each is available
akev intercept chrome --options '{"url": "https://example.com"}' # launch
akev intercept android-adb --options '{"deviceId": "emulator-5554"}'
akev intercept stop chrome # undo| Id | Options |
|---|---|
chrome, chromium, brave, edge, opera, vivaldi, arc |
url: the start page (an http://, https://, about: or file:// URL). quiet: true also turns off background networking, sync and component updates. |
firefox, firefox-developer, firefox-nightly |
url |
fresh-terminal |
terminal: which terminal to open (the ones Akev found are in the interceptor's metadata) |
existing-terminal |
none: the result contains the commands for each shell |
android-adb |
deviceId: needed when several devices are connected. systemTrust: false keeps the CA a user CA on rooted devices and emulators |
ios, manual |
none: they return the setup steps and addresses |
ios-simulator |
udid: one booted simulator (without it, every booted simulator) |
docker |
containerId to attach to a running container (without it, you get the snippets), engine (docker or podman) |
electron |
path (required), args. To stop a single app, pass its pid or path. |
system-proxy |
none |
jvm, wireguard and transparent-linux are covered in their own guides.
Pro feature. Over MCP, activating interceptors (
akev_activate_interceptor) needs Akev Pro or its 14-day trial. Listing and stopping them is free.