Quickstart

Three ways in, depending on what you have. Pick one.

You want	Start at
A backend on your machine, no database, no account	Local first
To run the whole thing yourself with Docker	Self-hosted
To build against a project that already exists	Link an existing project

Local first

mkdir my-app && cd my-app && npm init -y
npm i -D @groveback/cli @groveback/server
npx grove dev --seed --persist

That is the whole setup — no grove init, no URL, no key. It starts an empty project in memory and prints a dashboard link with the key already in it:

http://localhost:8099/dashboard?key=gb_sk_proj_dev.…#/

The CLI is plain Node with zero runtime dependencies. @groveback/server is the emulator grove dev spawns — a standalone binary per platform, so it needs neither Bun nor a database.

Use --seed --persist together, every time

They are the two halves of one thing. --persist writes the server back to disk when you stop it; --seed loads that back on the next start. With only --persist, your work is saved but never comes back — collections return (they live in the bundle) while the documents appear to have vanished.

Next: create a collection, then read the local loop.

Self-hosted

git clone https://github.com/ideascoldigital/groveback
cd groveback
cp .env.example .env          # set JWT_SECRET (openssl rand -base64 32)
docker compose up -d
curl localhost:8080/api/v1/health

This brings up the app plus a single-node MongoDB replica set — a replica set specifically, because realtime needs Change Streams. Full details in self-hosting.

To hack on the source instead, with Bun:

bun install
bun run dev          # in-memory backend on :8080 — data is lost on restart

Link an existing project

You need the project id (proj_…) and an admin API key (gb_sk_…), which you create in the dashboard under API Keys.

npm i -D @groveback/cli
npx grove init --url https://api.example.com --project proj_abc123
export GROVE_ADMIN_KEY=gb_sk_proj_abc123.…
npx grove pull      # mirror the project's shape into groveback/

grove init writes grove.json. Commit it — it holds no secrets. The admin key is read from the environment at the moment you run a command and is never written to disk.

Your first requests

With the server running, register a user and create a document:

curl -X POST localhost:8080/api/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"a@example.com","password":"correct-horse"}'

curl -X POST localhost:8080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"a@example.com","password":"correct-horse"}'

That returns an accessToken. Use it:

curl -X POST localhost:8080/api/v1/posts \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"title":"hola"}'

Note

If that last call returns 403, the collection has no policy yet — and the data plane is fail-closed, so nothing without a policy is reachable by a non-admin caller. That is working as intended. Give posts a policy and try again.

With the SDK

npm i @groveback/sdk

import { createClient } from '@groveback/sdk';

const client = createClient({ baseUrl: 'http://localhost:8080' });
await client.auth.register('a@example.com', 'correct-horse');
await client.auth.login('a@example.com', 'correct-horse');

const posts = client.collection('posts');
const doc = await posts.create({ title: 'Hola' });
const stop = posts.subscribe('insert', (event) => console.log('new post', event));

Better still, generate a typed client from your live schema:

npx grove gen

import { createGrove } from './src/grove/grove';

const grove = createGrove();
await grove.auth.login('a@example.com', 'correct-horse');

const posts = await grove.collections.posts.find();      // Post[]
await grove.collections.posts.create({ title: 'Hello' }); // PostInput

See the SDK reference and the CLI reference.

Build it by conversation

Groveback ships an MCP server, so Claude Code, Claude Desktop or Cursor can create collections, schemas, policies, roles and functions for you:

claude mcp add groveback \
  -e GROVEBACK_URL=http://localhost:8080 \
  -e GROVEBACK_API_KEY=gb_sk_proj_abc123.… \
  -- npx -y @groveback/mcp

Where next

• Core concepts — the vocabulary, in one page.
• Collections and schemas — define your data.
• Authorization policies — decide who reads what.
• The local loop — pull, dev, push.