Quickstart

1. Create an organization

Sign in at console.walleye.dev. The first sign-in asks for an organization name. An organization owns instances, members, API tokens and billing, and starts on the free trial: one ramp small instance until it has used $5.00 of compute, no card required.

To do the same from a script, use a WorkOS session or an organization API key as a bearer token against https://api.walleye.dev:

curl -X POST https://api.walleye.dev/v1/organizations \
  -H "Authorization: Bearer $LAKEDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

2. Create an instance

In the dashboard, open Instances and choose New instance. Pick a name, a shape and a cache tier. ramp with a small cache is the right start; see Shapes and cache tiers.

curl -X POST https://api.walleye.dev/v1/organizations/$ORG/instances \
  -H "Authorization: Bearer $LAKEDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "analytics", "shape": "ramp", "cache": "small"}'

The response is 201 with {"instance": {…}, "token": "…"}. The token is the instance’s bearer token and is returned here exactly once; the dashboard shows it in the same dialog. Provisioning takes a minute or two. Poll the instance until its state is running; the record also carries the instance url:

curl https://api.walleye.dev/v1/organizations/$ORG/instances/$INSTANCE \
  -H "Authorization: Bearer $LAKEDAY_TOKEN"

3. Get the instance token

Each instance has one bearer token. It is never stored in readable form, so it is shown exactly once: when the instance is created, and again whenever you rotate it. If you did not keep the creation token, open the instance in the dashboard and choose Rotate token; the dialog shows the new token with a copy button and the connect snippet below.

curl -X POST https://api.walleye.dev/v1/organizations/$ORG/instances/$INSTANCE/token \
  -H "Authorization: Bearer $LAKEDAY_TOKEN"

{ "token": "…", "url": "https://vt-….fly.dev" }

Rotating again invalidates the previous token as soon as the Machines pick up the new one.

4. Connect with the LanceDB SDKs

The data plane is the instance URL. Send the token as x-api-key (or as Authorization: Bearer). The stock LanceDB clients do this for you.

Python:

pip install lancedb

import lancedb

db = lancedb.connect("https://vt-….fly.dev", api_key="<token>")
table = db.create_table("clicks", data=[
    {"id": 1, "city": "ams", "value": 2.0},
    {"id": 2, "city": "ams", "value": 3.0},
    {"id": 3, "city": "ber", "value": 7.0},
])
print(table.count_rows())
print(table.search().where("city = 'ams'").to_list())

JavaScript:

npm install @lancedb/lancedb

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect({ uri: "https://vt-….fly.dev", apiKey: "<token>" });
const table = await db.createTable("clicks", [
  { id: 1, city: "ams", value: 2.0 },
  { id: 2, city: "ams", value: 3.0 },
  { id: 3, city: "ber", value: 7.0 },
]);
console.log(await table.countRows());
console.log(await table.query().where("city = 'ams'").toArray());

Every write is committed to the instance’s S3 write-ahead log before the SDK gets its acknowledgement. Read What an instance is for the durability model, and Stop, start and resize before you change its shape.