Quickstart

Run Layer on your laptop in front of your existing Turbopuffer account. You’ll need Docker with Compose, Git, curl, and a Turbopuffer API key.

1. Clone and start

Replace tpuf_... with your key before running this block.

git clone --branch v0.6.0 https://github.com/hev/layer.git
cd layer
export GATEWAY_IMAGE=hevlayer/layer-gateway:0.6.0
export TURBOPUFFER_API_KEY="tpuf_..."
docker compose up -d --wait
curl --fail http://localhost:8080/health

The gateway listens on localhost:8080. The 0.6.0 tag is the released image; set GATEWAY_IMAGE=hevlayer/layer-gateway:edge only to opt into the development build. Allow a few minutes for the first image downloads.

For CI setup and standalone configuration, see the repository setup guide.

2. Write rows

The first write creates the namespace. Run this in the same shell as step 1; the authorization header carries your Turbopuffer key.

curl --fail-with-body http://localhost:8080/v2/namespaces/products \
  -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "distance_metric": "cosine_distance",
    "schema": {"title": {"type": "string", "full_text_search": true}},
    "upsert_rows": [
      {"id": "earbuds", "title": "wireless earbuds", "vector": [1, 0, 0]},
      {"id": "speaker", "title": "portable speaker", "vector": [0, 1, 0]}
    ]
  }'

3. Query

curl --fail-with-body http://localhost:8080/v2/namespaces/products/query \
  -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rank_by": ["vector", "ANN", [1, 0, 0]], "top_k": 1, "include_attributes": true}'

The first row has id: "earbuds" and $dist: 0.

Continue with the API docs for client SDKs and query options, or explore the demos to see what you can build.