Capture
Intercept a running JVM (Java, Kotlin, Scala)
Pro feature. Attaching to running JVMs needs Akev Pro or its 14-day trial.
Already have a Spring Boot service, a Kotlin CLI or a Scala job running? Akev can attach to it
— no restart, no flags — and route its HTTP(S) traffic through the proxy. Under the hood this is
the standard Java debugging workflow: Akev loads a small Java agent into your own JVM with
the JDK Attach API, the same mechanism profilers and jcmd use.
Attach
- Open Connect → Running JVM (search for java, kotlin, spring…).
- The panel lists the Java processes you can attach to, with their PID, Java version and main class or jar. Click Attach next to your app.
- Use the app: its requests show up in Traffic, HTTPS decrypted.
Restore (same row) puts the JVM's original proxy and TLS settings back. Quitting Akev restores every JVM it attached to.
From the command line or another tool:
akev intercept list # `jvm` shows as available
akev intercept jvm --options '{"pid": 48213}' # attach
akev intercept stop jvm --options '{"pid": 48213}' # restore (without options: all of them)The REST API (POST /api/interceptors/jvm/activate, see API.md) and
MCP (akev_activate_interceptor with {"id": "jvm", "options": {"pid": …}}) work the same way.
Options
| Option | Default | Meaning |
|---|---|---|
pid |
— | The JVM to attach to (from the list). |
interceptLoopback |
false |
Also intercept requests to localhost, 127.0.0.0/8 and ::1 (Include localhost requests in the panel). Off by default so local databases, Docker port-forwards and dev services keep working directly. |
proxyProperties |
auto |
auto, always or never: whether to set the http(s).proxyHost/Port system properties (see below). |
What gets intercepted
The agent changes the JVM-wide defaults that HTTP clients read:
| Change | Covers |
|---|---|
ProxySelector.setDefault(…) → Akev for http, https, ws, wss (loopback direct unless enabled) |
HttpURLConnection, java.net.http.HttpClient created after attaching, OkHttp / Apache HttpClient (useSystemProperties) / Spring / Feign clients created after attaching, anything that asks ProxySelector.getDefault() |
A new default SSLContext and HttpsURLConnection default socket factory whose trust manager accepts the Akev CA in addition to everything the JVM trusted before |
HttpsURLConnection (Spring RestTemplate's default, Feign, Jersey…), SSLContext.getDefault() users |
The existing default SSLContext object gets the same trust manager |
Clients that captured the default context before the attach — e.g. a java.net.http.HttpClient built at startup, Apache clients built from SSLContexts.createSystemDefault() |
javax.net.ssl.trustStore → a temporary trust store with the JVM's previous trust store plus the Akev CA |
Libraries that build their own default TrustManagerFactory after attaching (OkHttp, Apache HttpClient, Netty SslContextBuilder.forClient()…) |
http(s).proxyHost/Port + http.nonProxyHosts |
Clients created before the attach that kept the JDK's built-in proxy selector (e.g. that startup HttpClient), code that reads the properties directly |
Trust is never "accept everything": a server certificate is accepted only if the JVM's original
trust manager or a trust manager containing just the Akev CA validates it — full PKIX
checks, including expiry and hostname verification. Client certificates (your app acting as a
TLS server) are still checked by the original trust manager only, and the original default
context's client certificates (javax.net.ssl.keyStore) are kept.
Limits — read this before you rely on it
- Clients with their own trust settings built before you attached keep connecting directly.
Without rewriting bytecode (which Akev doesn't do), an
OkHttpClient, a Netty/Reactor client or any client with a customSSLContextcreated at startup can't be re-pointed. Clients created after attaching are intercepted. Spring WebClient (Reactor Netty) ignores the JVM proxy settings unless configured with.proxyWithSystemProperties(). - That's why
proxyProperties: autosets thehttp(s).proxyHostproperties only when it is safe: when the existing defaultSSLContextcould be updated and no OkHttp client class is loaded. Otherwise an OkHttp client from before the attach would be routed through Akev without trusting it and fail. The activation result (and the panel) says when it was skipped.alwaysforces them;neverleaves them alone. - Updating the existing
SSLContextuses JSSE internals (opened through the agent'sInstrumentation, so no illegal-access warnings): theSSLContext.contextSpiandSSLContextImpl.trustManagerfields OpenJDK's JSSE has had since Java 8. Where they differ the agent reportsexistingDefaultContext: unchangedand only new clients are intercepted. - Tested in CI on Linux, macOS and Windows with Java 8, 11, 17, 21 and 25 (OpenJDK HotSpot builds), with the same Java as target and attacher. On every version the tests attach the agent to a live JVM and restore it; from Java 11 on they also check end to end that its HTTPS traffic goes through Akev, decrypted, and goes direct again after Restore. The agent is Java 8 bytecode and calls Java 9+ APIs reflectively.
- Non-HTTP protocols (raw sockets, gRPC over Netty with its own transport, database drivers) are not touched.
- If the application replaces a default (proxy selector, SSL context, a system property) while attached, Restore leaves its value alone and says so.
- A JVM can't unload an agent: after Restore its (now inactive) classes stay loaded until the app exits. Attaching again reuses them.
Requirements
- A JDK with the Attach API (
jdk.attachmodule; Java 8:tools.jar). Akev runs the attacher with the target's own Java when it has one, else$JAVA_HOME,javaonPATH, SDKMAN's or the platform's usual JDK folders — whichever can attach. A JRE withoutjdk.attachcan't. - The target: Java 8 or later (the agent is compiled for Java 8), running as your user on this machine. JVMs in containers or owned by other users aren't listed (use the Docker interceptor for containers).
- JVMs started with
-XX:+DisableAttachMechanismcan't be attached to. Since Java 21, dynamic agent loading prints a warning on the app's console ("A Java agent has been loaded dynamically…"); a future Java release will refuse it unless the app runs with-XX:+EnableDynamicAgentLoading. For those, start the app with the agent instead (below).
JVMs are listed with jps -l; without jps, from the process table (java launcher processes).
Start a JVM with the agent
To intercept from the first request (or where attaching is disabled), load the agent at startup.
The jar is written to <data dir>/jvm/akev-agent-<hash>.jar the first time you attach:
java "-javaagent:/path/to/akev-agent.jar=proxyHost=127.0.0.1&proxyPort=8000&caCert=$HOME/.local/share/akev/ca.pem" -jar app.jarArguments are URL-encoded key=value pairs joined with & (interceptLoopback=true,
proxyProperties=never, quiet=true, statusFile=/tmp/akev-status.txt), or @/path/to/file
with the same keys as a .properties file. The attacher works standalone too:
java -cp akev-agent.jar dev.akev.Attach <pid> --proxy 127.0.0.1:8000 --ca ca.pem [--intercept-loopback]
java -cp akev-agent.jar dev.akev.Attach <pid> --restore
java -cp akev-agent.jar dev.akev.Attach --check # is the Attach API available in this Java?It prints the agent's report (key=value lines) and exits with 0 on success, 3 when this Java
has no Attach API, 4 when it couldn't attach, 5 when the JVM refused the agent, 6 when the agent
reported an error.
Troubleshooting
| Symptom | Fix |
|---|---|
| No Java found | Install a JDK or set JAVA_HOME. |
| Your app isn't listed | It runs as another user, in a container, or with -XX:-UsePerfData and without the java launcher. Click refresh after it has started. |
| Couldn't attach … Unable to open socket file | The JVM is still starting, suspended in a debugger, or was started with -XX:+DisableAttachMechanism / -Xrs. |
| The Java Attach API isn't available | Akev only found JREs: install a JDK. |
| Some requests still go direct | See Limits: the client was built before attaching with its own trust or proxy settings. Restart that client (or the app with -javaagent:). |
| Attached to port 9000 (another Akev session) | The JVM still points at a previous Akev's proxy. Restore it, or Attach here to use this one. |
Attached JVMs are remembered in <data dir>/jvm/attached.json, so a restarted Akev still shows
— and can restore — them.