Introduction

Getting Started

Get up and running with Boltstore in under 5 minutes. This guide covers installation, starting the server, creating your first database, and making your first API request.

Installation

Choose whichever method works best for you:

Install Script (macOS / Linux)

# Download and install the latest binary
curl -fsSL https://boltstore.dev/install.sh | bash

The script detects your OS and architecture, downloads the appropriate binary from GitHub Releases, and places it on your PATH.

Download a Binary

Pre-built binaries are available on the GitHub Releases page for:

Platform	File
macOS (Apple Silicon)	boltstore-darwin-arm64
macOS (Intel)	boltstore-darwin-x64
Linux (x64)	boltstore-linux-x64
Windows (x64)	boltstore-windows-x64.exe

Download the file for your platform, make it executable, and move it to your PATH:

# Example: macOS Apple Silicon
chmod +x boltstore-darwin-arm64
sudo mv boltstore-darwin-arm64 /usr/local/bin/boltstore

Install via npm

If you have Node.js installed, you can install Boltstore globally via npm:

npm install -g boltstore

Run from Source

Requires Bun installed:

git clone https://github.com/boltstore/boltstore.git
cd boltstore/boltstore
bun install
bun run dev

Docker

Build and run Boltstore from source using the included Dockerfile. This is useful for containerized deployments without needing Bun or Node installed locally:

# Clone the repo
git clone https://github.com/boltstore/boltstore.git
cd boltstore/boltstore
# Build the image
docker build -t boltstore .
# Run the container with a data volume
docker run -p 8080:8080 -v ./data:/app/data boltstore

The Dockerfile is a multi-stage build that compiles the TypeScript source with Bun and runs the production server on port 8080. Your databases are stored in /app/data inside the container — mount it as a volume to persist data across restarts.

Start the Server

Start the Boltstore server with a single command. If no config file exists, one is auto-generated as boltstore.yaml:

boltstore serve --port 8080 --db ./data
# Server running on http://localhost:8080
# Dashboard available at http://localhost:8080/dashboard

Running from source:

bun run boltstore serve
# Or without a command argument — defaults to serve on port 8080
bun run boltstore

Create the First Admin Account

Open http://localhost:8080/dashboard in your browser. On first run, the dashboard shows a "Create Admin Account" screen. Submit an email and password (min 8 chars) — the first admin is created with no auth required.

Subsequent admin creation requires either an existing admin session or the bootstrap key (BOLTSTORE_ADMIN_KEY env var). Treat the bootstrap key as a one-shot provisioning secret — set it during initial deployment, then unset it.

Create Your First Database

Once logged into the dashboard, create a database from the UI, or via the API:

# Create a database (requires admin session token)
curl -X POST http://localhost:8080/api/databases \
-H 'Authorization: Bearer <admin-session-token>' \
-H 'Content-Type: application/json' \
-d '{"name": "my-app"}'

Database names must match /^[a-z0-9][a-z0-9_-]*$/.

Create an API Key

Create a per-database API key for your application backend:

curl -X POST http://localhost:8080/api/databases/my-app/keys \
-H 'Authorization: Bearer <admin-session-token>' \
-H 'Content-Type: application/json' \
-d '{"label": "My App Backend"}'
# Response — the raw key is returned only once
{
"data": {
"id": "apk_...",
"label": "My App Backend",
"key": "boltstore_..."
}
}

Make Your First Request

Use the API key to create a table and insert records:

# Create a table
curl -X POST http://localhost:8080/api/databases/my-app/tables \
-H 'Authorization: Bearer boltstore_...' \
-H 'Content-Type: application/json' \
-d '{"name": "users", "columns": [{"name": "id", "type": "integer", "primary_key": true, "auto_increment": true}, {"name": "name", "type": "text", "nullable": false}, {"name": "email", "type": "text"}]}'
# Insert a record
curl -X POST http://localhost:8080/api/databases/my-app/tables/users/records \
-H 'Authorization: Bearer boltstore_...' \
-H 'Content-Type: application/json' \
-d '{"name": "Alice", "email": "alice@example.com"}'
# Query records
curl http://localhost:8080/api/databases/my-app/tables/users/records \
-H 'Authorization: Bearer boltstore_...'

Using the SDK

For JavaScript/TypeScript applications, use the @boltstore/client SDK:

npm install @boltstore/client

import { BoltstoreClient } from '@boltstore/client';
const client = new BoltstoreClient({
url: 'http://localhost:8080',
database: 'my-app',
key: 'boltstore_...',
});
// Create a table
await client.tables.create('users', [
{ name: 'id', type: 'integer', primary_key: true, auto_increment: true },
{ name: 'name', type: 'text', nullable: false },
{ name: 'email', type: 'text' },
]);
// Typed record CRUD
const users = client.table<{ id: number; name: string; email: string }>('users');
const created = await users.create({ name: 'Alice', email: 'alice@example.com' });
const list = await users.query().where('name', 'like', 'A%').limit(10).get();
console.log(list);

Check out the SDK Guide for the full API reference.