Operations

Quickstart

Run the community gateway in front of your existing turbopuffer account. 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.

1. Clone the repo

git clone https://github.com/hev/layer.git
cd layer

2. Configure and start the gateway

Copy the example env file and fill in your turbopuffer API key:

cp .env.example .env
# edit .env and set TURBOPUFFER_API_KEY=tpuf_...

Then start the gateway:

docker compose up

The bundled docker-compose.yml runs the hevlayer/layer-gateway image against api.turbopuffer.com with a restart policy and health check. Check it in another shell:

curl http://localhost:8080/health

The rest of the steps use these in your shell:

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

3. 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.

4. 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