Loomup Docs
Guide /docs/quickstart

Loomup Quickstart

Loomup is a single-binary Backend OS that compiles domain resources into portable SQLite, secure APIs, and live clients.

Install

bash
cargo install loomup --locked

Prebuilt binaries are also produced by repository releases. Building from source remains available with cargo build --release. Product documentation is hosted at tryloomup.com/docs.

Create a project

bash
loomup new my-app --template mobile
cd my-app
loomup dev

The command uses admin@example.com, generates a unique local admin password, and prints both once. Supply --admin-email and --admin-password together when you want explicit credentials.

This creates:

  • loomup.app.toml — resources, fields, ownership, and capabilities
  • loomup.toml — generated/advanced runtime operations
  • data/app.sqlite — SQLite database (WAL mode)
  • loomup.types.ts — generated select/create/update types
  • resources from the selected template
  • relationship-safe sample domain rows for non-blank local starters
  • a unique admin and project-local development secret

Available templates are blank, saas, collaboration, and mobile:

bash
loomup templates

Edit loomup.app.toml, then preview and apply changes:

bash
loomup plan
loomup apply
loomup seed seeds/development.json # optional, idempotent fixtures
loomup doctor

Safe additive changes apply automatically when loomup dev starts. Required fields without defaults, type changes, and other ambiguous changes stop with a readable blocker instead of guessing.

Existing init/serve projects remain supported:

bash
loomup upgrade --dry-run

Multi-tenant control plane (optional)

To manage many isolated projects from one catalog (SaaS foundation), use platform commands — see control-plane.md.

bash
loomup platform register --email you@example.com --password 'secret12'
loomup platform create-project --token "$TOKEN" --name my-app --admin-password 'adminpass'
loomup serve --config .loomup/projects/<id>/loomup.toml

Single-project self-host (new + dev above) does not require the control plane.

Free-tier size quotas

New projects default to low caps so overages fail early in testing:

LimitDefaultConfig key
SQLite DB1 GiBdatabase.max_size_bytes
Object storage total100 MiBstorage.max_total_bytes

Set either to 0 for unlimited. See SQLite schema — size quotas.

Health

bash
curl http://127.0.0.1:3000/health

Developer portal

After dev, open the public packages & documentation catalog (no login):

  • http://127.0.0.1:3000/
  • http://127.0.0.1:3000/docs
  • http://127.0.0.1:3000/llms.txt (detailed plain-text implementation reference)

HTML guides are also at /docs/<slug> (e.g. /docs/quickstart, /docs/sdk, /docs/sdk-astro).

Admin UI

Open http://127.0.0.1:3000/admin and log in as the admin user.

Auth + CRUD (curl)

bash
# register
curl -s -X POST http://127.0.0.1:3000/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"user@example.com","password":"password"}'

# login and retain both identity + token
SESSION=$(curl -s -X POST http://127.0.0.1:3000/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"user@example.com","password":"password"}')
TOKEN=$(printf '%s' "$SESSION" | jq -r .data.access_token)
USER_ID=$(printf '%s' "$SESSION" | jq -r .data.user.id)

# create an owner-scoped mobile item
curl -s -X POST http://127.0.0.1:3000/api/items \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d "{\"user_id\":\"$USER_ID\",\"title\":\"Ship MVP\",\"completed\":0,\"sort_order\":0}"

# list
curl -s "http://127.0.0.1:3000/api/items?limit=10&sort=-id" \
  -H "authorization: Bearer $TOKEN"

TypeScript SDK

bash
npm install @loomup/client

Next.js apps should install @loomup/next as well and follow Next.js SDK.

ts
import { createProject } from "@loomup/client";

const project = createProject({ url: "http://localhost:3000" });

const session = await project.auth.signUp({
  email: "user@example.com",
  password: "password",
});

await project.items.create({
  user_id: session.user.id,
  title: "Build realtime SQLite backend",
  completed: false,
  sort_order: 0,
});

const live = await project.items.live({ strategy: "merge" });
live.onChange(({ data }) => {
  console.log("Live items:", data);
});

React SDK

bash
npm install @loomup/client @loomup/react
tsx
import { createClient } from "@loomup/client";
import { LoomupProvider, useAuth, useLiveQuery } from "@loomup/react";

const client = createClient({ url: "http://localhost:3000" });

function App() {
  return (
    <LoomupProvider client={client}>
      <Todos />
    </LoomupProvider>
  );
}

function Todos() {
  const { user, signUp } = useAuth();
  const { data } = useLiveQuery("todos", { strategy: "merge" });
  // ...
}

See React SDK and examples/todo-react.

Other CLI commands

bash
loomup migrate              # auth + CDC schemas + triggers
loomup plan                 # preview manifest changes
loomup apply                # apply safe manifest changes
loomup doctor               # diagnose the whole project
loomup upgrade --dry-run    # preview legacy manifest adoption
loomup cdc install          # regenerate CDC triggers
loomup cdc status           # unprocessed / processed counts
loomup gen typescript -o types.ts
loomup admin create-user --email you@example.com --password secret
loomup backup -o ./backup.sqlite

See also: