fak documentation
Primary audience: people entering the documentation who need to choose a current route by job. fak is one Go agent-kernel binary that adjudicates tool calls before they run, reuses shared setup, routes calls, serves repeats locally, and manages context.
Default next action: run the deterministic offline proof in the reproducibility packet with fak agent --offline. It needs no API key, model, or GPU and ends with checkable task-completion and blocked-operation results.
Choose your route
| You are… | Start here | Use this route to… |
|---|---|---|
| Evaluating fak | Reproducibility packet | Identify the product, run the offline proof, then inspect its evidence. |
| Building or integrating an agent or client | Managed agent runtime | Choose an interface, understand ownership, and follow the proposal-to-continuation flow. |
| Deploying or operating | Deployment guide | Choose an operating envelope, then configure and observe the service. |
| Contributing | Contributor guide | Build, test, change, and prove the repository under its current contracts. |
| Researching design or history | Notes archive | Find rationale and dated evidence, then check current code and tests before relying on it. |
For a human role map, use START-HERE.md. Agents that need a compact authority map should use llms.txt. The exhaustive audience, task, and lifecycle catalog is INDEX.md.
Authority and lifecycle
This page is the current, public documentation landing page for the current generation. Runtime behavior is authoritative in code and tests; operational pages link to their owning commands and proofs. Pages marked experimental, simulated, stubbed, superseded, or historical describe a narrower lifecycle and do not override current authorities. Dated material under notes/ provides provenance rather than the default product contract.
This landing page supports route selection for the offline proof, managed runtime, integrations, HTTP service, policy floor, deployment, and contribution workflow. It does not establish availability for accelerator hardware or private control channels; those environment-specific routes state their own prerequisites and support boundary. Begin with the offline proof unless your task requires one of those envelopes.
What fak does
The everyday wins first — the reasons most people put fak in front of an agent:
- Cheaper long sessions. A long conversation re-sends its whole transcript every
turn, and the provider only discounts it while the cached prefix stays byte-for-byte
the same.
faksheds the un-cacheable middle turns by splicing on the original bytes (a memcpy, never a re-marshal), so the prompt-cache discount survives instead of breaking. It guarantees prefix byte-identity, and relays the provider’s cache number rather than claiming it. - The right model per call.
fak routeroutes an aspect (a tool call, a reasoning step, a stage) to a different model, with first-class ensembles (vote,best_of). An easy read goes to a cheap model; a write-shaped call goes to a careful one. - Fewer wasted turns. A repeated read is served locally, a malformed call is repaired in place, and a dead-end branch is refused before the agent spends a turn on it. Shared work is computed once because the KV cache is a kernel object, not a rented one.
- A trail you can audit. Every decision is a plain verdict (
ALLOW,DENY,TRANSFORM, orQUARANTINE) in JSON logs, an optional hash-chained journal, and Prometheus metrics.
And the tool-call control floor, for teams that need one (more in Tool-call controls):
- Stops prompt injection and tool poisoning by structure. Suspicious tool results are quarantined out of the model’s context entirely; dangerous tools are never on the allow-list. Two independent gates, not one evadable classifier. Addresses the OWASP Agentic Top-10 and the MCP Top-10 (Tool Poisoning, Memory Poisoning).
- Default-deny capability security. The permission policy runs inside the kernel, on the same call path as the tool call. It fails closed, not open.
- Addressable, bit-exact KV cache. Evict one span from the middle of a kept
model run — a poisoned result, an expired secret — and leave the cache
bit-for-bit identical to a run that never saw it (
max|Δ| = 0). No shipped serving engine offers mid-run causal eviction. - Cache-efficient agent fleets. ~4× fewer tokens than a tuned warm-cache stack on a 50-turn × 5-agent run; 8.8–9.7× modeled prefill elimination vs the naive floor over the real WebVoyager web-agent set (1.0–1.1× vs a tuned per-agent KV).
See each win in one example
Each idea shrinks to a single worked example. The numbers trace to the benchmark authority; the live versions run on the demos page. Or watch the worked examples as a ~25-second reveal.
- A poisoned turn, removed mid-run. Quarantine evicts a tool result’s K/V from the middle of the
kept run and re-seats every survivor, leaving the cache bit-identical to one that never saw it
(
max|Δ| = 0). → Watch a turn vanish - More tool calls, more turns saved. On one 14-call agent trace a naive loop is forced into 9 extra model round-trips and a tuned 2026 framework into 5; the kernel resolves them in-syscall, for 0. → The turn that never fires
- Pay the shared prefix once. 5 agents × 50 turns is 250 chances to re-read the setup: naive pays 250×, a tuned warm cache 5×, fak once: 4.1× vs tuned, 62.0× fewer prefill tokens. → The setup-payments table
- More hooks, sooner. Four checks across 1,000 tool calls is ~28 s of gate latency if you spawn a hook per check, or ~10 ms in-process, which is what makes fail-closed the default. → The cost of checking everything
What fak is not
fak is not a drop-in replacement for tuned token engines. Use vLLM, SGLang,
llama.cpp, or a hosted provider when raw tokens/sec is the job, and put fak serve
in front for the agent boundary: which effects are allowed, which results may enter
memory, when reuse is still legal, what gets audited, and what survives a session
boundary. The in-kernel model path is a correctness/reference engine with narrow
witnessed performance rungs; broad serving-speed claims need a benchmark-authority
row, not a slogan.
Tool-call controls
If a hard capability floor is why you’re here — not just a nice-to-have — this is the load-bearing idea.
Treat the model like an untrusted program, and the tool call like a syscall: the
model proposes, the kernel disposes. Most agent security tries to recognize bad text.
Recognizers help; they are not the floor. Prompt injection is a text game, and attackers
get turns too. fak moves the load-bearing decision to the capability floor: a dangerous
tool outside the allow-list cannot be called, no matter what the model was told.
Two independent gates matter:
- Call-side gate: tool names and selected arguments are checked before dispatch, on
the same call path as the tool call (one address space, no IPC,
default-deny). A denied call never reaches the tool runner, and a check that crashes or times out fails closed. - Result-side gate: tool output is screened before it enters context. A poisoned or secret-bearing result is paged out or quarantined instead of being handed back to the model as trusted text. The detector is treated as evadable by design, a bonus rather than the floor; the floor is the dangerous lever simply not existing.
The capability floor is the guarantee. Irreversible effects are unwired by default; untrusted bytes have to pass a gate before they become model context. Read Policy in the kernel, POLICY.md, and the security model.
Try it in 2 minutes (no key, no model, no GPU)
Get the binary — no clone, no Go toolchain. The installer detects your OS/arch,
downloads the prebuilt static binary for the latest release, verifies its checksum, and
drops fak on your PATH:
curl -fsSL https://raw.githubusercontent.com/anthony-chaudhary/fak/main/install.sh | sh
fak version # prints the installed version, e.g. 0.34.0
Now prove the floor from the bare binary — these need no clone and no examples/ dir:
fak preflight --tool refund_payment --args "{}" # -> DENY (DEFAULT_DENY): unknown tool, fail-closed
fak preflight --tool search_kb --args "{}" # -> ALLOW: a read-shaped name is not blanket-blocked
fak agent --offline # runs one task twice — tools wired directly vs. behind fak — and prints the before/after
The dangerous action is refused by structure, before any model interpretation matters. Then wrap the agent you already run — one command, no rewrite, no key to start:
fak guard -- claude # or: fak guard --provider openai -- opencode
Have the source already? From a clone you can skip the install and run the same proof against a named example floor, where the deny is by argument value:
go run ./cmd/fak preflight --policy examples/customer-support-readonly-policy.json --tool refund_payment --args "{}". Full paths in INSTALL.md (one-line installer · manual download · Docker · build-from-source · Windows).
Learn more
| If you want… | Read |
|---|---|
| The principles fak is built to satisfy | Charter |
| Structured-output decoding SOTA + fak’s ride-mode surface (#907) | Research note |
| Prior art + threat model for a centrally-administered org policy plane (epic #5315) | Research note |
| Org-policy precedence lattice: compiled-in FROZEN floor > central > operator > agent-self (R3 / #5318) | Research note |
| Keeping a stable core as models × backends × features multiply | Combinatorial-growth epic |
| Constructing many on-demand “views” of the token history at marginal cost (attention/KV side-cars, re-attend tiers) | Research note |
| The quick answers | FAQ |
| A guided first run | Tutorial |
| What the words mean (preflight vs inflight vs prefill; cache rebate / net saving) | Glossary |
| How shared state is split | Shared state ladder |
| A collaborative task state contract | Shared task record contract |
| When managed context should append or reconstruct the task | Query, not chat — originating-task pin and checkable reseed-versus-append rule |
| How to construct model-visible directives | Positive-state construction — broadcast the target state instead of a negation operand |
| How negframe and managed context form one pipeline | Shared-workspace positive state — exact gateway emit seam, wired surfaces, and current limits |
How every new unit of work is scoped and shipped (spine-first, then fan out the backlog with fak issue fanout) |
Spine-first + fan-out defaults |
| How agents discover fak features and memory tools | Self-feature query spine |
| The two core ideas | Policy in the kernel · Addressable KV cache |
| Why a cache-hit % isn’t the whole story | Context signal-to-noise |
| How fak runs the agent as nested loops | Engineering is building loops |
| Why a loader can pass every shape/dtype check and still be wrong | Semantic transform contracts — the tensor-meaning defect class and the contract that catches it |
| Every benchmark number | Benchmark authority |
| Every per-run benchmark sheet (results · runbooks · pending/gated) | docs/benchmarks index |
| Everything fak supports | What fak supports — models · features · clouds · APIs/MCP · harnesses · engines |
| Every machine fak runs on | Hardware matrix (4 platforms · 2 CPU ISAs · 4 GPU backends) |
| How fak serves at scale | Serving plans — dual-track · poly-model · hardware-aware & regenerable KV |
| What’s real, what’s not | Claims ledger |
| The leadership snapshot (wins · live goal · risks · the one decision) | Executive roll-up |
| How fak maps to what enterprises are buying (runtime enforcement · prove-it · cost kill-switch · NHI · tamper-evident audit · air-gap) — every stat sourced, every claim fenced shipped/ticketed | Enterprise positioning |
| A machine-readable map (for LLMs) | llms.txt |
License: Apache-2.0 · Report a vulnerability · Keywords: Fused Agent Kernel, fak agent kernel, fak guard, fak serve, fak-certified, agent kernel, AI agent runtime boundary, long-session prompt cache, model routing for agents, MCP tool-call boundary, local GGUF, KV cache, addressable KV cache, self-hosted LLM, LLM agent fleet, agentic AI, Go.