# Quickstart

> Download, run, create an admin, and install your first plugin.

_Updated: 2026-06-10_

This guide takes you from nothing to a running Railbase with a paid plugin
installed. It takes a few minutes and assumes a local machine; production
hardening is covered in [Deployment](deployment).

## 1. Download the binary

Grab the build for your platform from the [download page](../download). It's a
single executable — there is nothing else to install. On macOS / Linux, make it
runnable:

```bash
chmod +x ./railbase
```

## 2. Create the first admin

Create your superuser before starting the server. The email is a positional
argument; you'll be prompted for a password (twice). The command creates the
data store on first use, and the vault won't unlock without a password — locally,
set **`RAILBASE_DEV=true`** to use the built-in development key:

```bash
RAILBASE_DEV=true ./railbase admin create you@example.com
```

> [!IMPORTANT]
> The vault is a single file opened by **one process at a time**. Commands that
> open it (`admin`, `backup`, `jobs`, …) can't run while `serve` holds the lock —
> they exit with *"vault: file is locked by another process"*. Create the admin
> first (as here), or stop the server for a moment. On a running instance you can
> also create the first admin from the **`/_/bootstrap`** setup wizard instead.

## 3. Run it

```bash
RAILBASE_DEV=true ./railbase serve
```

With no other flags, Railbase:

- listens on **`http://localhost:8095`**
- keeps its data store at **`./pb_data/railbase.vault`** (a single encrypted file)
- serves the admin console at **`http://localhost:8095/_/`**

> [!IMPORTANT]
> In production you set a real `RAILBASE_VAULT_PASSWORD` instead of
> `RAILBASE_DEV=true`. A bare `serve` with neither exits with *"no vault
> password configured"*. See [Installation](installation#development-vs-production).

> [!TIP]
> Use a different port or data directory with flags: `RAILBASE_DEV=true
> ./railbase serve --addr :9000 --data-dir ./demo`. See the [CLI reference](cli).

Now open **`http://localhost:8095/_/`** and sign in. (Two-factor authentication
is self-service — enroll it under your account settings once you're in.)

```walkthrough
target: admin
fresh: true
title: Sign in to the admin console
steps:
  - say: Open the admin console. On a fresh instance you land on the sign-in screen.
    do: navigate
    value: /_/login
    expect: { text: Railbase admin }
  - say: Enter the admin email you just created.
    do: fill
    on: { label: Email }
    value: admin@example.com
  - say: And the password.
    do: fill
    on: { label: Password }
    value: AdminP@ss123
  - say: Sign in.
    do: click
    on: { role: button, name: Sign in }
    expect: { text: Collections }
  - say: And you're in. This is your home base — collections, logs, and settings, all one click away.
    do: navigate
    value: /_/
    expect: { text: Audit events }
  - say: Your collections, audit events, and live request rates, all at a glance.
    do: hover
    on: { text: Collections, first: true }
    minDwellSec: 2
```

## 4. Open the marketplace

The in-app marketplace is **built in and on by default** — there's nothing to
enable. Open **Marketplace** in your admin (`/_/`) and you're browsing the live
catalogue from railbase.app.

> [!NOTE]
> The marketplace always pulls from railbase.app — the catalogue, prices, and
> checkout are served there. To add a plugin to a build you compile yourself
> instead, see [Installing plugins](installing-plugins).

## 5. Buy or trial, and install a plugin

Open the Marketplace and pick a plugin. The flow is entirely in-product:

1. **Browse** — the catalogue, prices, and per-seat terms are synced live from railbase.app.
2. **Buy or try free** — checkout is embedded right in the page; enter your card in
   the secure payment form (served by railbase.app; **card data never touches your
   server**). Where a plugin offers a trial, **Try free** starts a time-boxed trial
   with no card.
3. **Install** — your instance pulls the plugin, **verifies it's authentic and
   unmodified**, and starts it as a managed process.

No download, no file to copy, no redeploy. The plugin's tables, routes, and jobs
are live the moment it registers.

> [!NOTE]
> Pricing is **per seat**, where a seat is a user holding a *billable* role.
> Viewers and self-service users are free. See [Licensing & seats](licensing-and-seats).

## Next steps

- Understand the moving parts in [Architecture](architecture).
- Learn the full install/update/uninstall flow in [Installing plugins](installing-plugins).
- Take it to production with [Deployment](deployment) and [Backups](backups-and-restore).