Skip to main content
Get your TrailBase backend server running and create your first API in under 5 minutes.

​
Install TrailBase

curl -sSL https://trailbase.io/install.sh | bash
The install script downloads the latest release binary and adds it to your PATH. For more installation options, see the Installation Guide.

​
Start the Server

Run TrailBase with a single command: 
trail run
On first start, TrailBase will:
  • Create a ./traildepot directory for data and configuration
  • Initialize a SQLite database
  • Create an admin user with credentials printed to the terminal
  • Start the server on http://localhost:4000
Save the admin credentials displayed in the terminal - you’ll need them to access the dashboard.

​
Access the Admin Dashboard

Open http://localhost:4000/_/admin/ in your browser and log in with the credentials from the previous step. The admin dashboard lets you:
  • Create and manage database tables
  • Configure Record APIs with access rules
  • Manage users and authentication
  • View logs and monitor your server

​
Create Your First Table

Let’s create a simple “posts” table for a blog:
1

Navigate to Tables

In the admin dashboard, go to Schema → Tables and click Create Table.
2

Define the Schema

Create a table with the following columns:
CREATE TABLE posts (
  id BLOB PRIMARY KEY DEFAULT (uuid_v7()) NOT NULL,
  created INTEGER DEFAULT (unixepoch()) NOT NULL,
  updated INTEGER DEFAULT (unixepoch()) NOT NULL,
  
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  author_id BLOB REFERENCES _user(id),
  published INTEGER DEFAULT 0 NOT NULL
) STRICT;
Click Execute to create the table.
3

Configure the API

Go to APIs → Record APIs and click Create API:
  • Table: posts
  • Name: posts
  • Read Access: Public (for now)
  • Create Access: Authenticated
  • Update/Delete Access: Owner only
Click Save.

​
Test Your API

Your posts API is now live! Test it with curl:

​
List all posts

curl http://localhost:4000/api/records/v1/posts

​
Create a post (requires authentication)

First, create a user and get an auth token: 
# Register a new user
curl -X POST http://localhost:4000/api/auth/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secretpassword"}'

# Login to get a token
curl -X POST http://localhost:4000/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secretpassword"}'
Then create a post using the auth token: 
curl -X POST http://localhost:4000/api/records/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "My First Post",
    "content": "Hello from TrailBase!",
    "published": 1
  }'

​
Query posts

# Get a specific post
curl http://localhost:4000/api/records/v1/posts/POST_ID_HERE

# Filter published posts
curl "http://localhost:4000/api/records/v1/posts?published[eq]=1"

# Search by title
curl "http://localhost:4000/api/records/v1/posts?title[like]=%First%"

​
Use a Client SDK

Instead of raw HTTP requests, use one of TrailBase’s client libraries: 
npm install trailbase

import { TrailBase } from 'trailbase';

const client = new TrailBase('http://localhost:4000');

// Login
await client.login('[email protected]', 'secretpassword');

// Create a post
const post = await client.createRecord('posts', {
  title: 'My First Post',
  content: 'Hello from TrailBase!',
  published: 1
});

// List posts
const posts = await client.listRecords('posts', {
  filter: { published: { eq: 1 } }
});

​
Enable Realtime Subscriptions

Subscribe to live updates on your posts table: 
const unsubscribe = await client.subscribe('posts', {
  onCreate: (record) => console.log('New post:', record),
  onUpdate: (record) => console.log('Updated:', record),
  onDelete: (id) => console.log('Deleted:', id)
});
Any changes to the posts table will trigger your callbacks in realtime!

​
Next Steps

Build Your First App

Complete tutorial building a full application

Database Setup

Learn about schema design and migrations

Authentication

Add user auth with OAuth providers

API Reference

Explore the complete REST API

Build docs developers (and LLMs) love

Get started for freeTalk to us