Quickstart

Run the community gateway in front of your existing turbopuffer account in three steps. No license key or signup needed — your turbopuffer API key is the gateway bearer token, and your data stays where it is.

You need Docker, curl, and a turbopuffer namespace with rows in it:

export TURBOPUFFER_API_KEY="tpuf_..."
export LAYER_NAMESPACE="products"
export LAYER_GATEWAY_URL="http://localhost:8080"

1. Start the Gateway

docker run --rm -p 8080:8080 \
  -e PORT=8080 \
  -e LAYER_SECRET_LOCAL_API_KEY="$TURBOPUFFER_API_KEY" \
  -e LAYER_STORE_JSON='apiVersion: hevlayer.com/v1alpha1
kind: VectorStore
metadata:
  name: local
spec:
  kind: turbopuffer
  default: true
  endpoint:
    url: https://api.turbopuffer.com
    region: aws-us-east-1
  credential:
    secretRef:
      name: local
      key: api-key
  inboundAuth:
    mode: deriveFromStore' \
  hevlayer/layer-gateway

Check it in another shell:

curl "$LAYER_GATEWAY_URL/health"

2. Initialize the Namespace

curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/init" \
  -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema_version": 1, "shard_count": 8}'

Init stamps existing rows with Layer-reserved shard metadata — it is idempotent and self-throttled, and queries keep working while the backfill drains. Watch init_state reach ready at GET /v2/namespaces/$LAYER_NAMESPACE/metadata.

3. Run a Query

curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/query" \
  -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rank_by": ["title", "BM25", "wireless earbuds"],
    "top_k": 10
  }'

The same turbopuffer-compatible routes your application already calls now go through the gateway. From here:

• Query & Fetch — routing, hybrid text fusion, rank expressions
• Scans — scatter/gather counts across the shards you just initialized
• Install — the Helm chart for a real cluster