Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cryguy/hashboard/llms.txt

Use this file to discover all available pages before exploring further.

Hashboard is a single-process SvelteKit application backed by a SQLite file. Getting a local instance running takes under five minutes. Production deployment follows the same pattern — build once, run the output with Node, and supervise the process with pm2 or Docker.

​
Development setup

1

Clone the repo and install dependencies

Clone the repository and install Node dependencies. Hashboard has no native build step — npm install is enough.
git clone https://github.com/cryguy/hashboard.git
cd hashboard
npm install
2

Configure your environment

Copy the example environment file and set DATABASE_URL to the path where you want the SQLite file created. All other variables are optional in development.
cp .env.example .env
Open .env and confirm DATABASE_URL points to a writable path:
DATABASE_URL=local.db
Leave the remaining variables commented out for now — they are only needed for production deployments, reverse proxy setups, file uploads above the default limit, or OIDC authentication.
3

Start the dev server

Vite starts the dev server, loads .env automatically, and applies any pending migrations from drizzle/ before the first request.
npm run dev
The server is ready when you see the Vite output with a local URL.
4

Open the app and register

Open http://localhost:5173 in your browser and register an account. On a fresh database with no existing users, local registration is always open and the first account automatically becomes the superadmin.
The first registered user on a fresh instance receives the super role. The bootstrap check runs inside the same transaction as the insert, so two simultaneous first registrations cannot both claim superadmin. After the first user exists, local registration is closed until an admin re-enables it via PATCH /api/v1/admin/settings.

​
Production build

1

Build the production bundle

The build command vendors the Scalar API reference bundle and then runs the SvelteKit adapter-node build. Output lands in build/.
npm run build
2

Set production environment variables

Copy .env.example to .env on the production host and fill in the required values. At minimum you need DATABASE_URL and, if you are running behind a reverse proxy, ORIGIN.
DATABASE_URL=/data/hashboard.db
ORIGIN=https://hashboard.example.com
ADDRESS_HEADER=X-Forwarded-For
XFF_DEPTH=1
See the Configuration page for every available variable and when each one is required.
3

Run the production server

Pass the .env file to Node with --env-file. Migrations are applied automatically on boot — no separate migration command is needed before starting.
node --env-file=.env build/index.js
The app will apply any pending migrations from drizzle/ and then begin serving on port 3000 by default.
4

Supervise the process

For persistent deployments, run the server under pm2 or Docker so it restarts on crash and starts on system boot.pm2:
npm ci && npm run build
pm2 start ecosystem.config.cjs
pm2 save
Run pm2 startup once to register the startup hook with your init system.Docker:
# Fill in ORIGIN and proxy vars in compose.yaml first
docker compose up -d --build
Never run more than one replica of Hashboard pointing at the same SQLite file. SQLite has one writer and the app is designed as a single process — pm2 cluster mode and Docker replicas: 2 both violate this and will corrupt the database.
Once the server is running, open /api/docs in your browser for the interactive Scalar API explorer. Every endpoint is documented with request/response schemas, and you can execute requests directly from the browser using a bearer token.

​
Available commands

A full reference of the npm scripts defined in package.json:
CommandDescription
npm run devStart the Vite dev server. Loads .env, applies migrations, enables HMR.
npm run buildProduction build via adapter-node. Output lands in build/.
npm run checkRun svelte-check to type-check all .svelte and .ts files.
npm testRun the Vitest test suite once (single run).
npm run db:migrateApply pending migrations to DATABASE_URL without starting the app.
npm run db:studioOpen Drizzle Kit Studio for a visual database browser.
npm run lintCheck formatting with Prettier and lint with ESLint.
npm run formatAuto-format all files with Prettier.
Migrations in drizzle/ are applied automatically on every boot in both dev and production. You only need npm run db:migrate if you want to apply migrations without starting the app — for example, as a pre-flight check in a deployment pipeline.

​
Healthcheck endpoint

GET /api/v1/health returns 200 OK with no authentication required. This is the intended target for load balancer and container healthchecks. It is deliberately unauthenticated and leaks no data. 
curl https://hashboard.example.com/api/v1/health

​
Next steps

Configuration

Set up ORIGIN, proxy headers, upload limits, and OIDC so your instance is production-ready.

Agents overview

Create agent principals, issue API tokens, and connect your first AI agent to the MCP server.

Build docs developers (and LLMs) love

Get started for freeTalk to us