Developer Quickstart

Developer Quickstart

Get a local VaultLister 3.0 instance running in under five minutes. No accounts or cloud services required for the core experience.

Prerequisites

  • Required
    Bun 1.3+ Runtime and package manager. Install via curl -fsSL https://bun.sh/install | bash or see bun.sh.
  • Required
    Git 2.x For cloning and version control.
  • Optional
    Docker 24+ Only needed for production deployment or running the full containerized stack.
  • Optional
    Playwright browsers Required only if you want to test marketplace automation bots. Install after bun install by running bunx playwright install.

Setup

  1. Clone the repository

    git clone https://github.com/Vaultifacts/VaultLister-3.0.git
cd VaultLister-3.0

  2. Create your .env file

    Copy the example file and set a strong value for JWT_SECRET. All other values are optional for local development.

    cp .env.example .env
    Open .env in your editor and set JWT_SECRET to any random 32+ character string before starting the server.

  3. Install dependencies

    bun install

  4. Initialize the database

    bun run db:init

    Creates the SQLite database at data/vaultlister.db in WAL mode with all tables and seed data including the demo account.

Running locally

  1. Start the development server

    bun run dev

    The server starts on port 3000 by default. File changes to backend routes and frontend pages hot-reload automatically.

  2. Open the app

    Navigate to:

    http://localhost:3000

Demo login

A demo account is pre-seeded by db:init. Use it to explore the full UI without configuring marketplace credentials.

Demo account

Email demo@vaultlister.com
Password DemoPassword123!
MFA disabled (dev only)

Key commands

Command Description
bun run dev Start dev server with hot reload on port 3000
bun run dev:bg Start dev server in the background
bun run test:unit Run unit tests (Bun:test)
bun run test:e2e Run end-to-end tests (Playwright)
bun run test:all Run all tests in sequence
bun run build Production build — bundle and minify assets
bun run lint Syntax check all source files
bun run db:reset Wipe and re-seed the local database
bun scripts/help.js List all available scripts with descriptions

Project structure

vaultlister-3/ ├── src/ │ ├── backend/ │ │ ├── routes/ # API route handlers — one file per domain │ │ └── middleware/ # Auth, CSRF, rate limiting, security headers │ ├── frontend/ │ │ ├── app.js # SPA entry point, store, router │ │ ├── pages/ # Lazy-loaded route pages │ │ ├── handlers/ # Event handlers grouped by domain │ │ └── components/ # Reusable UI components │ └── shared/ │ ├── ai/ # Anthropic SDK wrappers — never call SDK directly │ └── automations/ # Playwright bots for marketplace automations ├── public/ # Static files served at root ├── scripts/ # Dev utilities — session-start, session-end, etc. ├── data/ # SQLite database and audit logs (git-ignored) ├── chrome-extension/ # Chromium extension source ├── .env.example # Copy to .env and fill in values └── CLAUDE.md # Project instructions for AI agents

Next steps