title	fak — the agent kernel \| cheaper long sessions, the right model per call, audited tool-call control
description	fak is one Go binary you put in front of the AI agent you already run — Claude Code, Codex, Cursor, or any OpenAI / Anthropic / MCP client. Cheaper long sessions, the right model per call, fewer wasted turns, and an auditable verdict for every tool call.

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.

FAK coordinates the whole agent path, not isolated components. Start with the canonical architecture map for the five-layer observation → constrained-plan → typed-effect contract, then use the glossary to keep coordination, orchestration, scheduling, routing, and serving distinct.

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.
Improving or comparing local inference	Fak-native inference doctrine	Keep native product work inside fak, classify explicit llama.cpp uses, and apply the matched-envelope rule.
Deploying or operating	Deployment guide	Choose an operating envelope, then configure and observe the service.
Contributing	Contributor guide and developer tooling	Find the owning document first, then 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.

Choose the smallest efficiency layer

Less context, less code: where fak fits beside Caveman and Ponytail — answer-first guide to concise output, YAGNI/minimal-code guidance, and fak runtime cache, context, reuse, recovery, and policy.

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. fak sheds 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 route routes 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, or QUARANTINE) 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 serve in proxy/gateway mode is not a claim that fak authored the upstream token engine. An explicitly selected vLLM, SGLang, llama.cpp, or hosted-provider route remains external inference while fak owns the agent boundary: which effects are allowed, which results may enter memory, when reuse is legal, what gets audited, and what survives a session boundary.

That gateway boundary does not turn the native engine into a permanent reference-only path. For local inference, fak-native is the product and performance path, intended to beat llama.cpp in matched, quality-constrained envelopes while retaining ownership of kernels, memory, scheduling, cache, adaptation, and operations. Current broad serving-speed claims still need a benchmark-authority row; the doctrine is the direction, not a substitute for evidence.

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 manage claude           # short: fak m claude; or: fak manage --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

Token-efficiency field map: Awesome Token Efficiency — prompt caching, context engineering, KV-cache reduction, serving, and agent-layer methods with loss/fidelity and fak-status labels. | If you want… | Read | |---|---| | Codex UserPromptSubmit modes, capability floor, and installer/runtime verbs | OpenAI Codex integration — UserPromptSubmit modes | | The principles fak is built to satisfy | Charter | | What changed recently | Witnessed recent changes — generated from authoritative commits, issues, claims, and module versions; freshness-bounded and grouped for humans | | 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 | | Current performance borrow map for agentic and model-runtime sources | Research note | | Related-system inventory contract for deep study-repo passes | Research note | | Qwen4 experimental support rollback watch and cutover evidence | Operational note | | Choosing repository indexes for exhaustive study inventories | Decision matrix | | 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 new work becomes readable and dispatchable (outcome, leaf, attempt, witness; explicit scope, dependencies, acceptance, and placement) | Shift-left task organization | | How every new unit of work is scoped and shipped (applied spine first, then exhaustive proof, measured optimization, and backlog fan-out) | 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 | | How named context is loaded, filtered, cached, and backed by call snapshots | Context as a variable | | 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 | | How agent lifecycle, model, and fleet scale differ | Agent scale hierarchy — macro, baseline, sub-agent, and micro | | What a micro agent is, and when to use one | Micro agents — definition, lifecycle, limits, and a no-key example | | How agent fleets coordinate workers safely | Fleet concepts — workers, lanes, leases, seats, monitoring, and independent witnesses | | 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 |

Additional documentation routes

Documentation maintenance: Indexed document sets defines the bounded-page and reciprocal-index contract for maintained long-form Markdown.
Session control and trajectory: Child-agent registration and lineage, Session lifecycle reconciliation, Trajectory assurance receipt, and Workflow concepts: the operator's middle layer.
Local application runtime: Local-app compute layer explains the browser-to-daemon boundary, loopback security, offline behavior, and accelerator ownership; job-apply migration runbook gives the shortest supported signed-desktop-app integration path.
Tool-result and work accounting: Operate tool-result budgets safely, Work-accounting coverage, Work delivery: recording is not readiness, Work-done baselines, Work-done history, Work-done query contract, and Work-done source provenance.
Captured read-backs and witnesses: Current task queue read-back and Issue 9020 — owned Metal session profile.

_{License: Apache-2.0 · Report a vulnerability · Keywords: Fused
Agent Kernel, fak agent kernel, fak manage, 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.}

Claude usage guides

KV capacity normalization — compare block-oriented and direct KV metrics in tokens, bytes, and occupancy without inventing unavailable values.

Scoreboard debt discovery index

These links expose captured evidence and maintained scorecard/research clusters to the documentation crawler without changing their content or scorecard coverage.

Scoreboard debt discovery index

These links expose captured evidence and maintained scorecard/research clusters to the documentation crawler without changing their content or scorecard coverage.

FilesExpand file tree

index.md

Latest commit

History

index.md

File metadata and controls

fak documentation

Choose your route

Authority and lifecycle

Choose the smallest efficiency layer

What fak does

See each win in one example

What fak is not

Tool-call controls

Try it in 2 minutes (no key, no model, no GPU)

Learn more

Additional documentation routes

Claude usage guides

Scoreboard debt discovery index

Scoreboard debt discovery index