Get started with Tetra

Auth, database security and a toolchain that checks your work — before you write your first route. Free for a single developer.

Run one command

npx create-tetra my-app

Node 24 or newer. Nothing to install first, and nothing to sign up for beforehand.

Approve it in your browser

Your terminal shows a short confirmation code and opens a page that shows the same code and the project you are creating. Enter your e-mail address there and open the link we send you. That address is the whole account — there is no password to choose.

Compare the code on the page with the one in your terminal before you approve. They should match; that is what stops someone else’s request from being approved by you.

The code is valid for ten minutes. If you need longer than that — finding the e-mail, switching devices — the terminal does not give up: it automatically renews the code, requesting a fresh one and a fresh link, up to four times, and keeps waiting. Nothing is lost and nothing needs to be re-run; just open whichever link is currently showing in your terminal. Do not restart the command while it is waiting — that throws away the approval in progress for no reason.

If something goes wrong

No e-mail arrived: check spam first. Reloading the approval page will not bring the form back — use the “Didn’t get it? Try again.” link it shows instead.
The page says the code expired: your terminal already asked for a new one automatically — look there for the current link rather than reusing the old one.
A temporary server error: the CLI retries this on its own; if it keeps failing for more than a few minutes, let us know.

Start building

cd my-app
npm run dev:local

The command already installed everything. While it ran it wrote four files. Your user .npmrc gained read access to the package registry, so every project you create keeps working. The project got an .npmrc pointing the @soulbatical scope at that registry — no secret in it, safe to commit. The project’s .env, git-ignored from the start, holds your signed licence key and a copy of the registry token. And a committed ci/npmrc carries the same registry mapping with a ${NPM_TOKEN} placeholder instead of the real token — Railway and Netlify builds point at that file and read the token from a build variable instead.

Both the user npmrc entry and the token inside .env are credentials: keep them server-side. Anything exposed to the browser is readable by every visitor.

npm run dev:local is the command that works right after install — it needs the Supabase CLI (supabase start, then supabase db reset) and nothing else. Once you have connected Doppler for shared secrets, npm run dev is the command to use instead — the generated project’s README explains both.

Deploying to Railway or Netlify: commit ci/npmrc (there is nothing secret in it) and set NPM_TOKEN as a build variable on that platform, using the token already sitting in your .env. Without it, the build fails on a 401 the first time it tries to install an @soulbatical package.

Working with an AI assistant

Claude Code, Codex, OpenCode, Cursor — any coding assistant can run the install for you. The approval step still needs a human: that is the point of it.

What the assistant does

It runs npx create-tetra in your project directory, prints the confirmation code and link, and then waits. It does not — and should not — open the link or approve anything itself; you do that, in your own browser, the same way as above.

What it should not do

Restart the command. The wait is intentional and self-healing — a code that expires is replaced automatically — so an assistant that kills and reruns the command on an expired code just burns a fresh approval for no reason. A well-behaved assistant waits for you, same as the terminal says.

Starting from existing instructions

If your assistant already laid down AGENTS.md, CLAUDE.md or a .claude/ directory before running the install, that is fine — create-tetra allows a target directory that already holds exactly those files.

For a ready-made set of agent instructions and skills, see PROJECT_SETUP.md and its companion scaffolding script, which layers agent scaffolding on top of a project create-tetra already created.

Machine-readable summary

/llms.txt has the same install steps in plain text, written for an agent to read directly rather than parse out of this page.

What you get on day one

This is the foundation, not a tutorial. It is here so you can see what you no longer have to build yourself.

An application with security defaults

import { createApp } from '@soulbatical/tetra-core';

const app = createApp({
  name: 'my-app',
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseAnonKey: process.env.SUPABASE_ANON_KEY!,
  supabaseServiceKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
});

CORS, CSP, rate limiting, security headers and the database client hierarchy — configured, not left to you.

Accounts and sessions

import { addPublicAuthRoutes } from '@soulbatical/tetra-core/auth';

// POST /api/public/auth/login, /api/public/auth/signup, /api/public/auth/logout,
//      /api/public/auth/refresh, /api/public/auth/magic-link, /api/public/auth/oauth/:provider
addPublicAuthRoutes(app);

Your own features

import { addQueryRoutes, addMutationRoutes }
  from '@soulbatical/tetra-core';

const config = {
  tableName: 'orders',
  organizationIdField: 'organization_id',
  filters: [
    { key: 'status', type: 'enum', options: ['pending', 'paid', 'shipped'] },
    { key: 'search', type: 'search', columns: ['customer_name', 'email'] },
  ],
};

addQueryRoutes(app, '/api/orders', config);
addMutationRoutes(app, '/api/orders', config);

Filtering, pagination and search from one description, with row level security applied per organization.

Checks you can run any time

npx tetra-check-rls         # row level security policies
npx tetra-migration-lint    # migration safety
npx tetra-toolchain-check   # project configuration
npx tetra-test-governance   # test coverage contracts

Deployment

Tetra runs on any Node.js host. Node 24 or newer is required.

FROM node:24-slim
COPY . .
RUN npm ci
CMD ["node", "dist/index.js"]

If you would rather wire it up yourself

The command is not doing anything you could not do by hand — it asks for a licence, mints a read-only registry token bound to it, and writes both where npm looks. If you would rather see those pieces first, or you are adding Tetra to a project that already exists, ask and we will send you the same credentials to place yourself.

Ask for the pieces

One thing that is worth knowing either way: the packages are not on npmjs.com. create-tetra writes the registry configuration for you, which is why npm install just works inside the project it creates. In an environment that never went through that step, the @soulbatical scope has no registry to answer from and a bare npm install fails on the first request — that is missing configuration, not a broken package.

Free for one developer

Building on your own costs nothing, for as long as you like. Pricing starts when a second person joins your organization, and moves in steps you can read off the table rather than a per-seat sum.

View pricing Documentation