Modify
Upstream & network
Who can connect decides which devices may use the proxy. The rest of this page is about Akev's own connections to servers: every request it forwards for a client, every Compose request and replay, and the traffic of WireGuard and transparent capture. They live in two places:
- Settings → Proxy: Who can connect, Upstream proxy, DNS, Timeouts and Preserve header case (under Protocols). HTTP/3 to servers and the upstream TLS fingerprint are on the same page.
- Settings → Certificates → Upstream servers: Client certificates, Trusted CA certificates and Ignore certificate errors.
Changes apply immediately, without a restart. When you change the upstream proxy, DNS or certificate settings, Akev drops its pooled connections, so the next request uses the new settings.
Who can connect
By default the proxy listens on this computer only (127.0.0.1). Once it also listens on your
network (Allow other devices, --proxy-bind 0.0.0.0, for phones, containers and other
computers), Settings → Proxy → Who can connect decides who may use it. A device that is
refused is disconnected without an answer.
| Setting | Default | What it does |
|---|---|---|
| Devices allowed | Private networks | Private networks: this computer, private LAN ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local and IPv6 unique-local addresses, and 100.64.0.0/10 (Docker, Tailscale). Only listed: this computer and the addresses in Allowed devices. Anyone: anyone who can reach the port. |
| Allowed devices | none | IP addresses or ranges for Only listed, such as 192.168.1.23 or 192.168.1.0/24. |
| Blocked devices | none | Always refused, whatever Devices allowed says. This computer is never blocked. Blocking a device also cuts its open connections. |
| Username and password | none | When set, devices on other machines must log in: HTTP proxy authentication (407 Proxy Authentication Required, then Proxy-Authorization: Basic) or SOCKS5 username and password; SOCKS4 is then refused. This computer, WireGuard and transparent capture need no login. The credentials are never sent on to servers. |
| Let devices reach this computer's localhost | off | Off, devices on other machines can't make the proxy connect to this computer's own loopback addresses (127.0.0.0/8, ::1, 0.0.0.0, localhost, also after DNS), so they can't reach dev servers or databases that only listen here. Rules you make that forward to localhost work either way. |
| Trust PROXY protocol headers | off | Only when a load balancer that adds PROXY protocol headers sits in front of Akev: the client address it declares is then the one checked. Off, such headers are ignored. |
When a device connects for the first time, Akev shows New device connected with its
address and a Block button. The setup page
(http://akev.cert) stays reachable for devices that need to log in. The same settings are
proxy.access in the settings API.
Upstream proxy
Use an upstream proxy when Akev has to go through a corporate proxy, or to chain Akev in front of another tool. Pick a Mode:
| Mode | What Akev does |
|---|---|
| Direct (default) | Connects to servers directly. |
| System | Uses the proxy configured in your operating system. |
| Manual | Sends upstream traffic through the Proxy URL you enter. |
| PAC | Chooses the proxy per request with a proxy auto-config script at the PAC script URL. |
Manual and PAC switch on once the URL is valid.
Proxy URL
The Proxy URL is scheme://host:port, with optional credentials:
| Scheme | Proxy |
|---|---|
http:// |
HTTP proxy. Plain HTTP requests are sent to it in absolute form; HTTPS and WebSocket connections are tunnelled with CONNECT. |
https:// |
The same, with Akev's connection to the proxy itself over TLS. |
socks5://, socks4:// |
SOCKS proxy; Akev resolves host names itself. |
socks5h://, socks4a:// |
SOCKS proxy; the proxy resolves host names. |
Add credentials as http://user:password@proxy.corp:3128 (percent-encode special
characters, e.g. @ as %40). HTTP proxies get them as Basic Proxy-Authorization; SOCKS5
proxies as username and password.
With an HTTP(S) proxy, socks5h:// or socks4a://, the proxy resolves the servers' host
names, so your DNS settings don't apply to requests that go through it. They do apply
to the proxy's own host name, and the certificate settings apply to
Akev's TLS connection to an https:// proxy.
Bypass list
Bypass the upstream proxy for lists hosts that Akev reaches directly in System,
Manual and PAC mode, e.g. internal services. Entries can be host names, globs like
*.corp.example, IP addresses or host:port. A plain domain also covers its subdomains:
example.com bypasses api.example.com too.
localhost, *.localhost and loopback addresses always bypass the proxy. Through the
settings API, the list also accepts CIDR ranges (10.0.0.0/8), <local>
(names without a dot, plus loopback) and <-loopback> (send loopback through the proxy too).
System
System reads, in this order:
- The environment variables
http_proxy,https_proxy,all_proxyandno_proxy(or their upper-case forms). - The desktop settings: KDE or GNOME on Linux, the network settings on macOS, the Internet Options (WinINET) settings on Windows.
A PAC script and bypass list configured there are used too. Akev checks the system settings again every 60 seconds.
PAC
The PAC script URL can be http://, https:// or file://. Akev fetches the script
directly (never through a proxy) and fetches it again every 5 minutes; if a fetch fails, it
keeps using the last script. Without any script, requests go direct.
The script's FindProxyForURL runs in an embedded JavaScript engine with the standard PAC
helpers (shExpMatch, isInNet, dnsResolve, myIpAddress and the others). Results like
PROXY a.corp:3128; SOCKS5 b.corp:1080; DIRECT are tried in order. The DNS helpers use your
DNS overrides.
What doesn't go through it
- HTTP/3 is never used through an upstream proxy: QUIC can't be tunnelled through an HTTP proxy, so those requests use TCP.
- A browser TLS fingerprint only applies to the connection to the
server. Akev's TLS connection to an
https://proxy always uses its native stack.
When the proxy can't be reached or refuses a request, the exchange fails with The upstream proxy failed, and in Compose a Proxy settings button takes you to the setting.
DNS
DNS overrides
DNS overrides resolve hosts to fixed addresses, like a hosts file that only affects
traffic through Akev. Add a Host (a name or a glob such as *.staging.example.com) and an
Address (an IPv4 or IPv6 address).
An exact host name wins over globs; globs are tried in list order. Through the
settings API, an address can also be several IPs ("10.0.0.1, ::1") or
another host name to resolve instead.
DNS-over-HTTPS
DNS-over-HTTPS resolves server names with an encrypted resolver instead of the system's.
Enter an https:// resolver URL, or pick one from Presets: Cloudflare, Google or
Quad9. Leave it empty (System resolver) to use your system's DNS. A URL without a path
uses /dns-query.
Akev looks up the resolver's own host name with the system resolver (not needed when the URL uses an IP address).
How names are resolved
For each server name, Akev uses the first of these that applies:
- An IP address in the URL is used as it is.
- A matching DNS override.
localhostand*.localhostresolve to::1and127.0.0.1.- A cached answer, kept for its DNS TTL (at most an hour).
- The DNS-over-HTTPS resolver if one is set, otherwise the system's DNS configuration
(including the hosts file). Names the system resolver can't find, such as
.localmDNS names, fall back to the operating system's lookup.
Upstream certificates
Client certificates (mTLS)
Client certificates are presented to servers that require mutual TLS. Each entry has:
- Host: the server it's for. Globs work (
*.internal.example.com,*for every server), and a:portsuffix limits it to one port. - Certificate file: an absolute path to a PKCS#12 file (
.p12/.pfx) or a PEM file holding the certificate chain and the private key. Encrypted PEM keys aren't supported; use a PKCS#12 file for a protected key. - Passphrase: for a PKCS#12 file, if it has one.
The first entry whose host matches is used. If its file can't be loaded (missing file, wrong passphrase), requests to that host fail with an error that says why, instead of connecting without a certificate. Client certificates apply over HTTP/3 too.
Trusted CA certificates
By default Akev trusts the usual public root certificates and your operating system's trust store. Trusted CA certificates adds more roots, such as your company's internal CA: enter the absolute path of a PEM file. A file that can't be read is skipped.
Ignore certificate errors
Ignore certificate errors accepts invalid, expired or self-signed certificates from the
hosts you list (globs work; * means every host). Anyone between Akev and those hosts could
read and change the traffic without you noticing, so only list hosts you control.
For a single request, use the Ignore TLS errors option in Compose; a request that failed on a certificate offers Retry ignoring TLS errors.
Whatever the settings, the server's certificate shows in the exchange's Connection tab.
Timeouts and connection settings
| Setting | Default | What it does |
|---|---|---|
| Connect timeout | 15 s | How long a new connection may take, covering the DNS lookup, TCP connect, upstream proxy handshake and TLS handshake together. |
| Response timeout | 120 s | How long to wait for the server to start answering (its response headers). 0 = no limit. |
| Body idle timeout | 5 min | Fails the exchange when a response body sends nothing for this long. Streams that keep sending are never cut off. 0 = no limit. |
| Preserve header case | On | Forwards HTTP/1 header names exactly as the client sent them, since some servers are case-sensitive. Off, Akev writes them in Title-Case. |
A Compose request's own Timeout option overrides the response timeout while waiting for the response to start.
Settings keys
The same settings are in settings.json and the settings API
(GET / PUT /api/settings), under proxy:
| Key | Default | Setting |
|---|---|---|
upstreamProxy.mode |
"direct" |
Mode: "direct", "system", "manual" or "pac" |
upstreamProxy.url |
"" |
Proxy URL or PAC script URL |
upstreamProxy.noProxy |
[] |
Bypass the upstream proxy for |
dnsOverrides |
[] |
DNS overrides: [{ "host": "api.example.com", "address": "127.0.0.1" }] |
dohUrl |
null |
DNS-over-HTTPS URL; null is the system resolver |
clientCertificates |
[] |
Client certificates: [{ "host": "*.corp", "path": "/certs/me.p12", "passphrase": "…" }] |
trustedCaPaths |
[] |
Trusted CA certificates (PEM file paths) |
ignoreUpstreamCertErrors |
[] |
Ignore certificate errors (host globs) |
connectTimeoutMs |
15000 |
Connect timeout; 0 = no limit |
responseTimeoutMs |
120000 |
Response timeout; 0 = no limit |
bodyIdleTimeoutMs |
300000 |
Body idle timeout; 0 = no limit |
access.policy |
"private" |
Devices allowed: "private", "allowlist" or "any" |
access.allow, access.block |
[] |
Allowed devices, Blocked devices (addresses or CIDR ranges) |
access.username, access.password |
"" |
Username and password |
access.allowLoopbackTargets |
false |
Let devices reach this computer's localhost |
access.trustProxyProtocol |
false |
Trust PROXY protocol headers |
preserveHeaderCase |
true |
Preserve header case |
settings.json stores a client certificate's passphrase, and the proxy password, as plain
text.