Keep & automate
Akev HTTP API (v1)
The Akev daemon (akev CLI or the desktop app) serves this API, the live event stream,
the MCP endpoint and the web UI from one localhost port (default 45456).
All JSON uses camelCase field names; enums use kebab-case strings. Types referenced as
ExchangeSummary, ExchangeDetail, RuleSet, Settings, InterceptorInfo, ... are defined
in crates/akev-core/src/*.rs (the UI mirrors them in ui/src/api/types.ts).
Authentication
Every /api/* and /mcp request must carry the session token, by either of:
Authorization: Bearer <token>(preferred)?token=<token>query parameter (for downloads & the WebSocket, where headers can't be set)?ticket=<ticket>for one download:POST /api/download-ticketwith{"path": "/api/export/har"}returns{"ticket", "expiresInMs"}, a ticket valid for a singleGETof that path (any query) within 60 seconds. The UI uses it for browser downloads so the token never lands in download history.
The token is never accepted from a cookie. Cookies are not isolated by port, so a cookie for
127.0.0.1 would be sent to every other service on that host (dev servers, containers, other
users' apps, Akev's own proxy port, which would record it).
Opening the UI. GET /?token=<token> with the valid token serves the UI itself
(Cache-Control: no-store, Referrer-Policy: no-referrer). The UI keeps the token in
port-isolated web storage, removes it from the address bar and sends it as a Bearer header. A
wrong token redirects to / without it. akev start never passes this URL on a command line,
because other local users can read process arguments (/proc/<pid>/cmdline). Instead it writes a
redirect page, open-ui.html (mode 0600), into the data directory and opens that file. The page
is removed when the daemon stops. If the browser can't read the data directory (some snap or
flatpak browsers), open the printed Web UI link, or the one from akev status.
Requests with a browser Origin header are rejected unless the origin is the API's own origin
or explicitly allowed (--allow-origin). Embedders can also allow the Tauri webview origins
(AkevOptions::allow_tauri_origins, off by default; the desktop app loads the UI from the API's
own origin). This blocks drive-by attacks from web pages against the local API. On a loopback
bind, GET / and static UI assets are public (they contain no data).
Network-exposed API (--api-bind not a loopback address):
Other machines reach the UI and the API over HTTPS only, with a certificate from Akev's own CA for the bind address,
localhost, the loopback addresses, the computer's name (and<name>.local) and its network addresses; it is re-issued when the CA is regenerated. Theakev startbanner andakev statusprint thishttps://address (Status.networkUrl). A device that sends plain HTTP gets a short answer pointing tohttps://. Plain HTTP stays for this machine itself, so the CLI,akev mcpand the desktop app keep usinghttp://127.0.0.1:<port>.The static UI requires authentication too.
GET /?token=also sets a UI-only session cookie,akev_ui_<port>(HttpOnly; SameSite=Strict). It holds a separate random secret that only unlocks the static UI, never/apior/mcp.A custom token (
--token/AKEV_TOKEN) must be at least 24 characters and not repetitive. Startup fails otherwise. Generated tokens are 256-bit random.A non-loopback peer that presents 20 distinct wrong credentials within a minute gets
429(withRetry-After) until the minute ends, even for a correct token. Retrying the same stale token, or sending no credential, doesn't count. Loopback peers are never throttled.
Debug request logs (-vv) never record the value of a token query parameter.
Errors: non-2xx with {"error": {"code": "not-found", "message": "..."}}. Using a Pro feature
without a licence or trial answers 402 with the code pro-required (see Licence).
Status & lifecycle
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/status |
– | Status |
| POST | /api/shutdown |
– | 204 |
interface Status {
version: string;
proxy: {
port: number; bindAddress: string /* in effect, incl. --proxy-bind */; addresses: string[] /* host:port reachable addresses incl. LAN IPs */;
http3: { enabled: boolean; address?: string /* UDP ip:port when listening */; port?: number; error?: string /* why it isn't listening although enabled, e.g. the UDP port is taken */ };
};
apiUrl: string;
dataDir: string;
ca: CaInfo; // akev-ca CaInfo
startedAt: number; // unix ms
stats: { exchanges: number; memoryBodyBytes: number; spilledBodyBytes: number; activeConnections: number; totalConnections: number };
platform: "linux" | "macos" | "windows";
desktop: boolean; // running inside the desktop shell
restoredSession?: { id: string; name: string; exchanges: number; savedAt: number /* unix ms */ }; // the autosave restored at startup, once loaded
license: LicenseStatus; // plan, trial and licence key (see Licence)
}Licence
Akev Pro is unlocked by a licence key or the trial; see licensing. The key is
verified offline and stored in <data dir>/license.json (not in Settings, and not in a
Settings export).
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/license |
– | LicenseStatus |
| PUT | /api/license |
{ key: string } ("AKEV1.…") |
LicenseStatus, or 400 invalid-license |
| DELETE | /api/license |
– | LicenseStatus (the stored key is removed) |
| POST | /api/license/trial |
– | LicenseStatus (trial started), or 409 trial-unavailable |
interface LicenseStatus {
plan: "free" | "pro";
state: "none" | "trial" | "trial-ended" | "active" | "updates-ended" | "invalid";
features: Feature[]; // the Pro features enabled now
license?: { // the key's contents, when there is one
id: string;
email: string;
name?: string;
issued: string; // YYYY-MM-DD
updatesUntil: string; // YYYY-MM-DD
};
trialEndsAt?: number; // unix ms, while a trial runs or after it ended
trialAvailable: boolean; // POST /api/license/trial would start one
error?: string; // why the key is invalid
releaseDate: string; // YYYY-MM-DD, this build's release date
}
type Feature =
| "scripting" | "tls-impersonation" | "wireguard" | "transparent"
| "jvm-attach" | "proto-schemas" | "llm-lens" | "mcp-write";state |
plan |
Meaning |
|---|---|---|
none |
free |
No key, no trial |
trial |
pro |
The trial runs until trialEndsAt |
trial-ended |
free |
The trial is over and there is no key |
active |
pro |
A valid key that covers this build |
updates-ended |
free |
A valid key, but this build was released after updatesUntil: use an older build or renew |
invalid |
free |
The key doesn't verify; error says why |
Changes are broadcast on the live stream as
{ type: "license", license: LicenseStatus }.
Pro required. Endpoints that start or use a Pro feature answer, without a licence or trial:
HTTP/1.1 402 Payment Required
Content-Type: application/json
{"error": {"code": "pro-required", "message": "…", "feature": "wireguard"}}feature is one of the Feature ids. Nothing stored is deleted without a licence: rules with
a Pro action (which stay editable), WireGuard and transparent capture settings and protobuf
schemas are kept, they just don't take effect. MCP tools that need Pro return a tool error
naming the feature.
Exchanges (captured traffic)
| Method | Path | Body / Query | Response |
|---|---|---|---|
| GET | /api/exchanges |
?filter=<query>&limit=<n> |
ExchangeSummary[] (id order) |
| GET | /api/exchanges/:id |
– | ExchangeDetail |
| GET | /api/exchanges/:id/body/:side |
side = request/response; ?original=1 pre-modification body |
BodyView (see below) |
| GET | /api/exchanges/:id/body/:side/raw |
?decoded=1 (remove content-encoding) &download=1 (Content-Disposition attachment, filename derived from URL) |
raw bytes with the exchange's Content-Type |
| GET | /api/exchanges/:id/messages |
?after=<seq> |
StreamMessageWithPayload[] |
| POST | /api/exchanges/:id/messages |
InjectMessage — inject into a live WebSocket (see WebSocket tools) |
202 { seq: number | null } |
| GET | /api/exchanges/:id/llm |
– | LlmExchange — the conversation view of an LLM API call (see LLM conversations); 404 not-llm for other exchanges |
| GET | /api/exchanges/:id/snippet |
?target=curl |
{ target, language, code } |
| POST | /api/exchanges/headers |
{ ids: number[], request?: string[], response?: string[] } (up to 5,000 ids and 32 header names per side) |
{ exchanges: { id, request: Record<string,string>, response: Record<string,string> }[] } — the chosen headers' values, names lowercase, repeated headers joined with ", "; unknown ids are left out. The traffic list's header columns use it. |
| POST | /api/exchanges/timings |
{ ids: number[] } (up to 5,000) |
{ timings: ({ id } & Timing)[] } — each exchange's phase timings, as in ExchangeDetail.timing; unknown ids are left out. The timeline uses it. |
| POST | /api/exchanges/delete |
{ ids: number[] } |
204 |
| POST | /api/exchanges/clear |
{ keepPinned?: boolean } |
204 |
| PATCH | /api/exchanges |
{ ids: number[], pinned?: boolean, color?: string | null, note?: string | null } |
204 |
| POST | /api/exchanges/:id/replay |
{ request?: EditableRequest, options?: SendOptions } (omitted request = resend as captured) |
SendResult & { body: BodyView, recorded: boolean } (see Compose) |
| GET | /api/exchanges/:id/editable/:side |
– | EditableRequest / EditableResponse (decoded body, base64) — used to open a captured request in Compose |
interface BodyView {
kind: ContentKind; // "json" | "html" | "image" | ...
size: number; // decoded size
wireSize: number;
encodings: string[]; // content-encoding chain
text: string | null; // decoded text (null if binary or decode failed)
formatted: string | null; // pretty-printed text where applicable
structured: any | null; // protobuf/grpc/msgpack/cbor → JSON, multipart parts, SSE events, form fields, image info
decodeError: string | null;
truncated: boolean; // text truncated for transport (> 8 MB); use /raw for full
captureTruncated: boolean; // the proxy only captured a prefix of the body
structuredTruncated?: true; // `structured` holds only the first part (decode size limits); omitted when false
schema?: SchemaInfo; // an imported protobuf schema decoded the body (see "Protobuf schemas"); omitted otherwise
}
interface StreamMessageWithPayload extends StreamMessage {
text: string | null; // UTF-8 payload if text
base64: string | null; // payload when binary
}ExchangeDetail.upstream.fingerprint (TLS upstream connections; omitted otherwise) is the
ClientHello — and HTTP/2 preface — Akev itself presented to the server, recorded from the bytes
actually sent (see Upstream TLS fingerprints):
interface UpstreamFingerprint {
profile: "native" | "chrome" | "firefox" | "safari" | "edge"; // what was used
requested?: string; // what was asked for when different: "mirror-client", or a browser profile in a build without the backend
note?: string; // why `requested` wasn't used as is
ja3?: string; // md5 hex of ja3Text
ja3Text?: string; // "771,4865-4866-...,0-23-65281-...,4588-29-23-24,0" (Chrome's changes per connection: it shuffles extensions)
ja4?: string; // e.g. "t13d1516h2_8daaf6152771_d8a2da3f94cd"
http2?: string; // Akamai format "SETTINGS|WINDOW_UPDATE|PRIORITY frames|pseudo-header order", HTTP/2 connections only
}ExchangeDetail.upstream.chain (TLS upstream connections; omitted for exchanges recorded by
earlier versions) is every certificate the server presented and what Akev's trust decision
rested on. It is filled once per connection and shared by the exchanges that reuse it:
interface CertificateChain {
certificates: CertificateSummary[]; // as the server sent them, the leaf first
trust: {
status: "verified" | "not-verified" | "unknown";
// verified: up to a trusted root; not-verified: certificate errors are ignored for this
// host (settings) or this request (Compose); unknown: the handshake succeeded but the
// path couldn't be rebuilt to report it
path: number[]; // indices into certificates of the verified path, leaf first
anchor?: { // the trusted root the path ends at
subject: string;
index?: number; // set when the server sent the root itself
source: "built-in" | "system" | "custom"; // Mozilla's roots built into Akev, the OS store, or a trusted CA file
};
};
}Certificates the server sent that aren't on path (old cross-signs, duplicates) weren't used.
For gRPC / gRPC-Web, structured is { messages: GrpcMessage[], error?: string } with
GrpcMessage = { compressed, decoded /* schemaless */, trailers, size }. When a schema applies,
each message also carries typed (the typed decode) and unknownFields?: string[], or
typedError: string when it doesn't fit the schema.
LLM conversations
Calls to LLM APIs are recognised when they are captured: OpenAI Chat Completions, legacy
Completions and Responses (OpenAI, Azure OpenAI and every OpenAI-compatible server — OpenRouter,
Groq, Mistral, DeepSeek, xAI, Together, Fireworks, Perplexity, Ollama, vLLM, LM Studio…),
Anthropic Messages (also Claude on Vertex AI), Google Gemini generateContent /
streamGenerateContent (AI Studio and Vertex AI) and Ollama's native /api/chat and
/api/generate. Well-known provider hosts are recognised by URL; other hosts also need a request
body of the API's shape. Such exchanges carry llm on their ExchangeSummary:
interface ExchangeSummary {
// …
llm?: { provider: string; model?: string }; // provider id + requested model
}and the filter language has is:llm, model: and provider:. GET /api/exchanges/:id/llm
normalises the call across providers. Streamed responses (SSE deltas, Anthropic content-block
events, Responses API events, Gemini SSE / JSON-array streams, Ollama NDJSON) are reassembled into
the final message(s). Malformed or truncated bodies never fail the request: what could be read is
returned and warnings says what couldn't.
interface LlmExchange {
provider: string; // "openai" | "anthropic" | "google" | "vertex-ai" | "azure-openai" | "openrouter" | "groq" | "mistral"
// | "deepseek" | "xai" | "together" | "fireworks" | "perplexity" | "cerebras" | "huggingface"
// | "ollama" | "lmstudio" | "openai-compatible" | "anthropic-compatible"
api: "openai-chat" | "openai-completions" | "openai-responses" | "anthropic-messages" | "gemini" | "ollama-chat" | "ollama-generate";
model?: string; // the model that answered (response), else the one requested
stream: boolean;
request: {
system?: string; // system prompt / instructions (several blocks joined by blank lines)
messages: LlmMessage[];
tools: { name: string; description?: string; schema?: any /* JSON Schema */; kind?: string /* built-in tool type */ }[];
params: Record<string, any>;// every other request field under the provider's own name (temperature, max_tokens,
// thinking, tool_choice, response_format…); Gemini generationConfig and Ollama options flattened
};
response?: { // absent while waiting, or when the API returned an error
id?: string;
model?: string;
messages: LlmMessage[]; // usually one assistant message (one per choice when n > 1)
stopReason?: string; // provider wording: "stop", "end_turn", "tool_use", "tool_calls", "length", "STOP"…
usage?: {
inputTokens?: number; // all prompt tokens, cached included (Anthropic: input + cache reads + cache writes)
outputTokens?: number; // reasoning included (Gemini: candidates + thoughts)
totalTokens?: number;
cacheReadTokens?: number;
cacheWriteTokens?: number;
reasoningTokens?: number;
};
};
timing: { // ms, measured from the request being sent upstream
ttftMs?: number; // first stream event carrying generated content (from the recorded SSE timestamps)
totalMs?: number; // until the response was complete
tokensPerSecond?: number; // output tokens / s after the first token (whole duration when not streamed; Ollama's own figure)
chunks?: number; // stream events the response arrived in
};
error?: { status?: number; kind?: string; code?: string; message: string }; // HTTP error body or stream error event
warnings?: string[]; // e.g. "The stream ended before its final event: the response may be incomplete"
}
interface LlmMessage {
role: string; // "system" | "developer" | "user" | "assistant" | "tool" (Gemini "model" → "assistant")
name?: string;
content: LlmPart[];
}
type LlmPart =
| { type: "text"; text: string }
| { type: "image"; mediaType?: string; data?: string /* base64, ≤ 8 MiB */; url?: string; size?: number /* bytes */ }
| { type: "file"; label: "document" | "audio" | "file"; mediaType?: string; name?: string; url?: string; size?: number }
| { type: "tool-call"; id?: string; name: string; arguments: any /* parsed JSON; the raw string when invalid */ }
| { type: "tool-result"; id?: string; name?: string; content: LlmPart[]; isError?: true }
| { type: "thinking"; text: string; redacted?: true }
| { type: "refusal"; text: string }
| { type: "other"; label: string; value: any }; // blocks Akev doesn't model (built-in tool results…)Absent optional fields are omitted. For agents, the MCP tool akev_llm_conversation returns the
same object with long texts cut and inline image data left out.
Filter language
| Method | Path | Body | Response |
|---|---|---|---|
| POST | /api/filter/validate |
{ query } |
{ ok: true } | { ok: false, error: { message, start, end } } |
| POST | /api/filter/suggest |
{ query, cursor } |
Suggestion[] |
| POST | /api/filter/query |
{ query } |
{ ids: number[] } |
| GET | /api/filter/docs |
– | FieldDoc[] |
Rules
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/rules |
– | RuleSet |
| PUT | /api/rules |
RuleSet |
{ errors: [ruleId, message][] } (applied immediately & persisted; compiling runs script rules' top-level code, up to 0.5 s each) |
| GET | /api/rules/stats |
– | RuleStats[] |
| POST | /api/rules/stats/reset |
– | RuleStats[] (counters zeroed, match limits re-armed) |
| POST | /api/rules/test |
{ exchangeId } or { request: EditableRequest } + optional { rules: RuleSet, runScripts?: boolean (default true) } |
{ matched: RuleId[], terminalRule: RuleId | null, action: Action, scriptLogs?: string[], error?: string, scriptOutcome?: { kind: "continue", method, url, headers, body, response?: {status, headers, body} } | { kind: "respond", response } } (dry run; matching script rules are executed in the sandbox against the request and the captured response) |
| GET | /api/rules/export |
– | RuleSet as attachment akev-rules.json |
| POST | /api/rules/import |
RuleSet or HTTP Toolkit rules export JSON |
RuleSet (converted; not applied) |
The modifier action { type: "tls-profile", profile: TlsProfile } makes matching requests
present that TLS fingerprint upstream, overriding proxy.tlsProfile (the last matching
tls-profile rule wins; later rules still run). See
Upstream TLS fingerprints.
Breakpoints
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/breakpoints |
– | PausedExchange[] |
| POST | /api/breakpoints/:id/resume |
RequestResume (request stage) or ResponseResume (response stage) |
204 |
| POST | /api/breakpoints/resume-all |
– | 204 (continue all unchanged; also forwards every paused WebSocket message) |
| GET | /api/breakpoints/messages |
– | PausedMessage[] (WebSocket messages paused at ws-breakpoint rules) |
| POST | /api/breakpoints/messages/:pauseId/resume |
MessageResume |
204 |
| POST | /api/breakpoints/messages/resume-all |
{ id?: number, action?: "forward" | "drop" } (only exchange id's messages; default forward) |
{ resumed: number } |
interface PausedExchange {
id: number; // the exchange id
stage: "request" | "response";
pausedAt: number; // unix µs, when it started waiting
request: EditableRequest; // as received (request stage) or as sent upstream (response stage)
response?: EditableResponse; // response stage only
}Breakpoints hold matching traffic even when it isn't recorded (recording paused, or
capture.ignoreHosts matches the host): such an exchange is in /api/breakpoints but not in
/api/exchanges, so clients should show and resume it from this snapshot.
WebSocket tools
Injecting messages. POST /api/exchanges/:id/messages writes a message into a live
intercepted WebSocket, as if one of the peers had sent it:
interface InjectMessage {
direction: "sent" | "received"; // "sent" = to the server (masked like a client frame), "received" = to the client
kind?: "text" | "binary"; // default: "text" with `text`, "binary" with `base64`
text?: string; // UTF-8 payload…
base64?: string; // …or raw bytes (exactly one of text / base64; text kind must be valid UTF-8)
}The message goes out as soon as that direction is between messages (never inside a frame or
a fragmented message) and is recorded like any other message, with modified: true. The
response comes once it was written: 202 { seq } (its StreamMessage.seq), or 202 { seq: null } after 2 s when it is still queued behind a long message. Errors: 404 unknown
exchange, 409 not an open intercepted WebSocket (closed, not a WebSocket, or sent on a
ws-echo connection, which has no server), 400 invalid body (max 16 MiB), 429 when 64
messages are already queued.
Message breakpoints. A rule with the modifier action
{ type: "ws-breakpoint", direction: "sent" | "received" | "both", pattern?: StringMatch }
pauses the text/binary messages of the WebSockets it matches. Such rules only match WebSocket
upgrade requests (once per connection: that is what maxMatches and the hit counter count).
pattern is tested against the payload as UTF-8 (binary lossily); without it every message
is paused. The rule is looked up again for every message, so disabling, deleting or editing it
applies to connections that are already open. Messages larger than 4 MiB are never paused.
A paused message holds back only its own direction, and only its data: pings and pongs still
pass (so keep-alive timeouts don't fire) and the other direction keeps flowing. What arrives
behind it waits in order (up to 4 MiB, then the sender is no longer read). When either peer
disconnects, or the other direction ends, the pause is abandoned: the message is delivered as
received and the connection stops pausing. Paused messages appear on the stream
(message-paused / message-resumed) and in hello.pausedMessages.
interface PausedMessage {
id: number; // the WebSocket exchange
pauseId: number; // resume with this id
direction: "sent" | "received";
kind: "text" | "binary";
payload: string; // complete payload, base64
at: number; // unix µs
rule: string; // the ws-breakpoint rule
}
type MessageResume =
| { action: "forward"; kind?: "text" | "binary"; text?: string; base64?: string } // no payload = unchanged (original framing kept)
| { action: "drop" }; // never delivered, not recordedAn edited message is sent as one frame and recorded with modified: true. Errors: 404 not
paused (anymore), 400 invalid payload.
Compose (send requests)
| Method | Path | Body | Response |
|---|---|---|---|
| POST | /api/send |
{ request: EditableRequest, options?: SendOptions } |
SendResult & { body: BodyView, recorded: boolean } |
| POST | /api/send/repeat |
{ request?: EditableRequest, exchangeId?: number, options?: SendOptions, count: number, concurrency?: number, delayMs?: number } |
NDJSON stream, one line per finished request, then { done: true, sent } (see below) |
| POST | /api/import/curl |
{ command } |
EditableRequest |
| GET | /api/codegen/targets |
– | TargetInfo[] |
| POST | /api/codegen |
{ request: EditableRequest, target } |
{ target, language, code } |
Repeat (POST /api/send/repeat) sends one request count times (at most 10,000), with up
to concurrency requests in flight (default 1, at most 64); each worker pauses delayMs
(at most 60,000) between its requests. Give request, or exchangeId to resend a captured
request as it was. The response streams one JSON line per finished request, in the order they
finish:
{"index":0,"id":812,"status":200,"durationMs":41.7}
{"index":2,"id":814,"error":"timeout","durationMs":60000}
{"done":true,"sent":3}index is the request's place in the run, id the exchange it made (in the traffic list
unless recording is paused), status or error (an error kind such as timeout or connection-refused) the outcome, and durationMs
the time to the end of the response body or the failure. Closing the connection stops the run,
in-flight requests included.
recorded tells whether exchange id was stored in the traffic list. It is false while
recording is paused (PUT /api/capture) or when the capture settings ignore the host. The id
then can't be opened (/api/exchanges/:id answers 404).
interface SendOptions { // all optional
applyRules: boolean; // false — run through the user's rules
followRedirects: boolean; // false — each hop is recorded
timeoutMs: number; // 60000 — response head timeout; 0 = the proxy settings' default
insecure: boolean; // false — ignore upstream certificate errors
httpVersion: "auto" | "http1" | "http2" | "http3"; // "auto"
}httpVersion: auto lets the settings decide (HTTP/2 via ALPN, HTTP/3 per
proxy.http3.upstream); http1 never negotiates HTTP/2; http2 stays on TCP (HTTP/2 when the
server offers it, else HTTP/1.1) and never uses HTTP/3; http3 tries HTTP/3 over QUIC first
whatever the settings say and falls back to TCP when the QUIC connection can't be established
(like curl --http3). HTTP/3 only applies to https:// URLs, never through an upstream proxy.
The response's httpVersion (and the recorded exchange's, for Compose / Repeat) is the one
actually used.
Interceptors
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/interceptors |
– | InterceptorInfo[] |
| POST | /api/interceptors/:id/activate |
{ options?: any } |
ActivationResult |
| POST | /api/interceptors/:id/deactivate |
{ options?: any } |
204 |
| GET | /api/setup/terminal |
?shell=bash|zsh|fish|powershell|cmd |
text/plain script for an already open terminal (see below) |
activate passes options to the interceptor. electron starts the executable at
options.path with options.args, so the token grants running programs as the user. Over MCP
this is refused unless the user opted in (see MCP).
JVM attach
jvm attaches the Akev Java agent to a running JVM (guide).
GET /api/interceptors → metadata:
{
processes: {
pid: number; name: string; // short name: "Main", "app.jar"
mainClass: string; // main class, -jar path or module/class ("" if unknown)
commandLine: string; javaVersion: string | null; javaHome: string | null;
attached: boolean; // the agent routes this JVM to an Akev proxy…
active: boolean; // …this one (attachedPort = this proxy's port)
attachedPort: number | null; attachedAt: number | null; interceptLoopback: boolean | null;
}[];
discovery: "jps" | "process-table"; // how JVMs were found (process table without jps)
jps: string | null; jpsError: string | null;
java: string | null; // first Java that will run the attacher
notes: string[]; // what is / isn't intercepted
}activate options: { pid: number, interceptLoopback?: boolean (false), proxyProperties?: "auto" | "always" | "never" }. Only JVMs listed in processes can be attached to. On success
metadata is { pid, name, java, agent }, agent being the agent's report: proxy,
proxySelector, defaultSslContext, httpsUrlConnection (installed),
existingDefaultContext (patched or unchanged: <reason>), trustStore (temporary store
path or unchanged: <reason>), proxyProperties (set or skipped: <reason>), okhttp
(loaded OkHttp client classes), warnings[], agentVersion, javaVersion, javaVendor,
javaHome. Failures (not attachable, Attach API missing, agent error) return
{ success: false, message }. deactivate with { pid } restores that JVM (also one attached
by an earlier Akev run), without options every attached JVM; restoring fails with 500 if the
agent can't restore a live JVM. Shutting the daemon down restores every attached JVM.
The existing terminal one-liner fetches the setup script. It sends the token in a header read
from curl's config on stdin (-K -), never in the URL. Process arguments, including curl's URL,
are visible to other local users, and printf is a shell builtin, so it spawns no process:
# bash / zsh
eval "$(printf '%s\n' 'header = "Authorization: Bearer <token>"' | curl -sS --noproxy '*' -K - 'http://127.0.0.1:45456/api/setup/terminal?shell=bash')"
# fish
printf '%s\n' 'header = "Authorization: Bearer <token>"' | curl -sS --noproxy '*' -K - 'http://127.0.0.1:45456/api/setup/terminal?shell=fish' | sourcePowerShell downloads the script in-process with the token as a request header, so neither appears in a process list:
iex (& { $c = New-Object Net.WebClient -Property @{Proxy=$null}; $c.Headers['Authorization'] = 'Bearer <token>'; $c.DownloadString('http://127.0.0.1:45456/api/setup/terminal?shell=powershell') })cmd writes the curl config to %TEMP%\akev-curl.cfg with the echo builtin (a pipe would run
it in a child cmd.exe), runs curl with -K on it, deletes it, then calls the downloaded
script. The daemon's interceptor metadata (GET /api/interceptors, existing-terminal →
metadata.shells.<shell>.command) carries the ready-made one-liners. ?token= keeps working
for clients that can't set headers.
Transparent capture (Linux)
A second listener (settings.proxy.transparent, off by default) accepts connections the
firewall redirected to Akev (nftables / iptables REDIRECT). Each connection's original
destination is read from conntrack (SO_ORIGINAL_DST / IP6T_SO_ORIGINAL_DST) and handled
like a CONNECT tunnel to it: TLS is intercepted by SNI (or passed through), HTTP is parsed,
other protocols are piped through. Exchanges get client.via: "transparent". Akev never runs
firewall commands; it generates them. Guide: guide/transparent.md.
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/transparent |
– | TransparentInfo — listener status, redirect check, system facts |
| POST | /api/transparent/plan |
TransparentPlanRequest |
TransparentPlan — the commands (400 with a message for invalid options, e.g. an unknown user) |
interface TransparentSettings { // settings.proxy.transparent (all optional)
enabled: boolean; // false
port: number; // 8001 — next free port (up to +100) when busy; 0 = any
mark: number; // 0 — SO_MARK on Akev's upstream sockets (needs CAP_NET_ADMIN)
}
interface TransparentInfo {
supported: boolean; // Linux
unsupportedReason?: string;
active: boolean; // a redirected connection arrived in the last 10 minutes
listener: TransparentStatus;
system: { platform: string; uid?: number; user?: string; cgroupV2: boolean; ownCgroup?: string;
userManagerCgroup?: string; nft: boolean; iptables: boolean; systemdRun: boolean; executable?: string };
slice: "akev-capture.slice";
}
interface TransparentStatus {
enabled: boolean; supported: boolean; listening: boolean;
port?: number; requestedPort: number; addresses: string[]; // e.g. ["127.0.0.1:8001", "[::1]:8001"]
error?: string; // why it isn't listening
mark: number; markError?: string; // e.g. missing CAP_NET_ADMIN
connections: number; // accepted on the transparent port
redirected: number; // ...with an original destination
direct: number; // ...made to the port directly (handled by Host / SNI)
loops: number; // Akev's own connections sent back by the rules (refused)
lastRedirectAt?: number; // unix ms
recent: { at: number; client: string; originalDestination?: string; process?: string }[]; // newest first, ≤ 20
}
interface TransparentPlanRequest { // all optional, defaults first
mode?: "app" | "user" | "machine";
ports?: "web" | "all" | "custom"; // web = 80 + 443
customPorts?: number[];
backend?: "nft" | "iptables";
command?: string; // app: what to launch (default: a captured "$SHELL")
user?: string; // user: name or uid (must not be Akev's own, unless a mark is set)
exclude?: "uid" | "mark"; // machine: how Akev's own traffic is kept out
launcher?: "systemd" | "cgroupfs"; // app: systemd user slice, or a hand-made cgroup
excludeDestinations?: string[]; // IPs / CIDRs never redirected (loopback never is)
trustCa?: boolean; // true — app: CA trust variables on the launch command
sudo?: boolean; // true — prefix root commands with sudo
}
interface TransparentStep { title: string; command: string; root: boolean; description?: string }
interface TransparentPlan {
mode: string; backend: string; port: number; summary: string;
setup: TransparentStep[]; // run in order
launch?: TransparentStep; // app mode
test: TransparentStep; // prints 200 when redirection reaches Akev
teardown: TransparentStep[];
rules: string; // the nft ruleset / iptables commands alone
warnings: string[]; notes: string[];
}The transparent-linux interceptor (Linux only, needsConfig) exposes the same thing to the
catalogue and MCP: info.metadata = { listener, system, slice }, active = the redirect check
above, and activate with a TransparentPlanRequest as options returns the plan as
metadata. deactivate fails with the teardown command: removing firewall rules needs root.
The listener binds 127.0.0.1 and ::1 (locally redirected connections arrive there) plus the
proxy's bind address. PUT /api/settings applies changes immediately and rejects
transparent.port equal to proxy.port while enabled.
Settings & certificate
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/settings |
– | Settings |
| PUT | /api/settings |
Settings |
Settings (applied live; port / bind address changes rebind the proxy, see below) |
| PATCH | /api/settings/ui |
any JSON | 204 (replaces settings.ui) |
| GET | /api/ca |
– | CaInfo |
| GET | /api/ca/cert.pem |
– | PEM (application/x-pem-file, attachment akev-ca.pem) |
| GET | /api/ca/cert.der |
– | DER (application/x-x509-ca-cert, attachment akev-ca.crt) |
| POST | /api/ca/regenerate |
– | CaInfo (the proxy restarts on its current port and bind address) |
--proxy-port / --proxy-bind apply to the current run only. They are never written to
settings.json, so GET /api/settings keeps returning the stored values, while
Status.proxy reports the live ones. PUT /api/settings moves the proxy only for listener
fields that differ from the stored settings. A field sent back unchanged keeps its live value.
For example, toggling proxy.bindAddress keeps the port the proxy listens on now, even if that
port came from --proxy-port or a fallback.
To move the proxy to the stored port anyway (after a busy-port fallback, or to drop a
--proxy-port / --proxy-bind override for the rest of the run), use the explicit rebind:
| Method | Path | Body | Response |
|---|---|---|---|
| POST | /api/proxy/rebind |
{ port: number, bindAddress?: string } (default: the bind address in effect) |
Status["proxy"] — 400 invalid port/address, 409 when that exact port is in use (the proxy stays where it was; it never falls back to another port here) |
It always rebinds and doesn't change settings.json; the new address becomes the preferred one
for the run (CA regeneration restarts the proxy there).
Settings.proxy.http3 (all optional, defaults shown) — HTTP/3 over QUIC, applied live:
interface Http3Settings {
upstream: "off" | "alt-svc" | "prefer"; // "off" — when requests to HTTPS servers use HTTP/3:
// never; for origins that advertised `Alt-Svc: h3=...`
// (cached for its `ma`); or first for every HTTPS origin.
// A failed QUIC connection always falls back to TCP.
listen: boolean; // false — accept HTTP/3 from clients on a QUIC (UDP) listener
listenPort: number; // 0 — its UDP port; 0 = the proxy's port number
}The listener binds proxy.bindAddress and follows rebinds when listenPort is 0. Its state is
in Status.proxy.http3; a UDP port that can't be bound is reported there (error) instead of
failing the settings update, and a port in use is retried for a few seconds (and on every later
settings change). See the HTTP/3 guide.
Settings.sessions (all optional, defaults shown) controls autosave, see Sessions:
interface SessionSettings {
autosave: boolean; // false — save traffic to the "Autosave" session periodically and on shutdown
autosaveIntervalSecs: number; // 60 (1–86400) — only when the traffic changed since the last autosave
restoreOnStartup: boolean; // true — load the autosave back at startup (only while autosave is on)
autosaveMaxExchanges: number; // 100000 — newest exchanges kept (pinned always kept); 0 = unlimited
autosaveMaxBytes: number; // 1073741824 — captured body bytes kept, newest first; 0 = unlimited
}Upstream TLS fingerprints
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/tls-profiles |
– | TlsProfiles — the profiles and whether this build can present browser fingerprints |
type TlsProfile = "native" | "chrome" | "firefox" | "safari" | "edge" | "mirror-client";
// Settings.proxy.tlsProfile (defaults shown). Unknown profile names read as "native".
interface TlsProfileSettings {
profile: TlsProfile; // "native"
overrides: { host: string; profile: TlsProfile }[]; // [] — host globs ("*.example.com", "host:8443"); first match wins; empty hosts → 400
}
interface TlsProfiles {
available: boolean; // browser profiles work in this build (cargo feature `impersonate`)
backend?: "BoringSSL"; // when compiled in
profiles: {
id: TlsProfile;
label: string;
description: string;
imitates?: string; // e.g. "Chrome 133+ (desktop)"
ja4?: string; // expected JA4 with h2 offered
http2?: string; // Akamai HTTP/2 fingerprint
available: boolean;
}[];
}Precedence per request: a matching tls-profile rule, then the first matching override, then
profile. mirror-client uses the intercepted client's browser family — from its ClientHello's
JA4 (cipher hash), refined by its User-Agent (Edge shares Chrome's TLS stack), or the
User-Agent alone for plain-HTTP clients — and native for clients that aren't a recognised
browser. In builds without the backend every profile falls back to native and
UpstreamFingerprint.note says so. Profiles only change TLS and HTTP/2 framing: request headers
are forwarded as the client sent them. TLS to HTTPS upstream proxies always uses the native
stack. Changing the setting doesn't drop pooled connections (the fingerprint is part of the
pool key).
Import / export
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/export/har |
?ids=1,2,3 (optional) &filter= &redact=1 |
HAR JSON attachment, streamed (chunked, no Content-Length; constant memory). redact=1 replaces secrets with [redacted] (what is redacted) |
| POST | /api/import/har |
HAR bytes | { ids: number[] } |
| GET | /api/export/session |
?ids= optional, &redact=1 |
.akev file attachment |
| POST | /api/import/session |
.akev bytes |
{ ids: number[] } |
| POST | /api/import/charles |
Charles JSON session (.chlsj) bytes |
{ ids: number[] } (400 with a reason when it isn't one) |
| POST | /api/import/mitmproxy |
mitmproxy flow file bytes (mitmdump -w, mitmweb Save) |
{ ids: number[] } (HTTP & WebSocket flows; TCP/UDP/DNS flows are skipped) |
| POST | /api/import/fiddler |
Fiddler session archive (.saz) bytes, from Fiddler Classic or Fiddler Everywhere |
{ ids: number[] } (400 with a reason when it can't be read, or is password-protected) |
Charles: bodies Charles decoded ("decoded": true) are stored decoded with their
Content-Encoding removed; FAILED / incomplete transactions import as aborted with the error
mapped to an error kind; CONNECT transactions without SSL proxying become tunnel rows;
WebSocket messages, notes, TLS and timing details are kept. mitmproxy: raw (still encoded)
bodies, WebSocket messages, client/server TLS & addresses, connection timings, comment → note
and marked → colour tag.
Sessions
Named sessions saved in the data directory (sessions/<id>.akev, the native session format,
plus a small <id>.json sidecar). Writes stream from the store to a temp file and replace the
target atomically, so a crash never leaves a half-written session.
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/sessions |
– | SessionInfo[] (most recently updated first) |
| POST | /api/sessions |
{ name, ids?: number[], filter?: string } (all traffic, or the ids and/or the filter's matches) |
SessionInfo |
| GET | /api/sessions/:id |
– | the .akev file (attachment named after the session, streamed, not re-compressed) |
| PUT | /api/sessions/:id |
{ name } |
SessionInfo (renaming an autosave keeps it as a saved session with a new id) |
| DELETE | /api/sessions/:id |
– | 204 |
| POST | /api/sessions/:id/open |
{ mode: "replace" | "append" } (default replace) |
{ ids: number[] } — replace removes all current traffic (pinned too) after the session validated |
interface SessionInfo {
id: string; // stable, file-safe slug of the first name: "checkout-bug", "checkout-bug-2", "autosave"
name: string; // 1–200 characters, no control characters
kind: "saved" | "autosave";
exchanges: number;
size: number; // file size in bytes
createdAt: number; // unix ms
updatedAt: number; // unix ms of the last content write
}Errors: 404 unknown id, 400 invalid name, 422 invalid-session when a session file is
corrupt. .akev files copied into the directory by hand are listed too.
Autosave (settings.sessions.autosave): every autosaveIntervalSecs while the traffic
changed, and once more on graceful shutdown, the traffic is written to the autosave session
(newest exchanges within the autosave bounds, pinned ones always). It runs on a background
thread and never blocks capture. The first autosave of a run keeps the previous run's autosave
as autosave-previous ("Autosave (previous run)") unless it was restored. With
restoreOnStartup, the autosave is loaded in the background at startup; its exchanges get ids
reserved before the proxy starts, so they sort before anything captured meanwhile. When it's
loaded, Status.restoredSession describes it and stream clients get session-restored.
WireGuard mode
An embedded WireGuard server (UDP, userspace): devices that import its client configuration
(QR code in the official WireGuard apps) send all their TCP traffic through the proxy, served as
if it arrived in a CONNECT tunnel to the original destination. Their exchanges have
client.via = "wireguard" and client.interceptor = "wireguard" (source:wireguard).
Guide: guide/wireguard.md.
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/wireguard |
?host= (optional endpoint host for config) |
WireguardInfo — 400 for an invalid host |
| PUT | /api/wireguard |
{ enabled?: boolean, port?: number (1–65535), bindAddress?: string | null } |
WireguardInfo (changes settings.proxy.wireguard: persisted, applied live, broadcast as settings) |
| POST | /api/wireguard/regenerate |
– | WireguardInfo — new server and client keys; configurations handed out before stop working; a running server restarts with them |
| GET | /api/wireguard/config |
?host= |
the client configuration, text/plain attachment akev.conf |
The wireguard interceptor (GET /api/interceptors, category mobile, needsConfig: true)
reflects the same server: activate / deactivate switch settings.proxy.wireguard.enabled.
settings.proxy.wireguard (all optional, defaults shown):
interface WireguardSettings {
enabled: boolean; // false
port: number; // 51820 (UDP)
bindAddress?: string; // absent = all interfaces (0.0.0.0); "::" = dual-stack
}A server that can't start (e.g. the port is in use) doesn't fail the settings change: the
settings are the desired state, WireguardInfo.error says why it isn't running (and a notice
is broadcast). It is retried when the settings change again and at the next start.
interface WireguardInfo {
enabled: boolean;
running: boolean;
port: number; // in the configuration: the bound port while running
bindAddress?: string;
listenAddr?: string; // "0.0.0.0:51820" while running
error?: string; // why it isn't running although enabled
endpoints: string[]; // LAN addresses devices can use (the bind address if specific)
endpoint: string; // "host:port" written into config
config: string; // [Interface] PrivateKey, Address = 10.0.0.2/32, DNS = 10.0.0.53
// [Peer] PublicKey, AllowedIPs = 0.0.0.0/0, ::/0, Endpoint
qrPayload: string; // what to encode in the QR code (= config)
configFileName: "akev.conf";
serverPublicKey: string; // base64
clientAddress: "10.0.0.2/32";
dnsAddress: "10.0.0.53";
keysCreatedAt: number; // unix ms
peer: WireguardPeer;
stats?: { // while running
listenAddr: string; peer: WireguardPeer;
tcpActive: number; tcpTotal: number; tcpRejected: number; // connections handed to the proxy
dnsQueries: number; udpFlows: number; udpRelayed: number;
quicDropped: number; droppedPackets: number;
};
}
interface WireguardPeer {
publicKey: string; // the client's
endpoint?: string; // where its packets come from
lastHandshakeAt?: number; // unix ms (current session)
lastSeenAt?: number; // unix ms (last authenticated packet)
rxBytes: number; // IP bytes received from the device
txBytes: number; // IP bytes sent to it
connected: boolean; // a session younger than WireGuard's 3-minute lifetime
}Keys are stored in wireguard.json in the data directory (mode 0600 on Unix).
Inside the tunnel, 10.0.0.53 answers DNS over UDP and TCP (resolved on the Akev machine;
akev.cert → 10.0.0.1, where the proxy serves its setup page), UDP 443 (QUIC) is dropped,
other UDP is relayed and ICMP is dropped.
Protobuf schemas
.proto files and descriptor sets the user imported. They are compiled at runtime (protox) into
one descriptor pool and used to decode protobuf, gRPC and gRPC-Web bodies with names (body
views of exchanges, Compose / replay responses, MCP akev_get_exchange). Stored in the data
directory under protos/ (in memory only for --ephemeral sessions).
| Method | Path | Body / Query | Response |
|---|---|---|---|
| GET | /api/protos |
– | ProtoRegistry |
| POST | /api/protos |
JSON { files: { name, content?: string, base64?: string }[] } (exactly one of content / base64 per file), or the raw bytes of one file with ?name= |
ProtoRegistry (files added or replaced by name; files that don't compile are kept with their errors) |
| DELETE | /api/protos |
?name=<name> (one file) or ?all=1 (every file; mappings are kept) |
ProtoRegistry |
| GET | /api/protos/file |
?name=<name> |
the file as uploaded (text/plain for .proto, application/octet-stream otherwise) |
| GET | /api/protos/mappings |
– | ProtoMapping[] |
| PUT | /api/protos/mappings |
ProtoMapping[] |
ProtoMapping[] (validated, trimmed, ids filled in) |
Names are relative paths (shop/v1/catalog.proto: letters, digits, . _ - + @, /
separators; no .. or hidden segments). Names ending in .proto are source text (UTF-8), any
other name is a serialized google.protobuf.FileDescriptorSet (.desc, .pb, .binpb,
.protoset). Limits: 16 MB per file, 2000 files, 128 MB in total. Invalid uploads and
mappings answer 400, unknown names 404.
Imports resolve by exact name, then — when exactly one stored file fits — by path suffix or
file name (the file is then compiled under the imported name, reported as importName). The
well-known google/protobuf/*.proto files are built in; files of uploaded descriptor sets can
be imported too.
interface ProtoRegistry {
files: ProtoFileInfo[];
mappings: ProtoMapping[];
messageTypes: string[]; // every message type the files define, sorted
}
interface ProtoFileInfo {
name: string;
kind: "proto" | "descriptor-set";
size: number;
addedAt: number; // unix ms
importName?: string; // compiled under this name (imports refer to it so)
package?: string;
contains?: string[]; // descriptor sets: the .proto files inside (google/protobuf/* left out)
services: { name: string; methods: { name: string; path: string /* /pkg.Service/Method */; inputType: string; outputType: string; clientStreaming: boolean; serverStreaming: boolean }[] }[];
messages: string[]; // fully-qualified, nested included, map entries excluded
enums: string[];
errors: ProtoError[]; // empty = compiled
}
interface ProtoError { file: string; line: number | null; column: number | null /* 1-based */; message: string }
interface ProtoMapping {
id: string; // generated when empty
enabled: boolean; // default true
pattern: string; // see below
side: "request" | "response" | "both"; // default "both"
messageType: string; // "shop.v1.Item" (a leading "." is dropped)
}
interface SchemaInfo { // BodyView.schema
messageType: string;
source: "grpc" | "content-type" | "mapping";
method?: { service: string; method: string; inputType: string; outputType: string; clientStreaming: boolean; serverStreaming: boolean };
mapping?: string; // the matching mapping's pattern
typed?: any; // protobuf bodies: the typed decode (gRPC: per message in `structured`)
error?: string; // didn't decode with the schema (gRPC: no message did); `structured` keeps the schemaless decode
unknownFields?: string[]; // field paths on the wire the schema doesn't define ("21", "items.9")
}Choosing the message type of a body — the first that applies:
- a
messageType=,proto=ormessage=parameter of the body's Content-Type (application/x-protobuf; messageType="shop.v1.Item"); withencoding=delimitedthe body is a sequence of varint length-prefixed messages andtypedis an array; - gRPC / gRPC-Web content (
application/grpc*): the last two path segments namepackage.Service/Method; requests decode as its input type, responses as its output type; - the first enabled mapping whose
sideincludes the body and whose pattern matches the request URL, when the schemas define its type.
Mapping patterns: * matches any characters (/ included), case-insensitive. A pattern
starting with / matches the path, one containing :// the whole URL, one with a / the host
(:port when not the default) plus path, and one without / the host. Path and URL patterns
match with or without the query string.
Typed decoding applies to protobuf, gRPC and gRPC-Web bodies, and (content-type and mapping
plans only) to binary or unclassified bodies, which become protobuf views (kind: "protobuf")
when they decode. JSON-coded gRPC (application/grpc+json) is never decoded with a schema.
The typed form is the proto3 JSON mapping with field names as declared in the .proto, enum
value names (numbers when unknown), 64-bit integers as JSON numbers, bytes as base64, map
entries sorted by key and the well-known types in their JSON form; fields the schema doesn't
define stay, schemaless, under their numbers. It has its own output budget (the limits of
structured); a decode that would exceed it reports error: "too large to decode with the schema (output limit reached)".
Live stream — GET /api/stream (WebSocket)
Auth via ?token=. Server → client JSON messages:
type ServerMessage =
| { type: "hello"; status: Status; summaries: ExchangeSummary[]; paused: PausedExchange[]; rules: RuleSet; settings: Settings }
| { type: "exchanges"; added: ExchangeSummary[]; updated: ExchangeSummary[] } // batched, max ~30/s
| { type: "removed"; ids: number[] }
| { type: "cleared" }
| { type: "messages"; id: number; messages: StreamMessage[] } // new WS/SSE messages (no payload)
| { type: "paused"; exchange: PausedExchange }
| { type: "resumed"; id: number }
| { type: "message-paused"; message: PausedMessage } // WebSocket message paused at a ws-breakpoint
| { type: "message-resumed"; id: number; pauseId: number } // forwarded, dropped or abandoned
| { type: "rules"; rules: RuleSet } // rules changed elsewhere
| { type: "rule-stats"; stats: RuleStats[] } // at most 2/s
| { type: "settings"; settings: Settings }
| { type: "interceptors"; interceptors: InterceptorInfo[] } // when activation state changes
| { type: "stats"; stats: Status["stats"] } // every 2s
| { type: "notice"; level: "info" | "warning" | "error"; message: string } // e.g. CA expiring
| { type: "capture"; recording: boolean }
| { type: "license"; license: LicenseStatus } // licence or trial changed
| { type: "session-restored"; session: { id: string; name: string; exchanges: number; savedAt: number } } // autosave restored at startup
| { type: "filter-result"; seq: number; query: string; ids: number[] | null; error?: { message: string; start: number; end: number } }
| { type: "pong" };
// `exchanges` messages additionally carry `filtered?: { add: number[]; remove: number[] }` once a filter is set.
// `hello` also carries `pausedMessages: PausedMessage[]` (see WebSocket tools); its `status.license` is the licence state.Client → server:
type ClientMessage =
| { type: "ping" } // server replies { type: "pong" }
| { type: "set-filter"; query: string; seq: number } // server-side filtering for this connectionServer-side filtering: after set-filter, the server replies
{ type: "filter-result", seq, query, ids: number[] | null, error?: { message, start, end } }
(ids: null = matches everything) and from then on every exchanges batch carries
filtered: { add: number[], remove: number[] } — ids that started/stopped matching this
connection's filter (computed on add and on every update, since e.g. status: only matches once
the response arrives). removed/cleared apply to the filtered set implicitly. An invalid
query keeps the previous filter and returns error.
Within one exchanges batch, an id appears at most once (in added if new since last batch,
else in updated with the latest summary).
Recording
| Method | Path | Body | Response |
|---|---|---|---|
| GET | /api/capture |
– | { recording: boolean } |
| PUT | /api/capture |
{ recording: boolean } |
{ recording } — when false, traffic is still proxied (and rules applied) but not stored. Broadcast as { type: "capture", recording } on the stream. |
MCP — POST /mcp (Streamable HTTP, JSON-RPC 2.0)
Model Context Protocol server so AI agents can inspect and change traffic, with the same
Authorization: Bearer <token> as the rest of the API. The tools, their arguments and which
need Pro are listed in MCP for AI agents; setting up Claude Code, Claude
Desktop, Cursor and VS Code is in Set up your client.
akev_send_requesttakes the Compose options (httpVersion:auto|http1|http2|http3, seeSendOptions). Results carryrecorded: false(and a note) when the exchange wasn't stored.akev_llm_conversation { id, maxTextChars? }returns the LLM conversation of an LLM API call (texts cut tomaxTextChars, default 20000; inline image data left out). List rows ofakev_list_exchangescarryllm: { provider, model }; filter withis:llm.- Tools that launch or reconfigure programs, replace rules or clear traffic
(
akev_activate_interceptor,akev_set_rules,akev_clear_traffic) are annotateddestructiveHint: true; clients that honour it ask the user first.electron(an arbitrary executable with arbitrary arguments) is refused over MCP unless Akev runs withakev start --mcp-allow-launch(orakev mcp --allow-launchfor an embedded instance;AkevOptions::mcp_allow_launch). Agents read captured traffic, which attackers can influence, so a prompt injection must not be able to start programs. The UI and REST API are not affected.
Tools that change something — akev_send_request, akev_replay, akev_set_rules,
akev_add_mock, akev_resume_breakpoint, akev_set_recording, akev_clear_traffic and
akev_activate_interceptor — need the Pro feature mcp-write, and akev_llm_conversation
needs llm-lens. Without it they return a tool error naming the feature.
The read tools are free and unlimited. See MCP.
akev mcp (stdio) bridges stdio JSON-RPC to this endpoint for MCP clients that spawn
processes (Claude Code, Cursor, etc.).
Device setup (served by the proxy port)
Requests through the proxy to http://akev.cert/ (or directly to http://<proxy-ip>:<port>/)
return a mobile-friendly setup page with CA download links (/ca.pem, /ca.crt, /ca.mobileconfig
for iOS) and instructions. No auth (CA certs are public).