What an instance is

An instance is a Walleye node: a LanceDB server whose durable state is a write-ahead log in S3 and whose working set lives in a RAM/NVMe cache on the Machine. The LanceDB remote protocol is served straight from the instance URL; there is no proxy in front of it.

The instance URL is always https://<app>.fly.dev — the Fly app itself, not a walleye.dev hostname. The control plane and the dashboard live on walleye.dev, but the data plane deliberately does not: putting a database behind an extra proxy hop would add a round trip to every query and buy nothing.

Ownership

Resource	Per instance
Fly app	One, on its own private network. https://<app>.fly.dev is the instance URL.
Machines	One (ramp) or three (launch). Region iad. Always on, except ramp / small, which Fly suspends when idle and wakes on the next request.
S3 bucket	One Tigris bucket holding the write-ahead log and table checkpoints.
Token	One bearer token, at least 32 characters, shown once when rotated.

Nothing is shared between instances or between organizations: no Machine, no V8 isolate, no bucket, no network path.

Durability

A write is acknowledged only after it is durable in S3:

• ramp commits each write to the bucket with an S3 conditional put.
• launch commits each write to an embedded Bitr write-ahead log replicated across the three Machines (quorum of two) and archives it to S3 within a second of the commit.

The cache holds hot fragments and indexes and is rebuilt from S3 whenever a Machine is replaced. Losing a Machine loses no acknowledged write.

Authentication

Send the instance token as x-api-key, which is what the LanceDB SDKs use, or as Authorization: Bearer. Requests without a valid token get 401. GET /healthz is the only unauthenticated route.

The token belongs to the instance, not to a user. Organization members, roles and API tokens control who can create, stop, resize, rotate and delete instances through the Walleye API; they never grant data access by themselves. Rotate the instance token to revoke every client at once.

States

stateDiagram-v2
    [*] --> provisioning
    provisioning --> running
    provisioning --> failed
    running --> stopping: stop
    stopping --> stopped
    stopped --> running: start
    running --> deleting: delete
    stopped --> deleting: delete
    failed --> deleting: delete
    deleting --> deleted

State	Meaning
provisioning	The app, bucket, volumes and Machines are being created. When an attempt fails the runtime retries it; error carries that attempt’s reason until the instance is running.
running	Every Machine is healthy and serving the URL.
stopping	Machines are draining: in-flight commits finish and every table is checkpointed to S3.
stopped	No Machines or volumes exist. Data stays in S3. Resize is accepted.
failed	Provisioning or a start gave up after several attempts, or hit an error no retry fixes; error says why and nothing is in flight. Start retries it.
deleting, deleted	The app, Machines, volumes and bucket are being removed.

A running instance keeps its Machines until you stop it. Every shape and tier is always on except ramp / small: Fly suspends that Machine after a few idle minutes and starts it on the next request, the instance stays running, and its record shows the Machine as suspended while it sleeps. There is no reserve capacity on any tier.

API

GET    /v1/organizations/:org/instances                       200 {instances: [record]}
POST   /v1/organizations/:org/instances   {name, shape, cache}  201 {instance: record, token}
GET    /v1/organizations/:org/instances/:id                   200 {instance: record}
POST   /v1/organizations/:org/instances/:id/stop              202 {instance: record}
POST   /v1/organizations/:org/instances/:id/start             202 {instance: record}; 402 while suspended for billing
POST   /v1/organizations/:org/instances/:id/resize {shape?, cache?}  200 {instance: record}; 409 unless stopped
POST   /v1/organizations/:org/instances/:id/token             200 {token, url}, returned once
DELETE /v1/organizations/:org/instances/:id                   202 {instance: record}

A record is {id, organization_id, name, shape, cache, state, error, url, machines: [{id, node_index, state}], billing_suspended, created_at, updated_at}. url is null until the Fly app is registered and after deletion; machines lists the current generation only, so a stopped instance has none, and a Machine’s state is created, started, stopped or, for a sleeping ramp / small Machine, suspended. 202 means the instance’s runtime accepted the request and will move the record on its own clock; poll GET …/:id until the state you want.

All routes take a WorkOS session or an organization API key as a bearer.