# Temporary databases

## Claimable temporary projects

An agent can get a real backend (Postgres, auth, storage, realtime,
functions) without an account:

```sh
npx scribase init --temp --yes --json
```

It detects the framework (Next.js, Expo, Vite, plain Node), creates a
temporary project, writes the env file with the framework's variable names
(`NEXT_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_URL`, `VITE_SUPABASE_URL`,
or `SUPABASE_URL`, plus the anon key), installs `@supabase/supabase-js`,
writes a small client module and prints one JSON object with the project URL,
the variables it wrote and a **claim URL**.

- The project lives **72 hours**. To keep it, open the claim URL, sign up (or
  sign in) and add a card (the one-time card check). The project moves to your
  account unchanged: same URL, same keys, nothing to reconfigure.
- Unclaimed projects are deleted, with their database, when they expire.
- The agent gets a token scoped to that one project (`SCRIBASE_ACCESS_TOKEN` in
  the env file), so it can keep running SQL and migrations. It expires with
  the project.
- Limits while unclaimed: small database, storage and egress caps, and the
  project's auth never sends email (sign-ups are confirmed automatically).
  Creating one may ask for a few seconds of proof of work, which
  `npx scribase init` does for you; each address can create a handful a day.

The same flow over HTTP:

| Call | What it does |
|---|---|
| `POST /v1/temporary-projects/challenge` | `{challenge, bits}` for the proof of work |
| `POST /v1/temporary-projects` | `{name, challenge, nonce}` → `201` with `agent_token`, `claim_url`, `expires_at` |
| `GET /v1/temporary-projects/{id}` | with the agent token: `status` (`provisioning`, `ready`) and, when ready, `keys` |
| `POST /v1/temporary-projects/{id}/claim` | a signed-in person with `{claim_token}`: `claimed`, or `402 card_required` until the card is added |

The deployment operator turns this on with `SCRIBASE_TEMPORARY_PROJECTS=1`
(and sets `SCRIBASE_TEMPORARY_PROJECTS_SECRET`); a deployment without it
answers `503 temporary_projects_disabled`.

## With your account

With a token (`scribase login`, or `SCRIBASE_ACCESS_TOKEN`),
`npx scribase init --yes --json` creates (or, run again, reuses) a project in
your organization and writes the same files. Give an agent a scoped token for
this: see [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md).

If the folder is linked to Vercel (`vercel link`), `init` also sets the URL and
keys on the Vercel project for development, preview and production, using
`VERCEL_TOKEN` or the signed-in `vercel` CLI. See
[vercel env push](https://docs.scribase.com/docs/cli/vercel.md).

## Other short-lived databases

- **MCP scratch branch.** Every remote MCP session gets its own scratch
  database for `schema.propose`, `policy.simulate`, `policy.test` and
  `sql.explain`. It is dropped when the session ends.
- **Previews with a TTL.** `scribase env create <org> <project> <env> preview
  schema_only <region> <key> <ttl-hours>` (MCP `environment.create` with
  `kind: "preview"` and `ttl_hours`) gives the agent a real environment, with
  URL, keys, auth and storage, that deletes itself when the TTL runs out.
  `schema_only` starts empty; `sanitized` copies production's data, then
  anonymizes it.
- **Local databases.** `scribase dev` runs Postgres, auth and storage on your
  machine with no account at all.