DocsConnect clients

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-profiles or ~/.var/app/<id>/data/akev-profiles).
  • Proxied through Akev, localhost included (--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 (localhost included). 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 certutil is installed, Akev adds the CA to the profile's certificate database before it launches Firefox. Otherwise, the first tab opens http://akev.cert/ca.crt and Firefox asks whether to trust it: tick Trust this CA to identify websites and click OK. You do this once per profile. Where to get certutil.

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_OPTIONS is extended rather than replaced, so flags like -Xmx stay;
  • in Windows PowerShell 5.x, also sets the proxy for Invoke-WebRequest and Invoke-RestMethod, which ignore the variables there;
  • defines akev-off and 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_HOME or $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:

  1. 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.
  2. Opens a USB tunnel with adb reverse tcp:<port> tcp:<port>, so the device reaches the proxy at 127.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 uses 10.0.2.2 instead, and a phone uses this computer's network address, which needs Allow other devices.
  3. 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:
xml
<!-- 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 shell already runs as root (you ran adb root, an emulator image without Google Play, a userdebug build) or the device has su (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": false in 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:

bash
adb shell settings put global http_proxy :0

The 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.

  1. Join the Wi-Fi network this computer is on.
  2. 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.
  3. 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 open http://<address>:<port>/ca.mobileconfig directly. Once the proxy is set, http://akev.cert opens the same page.
  4. Open Settings → Profile Downloaded and tap Install.
  5. 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:

  1. The proxy address: on this computer (127.0.0.1:8000 by default) and on your network. The same port accepts HTTP proxy requests (with CONNECT for 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.
  2. 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).
  3. 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:

bash
adb shell settings put global http_proxy <address>:<port>
adb shell settings put global http_proxy :0    # undo

Then 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:

bash
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 IMAGE

The panel shows the exact paths for your machine.

  • Env files live in docker/ in the data directory: akev-docker.env (proxy at host.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.pem and 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.internal to 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) or host.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 at 127.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 .app bundle, 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's bin folder (VS Code's bin/code) and Slack's slack.exe stub 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-server and --proxy-bypass-list=<-loopback>, for the Chromium side of the app, localhost included;
  • --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:

bash
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.

Type to search guides, the CLI and the API.