Skip to content
FeltDBA Boundry product
Sign in
← Documentation

FeltDB Quick Start

> New to FeltDB? Start with [Getting started](getting-started.md): five minutes,

FeltDB Quick Start

New to FeltDB? Start with Getting started: five minutes, no scaffolder, every call executed in CI. This page covers the create-feltdb project generator.

create-feltdb generates a FeltDB application, installs its dependencies, and starts it with Studio:

npx create-feltdb my-app

In a terminal it asks:

  1. Where does your application's data live? Browser, Node.js authority, Self-hosted server, or Managed.
  2. Application framework: React (a complete starter) or Vanilla TypeScript (a minimal page over the same database).
  3. Vanilla TypeScript only: whether to include an agent example, and which starter capabilities (search, vector search, or both). The React starter always includes its assistants and skips these questions.
  4. Add the private AI app builder (WebLLM)? No by default.

--yes skips the questions and uses the defaults (Browser, React, no WebLLM). create-feltdb --help lists every flag.

Choose where data lives

Pick the target with one flag (or --runtime browser|node|self-hosted|managed):

| Flag | Data | What src/feltdb.ts opens | | --- | --- | --- | | --browser (default) | In the browser, in IndexedDB; nothing else to run | createFeltDB({ namespace }) | | --server | A FeltDB authority the application connects to; feltdb dev runs one locally | createFeltDB({ namespace, server: { url } }), with url from VITE_FELTDB_URL (default http://127.0.0.1:7700) | | --self-host | Your own feltdb-server; Docker Compose included | the same server: { url } call as --server | | --managed | FeltDB-hosted infrastructure; needs a feltdb.com account | createFeltDB(), configured by the .env.local that setup writes |

The targets generate the same application. They differ in that one createFeltDB line, in feltdb.config.json and .env.example, and, for --self-host, in the Docker files below. --managed signs in to or creates a feltdb.com account, then installs dependencies and publishes the first revision, so it cannot be combined with --no-install.

To generate without installing or starting anything:

npx create-feltdb my-app --browser --yes --no-install --no-start

✅ FeltDB application created successfully!

Project is ready. Start it with:
  cd my-app
  npm install
  npm run feltdb:dev
This starts the application, the development authority, and Studio together.
Do not also run npm run dev: that second copy is not managed by FeltDB.

What gets generated

The React starter is a small multi-tenant application: sign-up and sign-in, organizations, projects, invitations, an activity log, and two assistants that run bounded capabilities (no AI model needed).

my-app/
├── feltdb.flow            # collections, capabilities, workflows, agents, policies
├── feltdb.config.json
├── agents/                # project-assistant.ts, activity-assistant.ts
├── capabilities/          # project-search.ts, project-summary.ts, activity-summary.ts
├── workflows/             # project-created.ts, invitation.ts, agent-assisted-summary.ts
├── src/
│   ├── feltdb.ts          # opens the database; collections and operations
│   ├── App.tsx, index.tsx
│   ├── context/AuthContext.tsx
│   └── pages/             # SignUp, SignIn, Dashboard, Projects, Invitations, Activity, Agents
├── .feltdb/               # workspace.json, README.md
├── .env.example
├── index.html
├── package.json
├── tsconfig.json
└── README.md

feltdb.flow declares the collections User, Organization, Membership, Session, Project, Invitation, AuditEvent, Team and TeamMembership. src/feltdb.ts exports a typed handle for each one, for example:

export const projects = db.collection<Project>('Project');
export const auditEvents = db.collection<AuditEvent>('AuditEvent');

--self-host adds docker-compose.yml, Dockerfile, Dockerfile.feltdb, Dockerfile.studio, .dockerignore, and a .env holding a generated FELTDB_MASTER_KEY. The Compose file runs three services: feltdb (feltdb-server on port 7700, data in the feltdb_data volume), app, and studio.

Run it

cd my-app
npm run feltdb:dev

feltdb dev starts the application, the development authority, and Studio together and prints the address of each. Do not also run npm run dev. Self-hosted projects need Docker running.

The generated package.json scripts are dev, build, test, feltdb, and feltdb:dev, feltdb:server, feltdb:connect, feltdb:status, feltdb:studio, feltdb:publish, feltdb:ai, feltdb:sync, feltdb:validate, feltdb:diff and feltdb:deploy, each running the matching feltdb command.

Check what you opened

db.capabilities() reports what the open runtime supports. A FeltDB server answers GET /health with its liveness, for example (abbreviated):

{ "status": "healthy", "writes": "available", "version": "0.5.0", "release_id": "unknown", "storage": "clean", "runtime": "self-hosted" }

status is healthy or degraded. Readiness (storage and a scoped operation) is GET /health/ready.

Next steps

  • Developer guide: the one supported way to do each task, from the first record to a managed deployment.
  • Getting started: the same calls, step by step, without the scaffolder.
← Back to documentation