# hev layer

> Retrieval gateway and transform runtime around turbopuffer.

hev layer is a transparent proxy in front of turbopuffer that adds operational semantics — document cache, namespace snapshots, search history, pipeline state — plus a Kubernetes-native UDF transform runtime for embedding, classification, tagging, and attribute migration.

These docs are queryable from the command line — better than reading this file: install `ask` (`go install github.com/hev/ask/cmd/ask@latest`), then `ask --endpoint https://hevlayer.com/api/ask search "<question>"` for ranked sections with deep links, `section get "<id>"` for detail, `overview` for the full map. Setup and verbs: https://hevlayer.com/docs/agents

The full concatenated docs are at https://hevlayer.com/llms-full.txt.

## Overview
- [Introduction](https://hevlayer.com/docs): Layer is a gateway and function runtime for modern retrieval systems. It scales compute for multi-stage indexing pipelines and runs functions across every row of your index, with all durable state in object storage.
- [Concepts](https://hevlayer.com/docs/concepts): How the gateway composes turbopuffer, the document cache, PostgreSQL, S3, and metrics — and the core nouns you'll work with.
- [Document model](https://hevlayer.com/docs/document-model): A Layer document and the reserved attributes the gateway manages on every row.
- [No Guarantees](https://hevlayer.com/docs/guarantees): Layer can't offer guarantees — here's what we commit to instead.
- [Tradeoffs](https://hevlayer.com/docs/tradeoffs): The current product posture and the cases it is not trying to cover.
- [Limits](https://hevlayer.com/docs/limits): Current ceilings inherited from the components we ship with, and what we don't cap.
- [Agents](https://hevlayer.com/docs/agents): Use the Layer docs and layer CLI from your coding agent with one-file skills that work across agent harnesses.
- [Demos](https://hevlayer.com/docs/demos): Live applications built on Layer — query routing, hybrid text fusion, semantic image search, and a full storefront workload — each composing shipped gateway features over a different corpus.
- [Changelog](https://hevlayer.com/docs/roadmap): What has shipped in hev layer, and what is coming next.
- [FAQ](https://hevlayer.com/docs/faq): Licensing, pricing, trials, and how to get started.

## Operations
- [Quickstart](https://hevlayer.com/docs/quickstart): Clone the repo, run the community gateway with Docker Compose, initialize a namespace, and run a query — no license key.
- [Install](https://hevlayer.com/docs/install): How to bring up a hev layer environment: layer install provisions AWS via Terraform and installs the runtime via Helm.
- [Operator Overview](https://hevlayer.com/docs/kubernetes/operator): What layer-operator reconciles and how it relates to the gateway.
- [VectorStore CRD](https://hevlayer.com/docs/kubernetes/vectorstore-crd): Backend connection and gateway inbound auth policy for a Layer install.
- [ApiKey CRD](https://hevlayer.com/docs/kubernetes/apikey-crd): Minted API keys as Kubernetes resources: lifecycle, entitlements, and opaque claims.
- [Warehouse CRD](https://hevlayer.com/docs/kubernetes/warehouse-crd): Declared upstream data source: identity, credential, and verified reachability.
- [Index CRD](https://hevlayer.com/docs/kubernetes/index-crd): Declarative representation of a namespace managed by Layer.
- [InfraRules CRD](https://hevlayer.com/docs/kubernetes/scaling-crd): Cluster-wide compute pools, document cache rules, and workload scaling.
- [Pipeline CRD](https://hevlayer.com/docs/kubernetes/pipeline-crd): Staged row-changing work declared as a Kubernetes resource.
- [Function CRD](https://hevlayer.com/docs/kubernetes/function-crd): Stateless user-defined functions declared as Kubernetes resources.
- [Agent CRD](https://hevlayer.com/docs/kubernetes/agent-crd): Agentic search as a Kubernetes resource: a governed reasoning loop over your indices, bound to a model, a budget, and an entitlement.
- [Failure Modes](https://hevlayer.com/docs/failure-modes): How reads and writes degrade when the gateway, cache, or pipeline runs into trouble.
- [Layer CLI](https://hevlayer.com/docs/cli): The layer CLI manages environments, initializes namespace sharding, observes data-supply resources, indexes, pipelines, and UDFs, mints API keys, and runs Function manifests.
- [Dashboard](https://hevlayer.com/docs/dashboard): Running the in-cluster operations dashboard: the access it needs, networking, auth, and turning it off.

## API
- [Introduction](https://hevlayer.com/docs/api/introduction): What Layer adds on top of the turbopuffer-compatible client wire, and how to point a client at the gateway.
- [Write & Stage](https://hevlayer.com/docs/api/write): Write rows to a namespace and stage documents in the cache.
- [Blobs](https://hevlayer.com/docs/api/blobs): Durable content-addressed bytes served through the gateway.
- [Query & Fetch](https://hevlayer.com/docs/api/query): Vector similarity search with stable reads, query by id, and cached document fetch.
- [Federated query](https://hevlayer.com/docs/api/federated-query): Federate one query across a set of namespaces and merge the results into a single ranked list, scoped by the key's entitlements.
- [Agentic search](https://hevlayer.com/docs/api/agents): Run a configured reasoning loop over your indices: plan, fan out for recall, score for relevance, and return the standard row shape.
- [Scan](https://hevlayer.com/docs/api/scans): On-demand row selection by filter, full-text, hybrid-text, or radius — IDs, count, or values.
- [Pipelines](https://hevlayer.com/docs/api/pipelines): Organize a two-stage indexing pipeline: extract + chunk on CPU, embed on GPU, trigger runs and wait for completion.
- [Namespace metadata](https://hevlayer.com/docs/api/namespace-metadata): Read namespace metadata enriched with Layer freshness signals.
- [VectorStores And Warehouses](https://hevlayer.com/docs/api/data-supply): Read declared vector stores and upstream warehouses through the gateway.
- [Warm cache](https://hevlayer.com/docs/api/warm-cache): Warm a namespace's document cache and snapshot mirror.
- [Snapshot History](https://hevlayer.com/docs/api/snapshots): Facet snapshot jobs, history, bodies, and activity streams.
- [Checkpoints](https://hevlayer.com/docs/api/checkpoints): Immutable labels over namespace snapshot watermarks.
- [Query History](https://hevlayer.com/docs/api/search-history): Per-namespace query and clickstream history backed by JSONL in S3.

## Search knowledge graph

Version: 2
Generated: 2026-08-18T13:09:27.390Z
Content hash: 6cea9754ab5ab794e5eb03596f4efef28fce8ebf881e3287488604749e4f5a87

Context:
## Layer (hev layer)

Layer is a Kubernetes-native gateway and compute runtime for retrieval systems. Its Rust gateway fronts Turbopuffer and other supported stores with compatible query/write routes plus stable reads, cached fetches, scans, snapshots, history, federated search, automatic query routing, and reasoning-assisted retrieval. The operator reconciles desired state for stores, indexes, pipelines, functions, credentials, agents, external sources, and shared compute rules.

### Core concepts
- **Storage and durability** — object storage holds durable history and artifacts; Aerospike provides ephemeral fast access; PostgreSQL is limited to indexing queues and state.
- **Query routing and embedding** — Auto chooses lexical, semantic, or fused execution. An inline Embed supplies semantic input in one request and is resolved only when the chosen route needs a vector.
- **Pipelines and Functions** — pipelines ingest external data and may change row count; Functions enrich rows already in Layer while preserving their row identity.
- **Operations** — InfraRules defines compute pools, autoscaling limits, cache policy, and cold-start tradeoffs. The CLI and dashboard expose resources, workloads, credentials, progress, and failures.
- **Identity and access** — ApiKey resources retain credential lifecycle and audit metadata; entitlements separate Layer access from opaque application claims.
- **Installation** — AWS infrastructure and the Kubernetes runtime are provisioned separately, with local license verification gating advanced surfaces while core gateway operations remain available.

Users commonly ask about the gateway, Turbopuffer compatibility, Auto routing, inline embedding, stable reads, warming the cache, scans, snapshots, pipeline versus Function behavior, compute pools, scale to zero, ApiKey rotation and revocation, warehouses, and operator reconciliation. The committed ask digest lets coding agents answer those questions from reviewable documentation before inspecting or changing a deployment.

Glossary:
- stable reads: Layer's default read mode: queries never see partially-indexed rows, pinned to an epoch-ms watermark echoed in the x-layer-stable-as-of header. Aliases: stable watermark, watermark, x-layer-stable-as-of.
- document cache: Layer's pull-through Aerospike hot cache for document reads, pipeline chunks, and snapshot mirrors; misses fall through to turbopuffer or S3. Aliases: cache, aerospike cache.
- HybridText: Layer-only rankby spelling that expands one query string into a BM25 leg plus per-token fuzzy legs, RRF-fused into one typo-tolerant ranking. Aliases: hybrid text fusion, fuzzy search.
- Auto: Layer-only rankby spelling that picks hybridtext, semantic, or fused per query from the input's token count and echoes the decision in a routing block. Aliases: query routing, router, routing.
- Embed: Query/write-time embedding expression resolved by serving mode: native (upstream), autoscaler (provider), or local/lattice (in-process CPU on the gateway). Aliases: embedding, lattice, local clip.
- federated query: POST /v2/query runs one ranking across a set of namespaces and merges results into a single ranked list by distance or rank-interleave. Aliases: multi-namespace query, fan-out.
- agentic search: A configured reasoning loop (POST /v2/agents/{name}/query) that reformulates a query, fans out for recall, scores relevance, and returns the standard federated row shape. Aliases: agent, agents endpoint.
- snapshot: A content-addressed S3 facet histogram written after a namespace is observed stable; serves facet listings, counts, and checkpoint labels. Aliases: facet snapshot, facet histogram.
- scan: On-demand row selection by filter, full-text, hybrid-text, or ANN radius, returning IDs, an exact/approximate count, or distinct field values. Aliases: count, values scan, id scan.
- pipeline: A PostgreSQL-backed two-stage state machine: CPU workers stage chunks, GPU workers claim pending documents and write vectors, with leased claims and KEDA scale-to-zero. Aliases: indexing pipeline, chunking, ingestion pipeline.
- layer install: The single CLI entrypoint that runs Terraform (AWS provisioning) then Helm (in-cluster release) to bring up a hev layer environment. Aliases: install, installer.
- deriveFromStore: Default inbound auth mode where the upstream store's own API key doubles as the gateway bearer token (single-tenant BYOC shape). Aliases: derive from store.
- keys mode: Inbound auth mode with gateway-only bearer keys carrying read, write, and admin scopes. Aliases: inbound keys, gateway keys.
- compute pool: Named worker placement-and-resources bundle (built-in cpu, cpu-large, gpu) that Pipelines and Functions schedule onto; overridable via InfraRules/default. Aliases: pool, cpu pool, gpu pool.
- warm window: Cooldown that holds an autoscaled worker and its node warm after the queue drains, so adjacent batches skip GPU cold starts. Aliases: warmWindowSeconds, cooldown.
- Function: Kubernetes resource declaring a stateless per-row function run over rows already in an Index, with gateway-owned discovery, queueing, and retries. Aliases: UDF, user-defined function.
- Warehouse: Declared upstream source (Snowflake, Hugging Face, REST) holding identity and credential with verified reachability; pipelines extract from it. Aliases: source system, data source.
- ApiKey: Minted credential as a Kubernetes resource: Layer owns mint/verify/revoke/expire, with per-target entitlements, scopes, and opaque claims. Aliases: api key, minted key, scoped key.
- license floor: License state where licensed surfaces degrade to CE behavior — no valid key, expired trial, or commercial key past expiration plus grace. Aliases: floor, grace, license state.
- InfraRules: Cluster-scoped singleton policy object replacing the built-in compute pools and declaring document-cache and workload scaling rules. Aliases: scaling CRD, infra rules.
- install profile: Install footprint selection: demo is the lean evaluation shape (~$40-70/mo at rest); indexing adds a dedicated NVMe document-cache node pool. Aliases: demo profile, indexing profile.