Start with no account
Run an app on BuildBase before anyone signs up, with buildbase init --claim or keyless development, then claim the organization and keep it.
You, or a coding agent working for you, can start an app on BuildBase before anyone has an account. The SDK creates a claimable organization, wires the app to it, and hands you a claim link and a short code. A person claims it later by signing in or up and typing the code; unclaimed, it is deleted after 72 hours.
There are two ways in:
buildbase init --claim: one command, run once, writes the keys into.env.local. For any appinitsupports, and the way a coding agent starts.- Keyless development (
@buildbase/sdk/keyless): no command at all. The dev server creates the organization on its first start and reuses it after. Next.js and Express only.
Before you start
@buildbase/sdk 1.3.0
or later, against a platform with claimable organizations. An
older platform answers 404 and nothing is created.
With buildbase init --claim
Run it in the root of your app:
npx @buildbase/sdk init --claim --yes --name "Acme" --email [email protected]--name and --email are optional. The email address is told when the organization is claimed and gets one reminder a day before it expires; it never receives the key.
What it does:
- Creates the organization with one request, gives it a sign-in client for your app's local URL (email and password, and magic links), and writes the files
initalways writes (Quickstart). - Writes
.env.local(readable only by you): the server URL, the org id, the client id and the redirect URL under the names below, the client secret, and the organization's key asBUILDBASE_API_TOKEN..env.examplegets the same names with the secrets empty. - Writes
.buildbase/claim.jsonwith the claim URL, the expiry and where the organization lives. Never the key or a code.initadds.buildbase/(and.env*.local, when missing) to.gitignorebefore the key exists. - Prints the expiry, the claim URL and the claim code, once. The key and the client secret are never printed.
A claim code works for 15 minutes. Get a fresh one at any time before the organization expires:
npx @buildbase/sdk claim-codeIt reads the key from .env.local (or .buildbase/keyless.json) and prints a new code with the claim URL; --json prints one JSON document.
init --claim never takes over an app that already has an organization: it refuses when .env.local names one. A run cut short is finished by running it again, which reuses the organization whose key .env.local holds instead of making another.
| Exit code | Meaning |
|---|---|
3 | The daily limit of claimable organizations for that email address was reached |
4 | The platform has no claimable organizations (an older one answered 404) |
5 | claim-code only: the key was refused, because the organization was claimed or expired |
Agent-ready from the start
Add --agent and init also makes the app agent-ready, so AI agents can sign in to its own MCP server:
npx @buildbase/sdk init --claim --agent --yesOn a Next.js App Router app it writes lib/agent.ts and the MCP, discovery and agent token routes, a generated SYSTEM_SECRET, and the agent client's BUILDBASE_AGENT_CLIENT_ID and BUILDBASE_AGENT_CLIENT_SECRET. Agents can sign in only once a person turns it on: the Let AI agents sign in to your app tick on the claim page, or Agent readiness in the console. See Make your app agent ready.
Keyless development
Wrap your Next.js config, and start the dev server with no BuildBase keys at all:
// next.config.mjs
import { withBuildBaseKeyless } from '@buildbase/sdk/keyless';
export default withBuildBaseKeyless({
// your Next.js config
});In Express, call applyKeyless before the BuildBase client is created:
import { applyKeyless } from '@buildbase/sdk/keyless';
await applyKeyless({ framework: 'express' });
const { buildbase } = await import('./buildbase');The first start creates a claimable organization, through the same code as init --claim, and keeps it in .buildbase/keyless.json (readable only by you, and git-ignored). Every start after reuses it, and an expired one is replaced.
- When it runs: only with
NODE_ENV=development(undernext devfor Next.js;BUILDBASE_KEYLESS=1stands in for an unsetNODE_ENV, never forproduction), only when no org id is set (NEXT_PUBLIC_BUILDBASE_ORG_IDorBUILDBASE_ORG_ID), never in CI, and not withBUILDBASE_KEYLESS=0.next build,next startand a production build behave exactly as before. - Where the keys go: the server's
process.envgetsBUILDBASE_CLIENT_SECRETandBUILDBASE_API_TOKEN. The browser gets only public values:NEXT_PUBLIC_BUILDBASE_SERVER_URL,NEXT_PUBLIC_BUILDBASE_ORG_ID,NEXT_PUBLIC_BUILDBASE_CLIENT_ID,NEXT_PUBLIC_BUILDBASE_REDIRECT_URLandNEXT_PUBLIC_BUILDBASE_KEYLESS(the expiry and the claim URL). The filesbuildbase initwrites work unchanged. - A browser-only app (Vite with no server) has nowhere to keep the key: use
init --claiminstead.
@buildbase/sdk/keyless is for Node only. Imported in a browser bundle, it throws.
The claim prompt
<KeylessPrompt> from @buildbase/sdk/react is a small card that can be dismissed. It says the app runs on a temporary organization, when it is deleted and how to claim it (the claim page, and npx @buildbase/sdk claim-code for the code). Once the organization is claimed, it says the temporary key has ended and how to get permanent keys.
import { KeylessPrompt } from '@buildbase/sdk/react';
<KeylessPrompt config={process.env.NEXT_PUBLIC_BUILDBASE_KEYLESS} />;The Next.js provider buildbase init writes already renders it. With no config, outside keyless development, it renders nothing. An Express app hands it the value applyKeyless returns, which holds public values only.
Claim it
Open the claim link, sign in or sign up (your usual sign-in method and second step apply) and type the code. You become the organization's owner. What the claim page shows, and what the organization may do until it is claimed, is in the claimable organization.
After the claim, the org id and the sign-in client stay the same, so sign-in keeps working, but the temporary key stops working. Get permanent keys with npx @buildbase/sdk init --dev (after npx @buildbase/sdk login), or copy them from the console into .env.local. Once an org id is set, keyless development is off.
Add an email sender before your users sign up: until the organization has one, sign-up answers 503. init --claim says so when it finishes.
Next steps
- Quickstart: what
initwrites, and every file by hand. - Installation: the environment variable names for Next.js, Vite and Express.
- Development and staging environments:
buildbase init --dev.