Quick start

From a fresh checkout to your first record over the REST API, in under five minutes.

8 steps
~5 min
Requires Bun
Updated for v0.27.1

Build and run

git clone https://github.com/vaultbase-sh/vaultbase
cd vaultbase
bun install
(cd admin && bun install)   # the admin UI has its own dependencies
bun run build   # compiles admin + binary → ./vaultbase
./vaultbase     # starts on :8091

The first bun run build takes about 30 seconds (it compiles the admin UI and bundles the Bun binary). After that, ./vaultbase starts in milliseconds.

Pick the database

The command above runs on SQLite: a data.db file in ./vaultbase_data, nothing to set up. For this guide that is all you need.

To run on Postgres (beta) instead, stop it and start it with the URL of an empty database:

VAULTBASE_DATABASE_URL=postgres://user:pass@localhost:5432/vaultbase ./vaultbase

Choose before you create the admin: the server uses one database, and nothing is copied between them. See Databases for how they differ.

Setup wizard

Open localhost:8091/_/. On a fresh install you’ll see a setup wizard; its first step shows which database the server is on.

Pick an admin email and password (12+ characters by default).
Sign in with them. You land on the Dashboard.

Create a collection

Open Collections, click New collection and fill in the modal:

Name: posts
Type: Base (default)
Schema: +text title, Required · +text body

Click Create collection. Behind the scenes Vaultbase creates a real table with native columns, not a JSON blob:

CREATE TABLE vb_posts (
  id         TEXT PRIMARY KEY,
  title      TEXT NOT NULL,
  body       TEXT,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
);

Set the API rules

New collections are admin-only: until you open them up, GET /api/v1/posts returns 403 to anyone who isn’t an admin. Open the posts collection, switch to the API rules tab and set:

List: Public
View: Public
Create: Auth only — any signed-in user
Update / Delete: Admin only (leave as is)

Click Save. Anyone can now read posts; creating one needs a signed-in user. Read more about rules →

Add a record from the admin

Open the posts collection, click New record, fill in title and body, then Create. It appears in the table.

Hit the REST API

# List records
curl http://localhost:8091/api/v1/posts

# Get one record
curl http://localhost:8091/api/v1/posts/<id>

# Filter + sort (URL-encode in real use)
curl 'http://localhost:8091/api/v1/posts?filter=title~"hello"&sort=-created'

# Create. Needs a signed-in user, since create_rule is "Auth only"
curl -X POST http://localhost:8091/api/v1/posts \
  -H "Authorization: Bearer <user-token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"hello","body":"world"}'

{
  "data": [{
    "id": "abc-123",
    "collectionName": "posts",
    "title": "hello",
    "body": "world",
    "created": 1730000000,
    "updated": 1730000000
  }],
  "page": 1, "perPage": 30, "totalItems": 1, "totalPages": 1
}

Save this as watch.ts and run bun watch.ts:

const ws = new WebSocket("ws://localhost:8091/realtime");
ws.onopen = () => ws.send(JSON.stringify({ type: "subscribe", topics: ["posts"] }));
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Create or edit a post in the admin and the event prints live.

What’s next

Concepts Collections Base, auth, view and singleton types Concepts API rules The expression language API reference Records Every query parameter Guides Deployment Running in production

To see it all in an app, the todo example has sign-in, rules that keep each user’s todos private, and realtime sync across tabs, in one TypeScript file.