DocsUpstream & network

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:

  1. The environment variables http_proxy, https_proxy, all_proxy and no_proxy (or their upper-case forms).
  2. 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:

  1. An IP address in the URL is used as it is.
  2. A matching DNS override.
  3. localhost and *.localhost resolve to ::1 and 127.0.0.1.
  4. A cached answer, kept for its DNS TTL (at most an hour).
  5. 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 .local mDNS 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 :port suffix 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.

Type to search guides, the CLI and the API.