Architecture

The core, out-of-process plugins, the vault data store, and the marketplace.

Updated 2026-06-10

Railbase is one binary that supervises a small set of moving parts. Understanding them makes the install, update, and licensing flows obvious.

The big picture

                    your server
 ┌───────────────────────────────────────────────┐
 │  Railbase core (the binary)                     │
 │   ├── HTTP server        :8095                  │
 │   │     /          public assets (optional)     │
 │   │     /_/        admin console (SPA)           │
 │   │     /_pm       marketplace / plugin manager  │
 │   │     /papi/...  reverse-proxy to plugins      │
 │   ├── vault         single-file data store       │
 │   └── plugin manager                             │
 │         ├── plugin A   (subprocess)              │
 │         └── plugin B   (subprocess)              │
 └───────────────────────────────────────────────┘
              │ syncs with (catalog, licenses,
              ▼  artifacts, payments)
        railbase.app  — vendor licensing & distribution

The core

The core is the always-on process. It owns the HTTP server, the data store, auth, the job runner, and the admin console. It boots in well under a second and runs happily on a small VPS.

Key routes:

/_/ — the admin console (a single-page app embedded in the binary).
/_pm — the marketplace / plugin-manager console (on by default; RAILBASE_PLUGIN_MANAGER=0 disables).
/papi/<slug>/… — a reverse proxy the core uses to route requests to a running plugin.

Plugins run out of process

A plugin is a separate signed binary that the core runs as a subprocess — it is not compiled into Railbase. When you install a plugin, the plugin manager:

launches it with a private port and short-lived tokens,
waits for it to register (a loopback handshake announcing its slug, the collections it owns, the capabilities it provides/consumes, its minimum core version, and the roles it declares),
supervises it — health-checks it, restarts it on crash, and proxies /papi/<slug>/… traffic to it.

Because plugins are separate processes, a misbehaving plugin can't take the core down, and the core can stop, update, or remove one without a redeploy. The full lifecycle is in How plugins work.

The vault data store

Persistence is a single encrypted file (railbase.vault) managed by an in-process, MVCC document engine. No PostgreSQL, no connection strings, no sidecar. Each plugin gets its own namespaced collections; multi-tenant deployments use a file per tenant. See Data & multi-tenancy.

railbase.app: the vendor plane

Your instance is a client of railbase.app, the vendor's server. It reaches out to:

discover plugins and prices (catalog) and the vendor's signing key (pubkey),
complete a purchase (payment runs on railbase.app; your server is never a card processor),
download the signed artifact for a plugin you're licensed for,
keep licenses fresh via a periodic license check (renewals, revocations).

The trust anchor is a pinned public key: the core only runs an artifact whose signature verifies against the key it has pinned for the vendor. This is why acquisition is marketplace-only — see How plugins work and Licensing & seats.