Capture
Certificates
To show you HTTPS traffic, Akev decrypts it. It answers each HTTPS connection with a certificate for the requested host, signed on the fly by its own certificate authority (CA). A client accepts those certificates only if it trusts the Akev CA.
Browsers, terminals and Electron apps that Akev launches from Connect trust it automatically, and nothing on your system changes. Everything else needs the CA installed once: the operating system, Firefox, Java, phones. Akev never changes your system's trust stores itself. It gives you the commands, and the commands to undo them.
Akev's CA
Every installation generates its own CA the first time it starts. It is created on your machine, and its private key never leaves it.
It lives in Akev's data directory, which the desktop app and the CLI share:
| OS | Data directory |
|---|---|
| Linux | ~/.local/share/akev ($XDG_DATA_HOME/akev if that is set) |
| macOS | ~/Library/Application Support/akev |
| Windows | %LOCALAPPDATA%\akev |
ca.pem: the CA certificate (PEM). This is the file clients trust.ca.key: its private key (PKCS#8 PEM). On Linux and macOS it is readable only by you (mode0600), and Akev tightens the permissions if they are looser. On Windows Akev gives it an access list that only your account can use, whenever it writes or loads it. Anyone with this key can intercept HTTPS traffic of every client that trusts your CA, so never share it.
--data-dir (or AKEV_DATA_DIR) points the CLI at another data directory, with its own CA.
akev start --ephemeral without --data-dir uses a temporary directory, so it generates a new
CA on every run.
What's in it
- Key: ECDSA P-256.
- Subject:
O=Akev, OU=<id>, CN=Akev CA. The OU is a random 8-character id, so you can tell installations, and successive CAs, apart in a trust store. - Constraints: a CA that can't issue other CAs (path length 0), allowed to sign certificates.
- Validity: from a day before it was created (to tolerate clock skew) for 10 years.
The certificates Akev makes for each host use ECDSA P-256 keys and are valid for at most 397
days, and never beyond the CA's own expiry. They name the host (or IP address) and, for names
with three or more labels, a wildcard for the parent domain too (api.example.com also covers
*.example.com). Akev caches the last 2,048.
Expiry
A CA lasts 10 years, and Akev never replaces one your devices trust on its own. When fewer
than 60 days are left, the status bar, akev ca show, the akev start banner and the MCP
akev_status tool warn you, with the date; once it has expired they say that HTTPS
interception fails until you replace it. Regenerate it when it suits you,
and trust the new one on your devices.
Akev does make a new CA by itself when it starts and ca.pem or ca.key is missing, can't be
read as a certificate or key, the two don't match, or the certificate isn't valid yet (the
clock was wrong when it was made). The previous files are kept as ca.pem.bak and
ca.key.bak. Any other problem reading the files, such as a permission error, stops Akev with
an error instead, so a passing problem never replaces a CA your devices trust.
In the app
Settings → Certificates (Ctrl/⌘ ,) shows the CA under Certificate authority:
| Field | What it is |
|---|---|
| Subject | The CA's name, with your installation's id |
| SHA-256 | The certificate's fingerprint, to compare with what a device shows |
| SPKI (base64) | The SHA-256 of its public key, the pin Chromium-family browsers launched by Akev use |
| Android file name | <hash>.0, the name of this CA in Android's system store (Akev uses it on rooted devices and emulators) |
| Valid | First and last day of validity |
| File | The path of ca.pem |
Download PEM and Download DER (.crt) save a copy of the certificate. Regenerate… makes a new CA; see below.
Below it, Trust on this computer adds the CA to your operating system's certificate store in one click, and Trust by hand shows the commands to do it yourself; see trust the CA system-wide. When the main store doesn't trust the CA, the status bar says CA not trusted (it checks again when the window gets focus).
The akev ca command
akev ca path # print the path of ca.pem
akev ca show [--json] # subject, path, fingerprints, validity
akev ca export FILE # write the certificate to FILE (PEM)
akev ca export FILE --der # the same in DER (.crt / .cer, e.g. for Android or Windows)
akev ca regenerate # make a new CAakev ca show prints the subject, path, SHA-256 and SPKI fingerprints, the OpenSSL
subject_hash_old (the Android file name) and the validity, in yellow when fewer than 60 days
remain.
With Akev running, the commands use its data directory and its API. Without it, they work on the data directory directly, and create a CA if there is none yet.
Over the API: GET /api/ca, GET /api/ca/cert.pem, GET /api/ca/cert.der and
POST /api/ca/regenerate. See Settings & certificate.
Regenerate the CA
Regenerate when the CA is about to expire, when its key may have leaked, or to start over
with a fresh CA. In Settings → Certificates, click Regenerate… and confirm. Or run
akev ca regenerate.
Akev creates the new key and certificate first, then replaces ca.pem and ca.key, keeping the
old ones as ca.pem.bak and ca.key.bak (and putting them back if the new files can't be
written), and restarts the proxy with the new CA on the same port and address.
Everything that trusted the old CA stops trusting Akev until you install the new one: system trust stores, Firefox profiles, Java trust stores, phones and other devices. Before you regenerate, remove the old CA where you installed it by hand. The removal commands below that take the certificate file only work with the file you trusted.
Clients Akev launches get the new CA when you launch them again. A browser that is still running with the old CA is restarted the next time you launch it from Connect. Quit Electron apps before you launch them again, and open new terminals.
Trust the CA system-wide
Clients that Akev launches trust its CA on their own. Clients that Akev doesn't launch, and apps that follow the system proxy, need the CA in your system's trust store.
In one click
Settings → Certificates → Trust on this computer lists the stores Akev can manage on this computer, with whether each one trusts the CA (Trusted, Not trusted or Unknown, checked for real, not remembered). Click Trust next to one; Akev asks you to confirm, then the operating system asks too:
| OS | Store | What confirms it |
|---|---|---|
| macOS | Your login keychain, as a trusted root for your account (Safari, Chrome, Edge, curl and apps that use the system's TLS) | macOS's password dialog |
| Windows | Your account's Trusted Root store (Edge, Chrome, .NET and most Windows apps) | Windows's security warning |
| Linux | The distribution's CA bundle, with p11-kit's trust anchor (Fedora, RHEL, Arch, openSUSE) or update-ca-certificates (Debian, Ubuntu), through pkexec |
Your desktop's password dialog (polkit) |
| Linux | The NSS database Chrome, Chromium, Brave, Edge and Vivaldi read (~/.pki/nssdb) |
Akev's confirmation only; needs certutil (nss-tools on Fedora, libnss3-tools on Debian and Ubuntu) |
Akev never does this on its own, and AI agents can't do it over MCP: installing a root certificate is always your click. Remove next to a trusted store takes the CA out again. Restart apps that were already open so they notice the change. Firefox keeps its own store; see Firefox.
When a store can't be managed from Akev (no pkexec, no certutil, or no supported tool),
the row says why; use the commands below instead. Over the API:
GET /api/ca/trust reports the stores, and POST or DELETE /api/ca/trust with
{"store": "user" | "system" | "nss"} installs or removes the CA.
By hand
Settings → Certificates → Trust by hand shows the commands for your OS, with the path of
your certificate filled in. The commands below use "$(akev ca path)" for that path.
Remove the CA again when you're done; see remove trust again.
Linux
Most Linux tools read the distribution's CA bundle.
Fedora, RHEL, Arch, openSUSE (p11-kit):
sudo trust anchor --store "$(akev ca path)"
# remove:
sudo trust anchor --remove "$(akev ca path)"Debian, Ubuntu:
sudo cp "$(akev ca path)" /usr/local/share/ca-certificates/akev-ca.crt
sudo update-ca-certificates
# remove:
sudo rm /usr/local/share/ca-certificates/akev-ca.crt
sudo update-ca-certificates --freshChrome and Chromium on Linux read their own NSS database (~/.pki/nssdb) for your user. This
needs NSS certutil (the libnss3-tools package on Debian and Ubuntu). Browsers that Akev
launches don't need it.
certutil -d sql:$HOME/.pki/nssdb -A -t C,, -n 'Akev CA' -i "$(akev ca path)"
# remove:
certutil -d sql:$HOME/.pki/nssdb -D -n 'Akev CA'Firefox keeps its own store: see Firefox. Java, Node.js and Python may ignore the system bundle: see Java and command-line tools.
macOS
Safari, Chrome, curl and apps using URLSession read the Keychain.
For your user only (asks for your password):
security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db "$(akev ca path)"
# remove:
security remove-trusted-cert "$(akev ca path)"
security delete-certificate -Z <SHA-256> ~/Library/Keychains/login.keychain-dbFor all users (System keychain):
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "$(akev ca path)"
# remove:
sudo security remove-trusted-cert -d "$(akev ca path)"
sudo security delete-certificate -Z <SHA-256> /Library/Keychains/System.keychain<SHA-256> is the certificate's SHA-256 fingerprint without the colons (akev ca show prints
it with colons). Settings → Certificates fills it in for you.
Or use Keychain Access: open ca.pem with it and add it to the login keychain, double-click
the Akev certificate → Trust → When using this certificate: Always Trust. To remove
it, select the certificate in Keychain Access and delete it.
On a Mac you can also install the configuration profile from the setup page (iPhone / iPad / Mac), then install it in System Settings → Privacy & Security → Profiles and set the certificate to Always Trust.
Java, Node.js and Python ignore the Keychain: see Java and command-line tools.
Windows
Edge, Chrome, .NET and most native apps use the Windows certificate store.
For your user, in Command Prompt (Windows asks you to confirm):
certutil -user -addstore Root "%LOCALAPPDATA%\akev\ca.pem"In PowerShell, use "$env:LOCALAPPDATA\akev\ca.pem" for the path. To remove it again, in
PowerShell:
Get-ChildItem Cert:\CurrentUser\Root | Where-Object Subject -like "*CN=Akev CA*" | Remove-ItemThis removes every Akev CA from your user's store, including those of earlier CAs.
Or use the certificate manager: double-click a .crt copy of the certificate (Download DER
(.crt) in Settings → Certificates, or akev ca export akev-ca.crt --der) → Install
Certificate… → Current User (or Local Machine for all users, which needs
administrator rights) → Place all certificates in the following store: Trusted Root
Certification Authorities → Finish. To remove it, run certmgr.msc → Trusted Root
Certification Authorities → Certificates, and delete the Akev certificate.
Java, Node.js and Python ignore the Windows store: see Java and command-line tools.
Firefox
Firefox keeps its own certificate store.
Firefox launched from Akev needs nothing from you if NSS certutil is installed: Akev
adds the CA to that profile's certificate database, and replaces an older Akev CA there. Akev
finds certutil on PATH, and on macOS also in Homebrew's nss. On Debian and Ubuntu it is
in libnss3-tools. Without certutil, the first tab asks you to trust the CA once per
profile; see Firefox.
Your own Firefox profile:
- Settings → Privacy & Security → Certificates → View Certificates…
- Authorities → Import… → choose the PEM file (
ca.pem, or a downloaded copy). - Tick Trust this CA to identify websites → OK.
If that Firefox already uses Akev as its proxy, opening http://akev.cert/ca.crt shows the same
trust dialog.
On Windows and macOS, Firefox can use the system store instead: set
security.enterprise_roots.enabled to true in about:config, and trust the CA
system-wide. Firefox profiles that Akev launches already have this
setting.
To remove the CA, select it under Authorities and click Delete or Distrust….
Java
Java uses its own trust store (cacerts), not the Keychain or the Windows store, and on Linux
it may ignore the system bundle too.
Terminals from Akev. When Akev finds keytool (in $JAVA_HOME/bin, or on PATH), it
builds a trust store in the data directory, java/akev-truststore.p12: a copy of the JDK's
default cacerts plus the Akev CA (PKCS#12, password changeit). New and existing terminals
then set JAVA_TOOL_OPTIONS, which every JVM reads:
-Dhttp.proxyHost,-Dhttp.proxyPort,-Dhttps.proxyHost,-Dhttps.proxyPortand an empty-Dhttp.nonProxyHosts, solocalhostis captured too;- an empty
-Djdk.http.auth.tunneling.disabledSchemes, which allows Basic authentication throughCONNECTtunnels; -Djavax.net.ssl.trustStore,-Djavax.net.ssl.trustStorePassword=changeitand-Djavax.net.ssl.trustStoreType=PKCS12, once the trust store exists.
In an existing terminal, your own JAVA_TOOL_OPTIONS flags are kept. The trust store belongs
to one CA: after you regenerate, Akev builds a new one the next time a terminal needs it.
Without keytool, Java gets the proxy settings only.
By hand, build a trust store once and start the JVM with it:
keytool -importcert -noprompt -alias akev-ca -file "$(akev ca path)" \
-keystore akev-truststore.p12 -storetype PKCS12 -storepass changeit
java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8000 \
-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8000 -Dhttp.nonProxyHosts= \
-Djavax.net.ssl.trustStore=akev-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit \
-jar app.jarThis trust store contains only the Akev CA, so the JVM trusts nothing else while it uses it.
For Gradle, Maven or IDE runs, put the same -D flags in JAVA_TOOL_OPTIONS.
A JVM that is already running: attach to it instead. See Running JVMs (Pro).
Node, Python, curl and other tools
Terminals opened from Akev, the Existing Terminal command, Electron apps launched by Akev, and the env files for containers all set the same variables. The Anything card on the Connect page lists them with their values.
Trust. Variables that replace a tool's trusted roots point at a combined bundle,
ca-bundle.pem in the data directory: your system's roots followed by the Akev CA. Requests
that don't go through Akev keep working. NODE_EXTRA_CA_CERTS adds to Node's built-in roots,
so it points at ca.pem alone.
| Variable | Points at | Read by |
|---|---|---|
SSL_CERT_FILE |
bundle | OpenSSL, Ruby, Go (Linux only), httpx, uv, rustls-native-certs |
REQUESTS_CA_BUNDLE |
bundle | Python requests, Azure CLI, conda |
CURL_CA_BUNDLE |
bundle | curl, PHP |
GIT_SSL_CAINFO |
bundle | git |
AWS_CA_BUNDLE |
bundle | AWS CLI and SDKs |
CARGO_HTTP_CAINFO |
bundle | cargo |
PIP_CERT |
bundle | pip |
BUNDLE_SSL_CA_CERT |
bundle | Bundler |
DENO_CERT |
bundle | Deno |
HEX_CACERTS_PATH |
bundle | Elixir's Hex |
PERL_LWP_SSL_CA_FILE |
bundle | Perl LWP |
CLOUDSDK_CORE_CUSTOM_CA_CERTS_FILE |
bundle | gcloud |
NODE_EXTRA_CA_CERTS |
ca.pem |
Node.js, npm, Bun, Electron's main process |
JAVA_TOOL_OPTIONS |
trust store | Java (above) |
The system roots come from the bundle that SSL_CERT_FILE, REQUESTS_CA_BUNDLE or
CURL_CA_BUNDLE already pointed at (a company bundle, say). Otherwise Akev uses the
distribution's bundle (/etc/ssl/certs/ca-certificates.crt, /etc/pki/tls/certs/ca-bundle.crt
and similar; /etc/ssl/cert.pem on macOS), or Git for Windows' bundle on Windows. When the CA
or the system bundle changes, Akev rewrites the bundle the next time it is needed.
Proxy. HTTP_PROXY and HTTPS_PROXY (in both cases), WS_PROXY, WSS_PROXY,
GLOBAL_AGENT_HTTP_PROXY, CGI_HTTP_PROXY, npm_config_proxy, npm_config_https_proxy,
YARN_HTTP_PROXY and YARN_HTTPS_PROXY point at the proxy. NODE_USE_ENV_PROXY=1 and
ELECTRON_GET_USE_PROXY=1 turn on proxy support in Node.js and Electron's downloader, and
NO_PROXY and no_proxy are emptied so localhost is captured too. AKEV_ACTIVE=1 and
AKEV_PROXY mark the environment. ALL_PROXY is deliberately not set: many tools treat it as
a SOCKS proxy or apply it to protocols other than HTTP, which breaks them.
Good to know:
- Go reads
SSL_CERT_FILEon Linux only. On macOS and Windows it uses the system store, so trust the CA system-wide. Go never sends requests forlocalhostor127.0.0.1through a proxy: use your machine's host name or network address. - Node.js 24 and later use the proxy variables for
fetchandhttp(s)whenNODE_USE_ENV_PROXY=1is set. For older versions, useglobal-agent(node -r global-agent/bootstrap app.js) or an undiciProxyAgent. - Python: aiohttp only uses the proxy variables with
ClientSession(trust_env=True). - Rust: reqwest uses the proxy variables, and trusts
SSL_CERT_FILEwith rustls-native-certs or native-tls. Builds that use webpki-roots need the CA added in code (add_root_certificate). - PowerShell's web cmdlets use the system store, except PowerShell 6 and later on Linux.
For a single command, pass the proxy and the CA directly:
curl --proxy http://127.0.0.1:8000 --cacert "$(akev ca path)" https://example.comPhones and tablets
- iPhone and iPad: install the configuration profile from the setup page, then turn on full trust in Settings → General → About → Certificate Trust Settings. See iPhone and iPad.
- Android: install the certificate as a user CA. Apps targeting Android 7 or later only trust it if they opt in. On rooted devices and emulators, Akev also trusts it as a system CA until the device restarts, which release apps trust too. See Android over ADB.
- iOS Simulator (macOS): one click trusts the CA in booted simulators. See iOS Simulator.
- Any device can download the certificate from the setup page,
http://akev.cert/through the proxy orhttp://<address>:<port>/directly: as a configuration profile (/ca.mobileconfig), DER (/ca.crt, also/ca.cerand/ca.der) or PEM (/ca.pem). See other devices.
WireGuard mode sends a device's traffic through Akev without proxy settings, but the device still needs to trust the CA for HTTPS.
Bring your own CA
Akev has no import button, setting or API for your own CA. It does use whatever certificate
and key it finds as ca.pem and ca.key in its data directory when it starts. So you can use
your own CA, for example one your devices already trust, by replacing those two files:
- Quit Akev completely (quit the desktop app, or run
akev stop). - Back up the current
ca.pemandca.keyif you might want them again. - Save your CA certificate as
ca.pemand its private key asca.keyin the data directory. - Start Akev and check that Settings → Certificates (or
akev ca show) shows your CA's subject.
What Akev accepts:
| Supported | |
|---|---|
| Files | PEM only. Convert DER or PKCS#12 files to PEM first. |
| Key types | ECDSA P-256 or P-384, RSA, Ed25519 |
| Key formats | PKCS#8 (BEGIN PRIVATE KEY), SEC1 (BEGIN EC PRIVATE KEY) or PKCS#1 (BEGIN RSA PRIVATE KEY), not encrypted. Decrypt an encrypted key first, e.g. openssl pkey -in ca.key -out ca-decrypted.key. |
| Certificate | A CA certificate: basicConstraints with cA true, and a keyUsage (if it has one) that allows signing certificates (keyCertSign). It must match the key. |
| Validity | Already valid (an expired CA is kept, with a warning, but you can't switch to one) |
| Subject | No attribute type used twice (such as DC=example, DC=com) and no multi-valued RDNs, because Akev's certificates must reproduce the issuer name exactly |
A certificate without basicConstraints is accepted, but strict clients may reject the
certificates it signs.
Things to know before you rely on it:
- If Akev can't use the pair, it doesn't stop. It moves your files to
ca.pem.bakandca.key.bak, generates its own CA and logs the reason. That's why step 4 matters. - Expiry: Akev keeps your CA until you replace it, and warns when fewer than 60 days are left.
- Regenerating (Settings → Certificates,
akev ca regenerateor the API) replaces your CA with a new Akev CA; your files are kept asca.pem.bakandca.key.bakonly until the next regeneration. Keep a copy elsewhere. - Chains are kept. If
ca.pemholds an intermediate CA followed by its chain, the first certificate signs, and the rest are sent after it in every TLS handshake. - Akev's host certificates still use ECDSA P-256 keys. Your CA signs them with its own key (RSA signatures use PKCS#1 v1.5 with SHA-256).
--ephemeralwithout--data-diruses a temporary data directory, so it doesn't see your files.- The Windows removal command above looks for
CN=Akev CA, so adapt it to your CA's name.
Remove trust again
Remove the CA when you're done debugging, and before you regenerate it.
| Where | How to remove it |
|---|---|
| Linux, macOS, Windows | Remove in Settings → Certificates → Trust on this computer, or the removal commands under Trust the CA system-wide, also shown in Settings → Certificates → Trust by hand |
| Chrome or Chromium's NSS database (Linux) | Remove under Trust on this computer, or certutil -d sql:$HOME/.pki/nssdb -D -n 'Akev CA' |
| Your own Firefox profile | Settings → Privacy & Security → Certificates → View Certificates… → Authorities → Delete or Distrust… |
| iPhone and iPad | Remove the profile in Settings → General → VPN & Device Management |
| Android | Remove the user certificate in the device's security settings, and Download/akev-ca.crt if you like |
| A Java trust store you built | Delete the .p12 file and stop passing it to the JVM |
Nothing needs removing for clients Akev launched. Chromium-family browsers and Electron apps
trust the CA only through a switch in that one process. Firefox profiles and Akev's Java trust
store live in Akev's data directory. Terminals lose the variables when you close them or run
akev-off. Containers you attached to lose the copied files when you click Detach.
Certificates for upstream servers
Settings → Certificates → Upstream servers is about the servers your clients talk to, not about Akev's CA:
- Client certificates: present a certificate to servers that require mutual TLS. PKCS#12
(
.p12,.pfx) or PEM files, per host (globs allowed), with an optional passphrase. - Trusted CA certificates: extra root certificates (PEM files) to trust for upstream servers, such as your company's internal CA, on top of the roots built into Akev (Mozilla's) and your system's.
- Ignore certificate errors: hosts whose invalid, expired or self-signed certificates Akev accepts. Only list hosts you control: traffic to them could be intercepted by someone else without you noticing.
To see which certificates a server presented and why Akev trusted them, open an exchange's Connection tab: see certificates on the Connection tab.