# Getting Started with Scribase

Scribase is an open application cloud built on PostgreSQL. It provides a
durable control plane, branching data environments, and a full set of
application-layer services — auth, storage, realtime subscriptions, and edge
functions — all deployable as a single stack that you own.

## What Scribase gives you

| Surface | Description |
|---|---|
| Control-plane API | Durable `/v1` REST API for organizations, projects, environments, and operations |
| Local dev | `scribase dev` — Postgres + all services, no Docker, no configuration |
| Branching | Schema-level CoW branches for each pull request or preview environment |
| Migrations | Lint-first migration runner with up/down tracking |
| Auth | JWT-based authentication with OAuth providers via GoTrue |
| Storage | Object storage with buckets and bucket policies |
| Realtime | WebSocket subscriptions over Postgres replication |
| Functions | V8-based edge function runtime |
| Aegis | Compile-time RLS policy verifier |
| SDK | Typed TypeScript client — `scribase` on npm |

There are two ways in:

- **Hosted Scribase** — sign up, add a card ($1, credited back), and your
  backend is live with its URL and key in about a minute. Nothing to install.
  Follow the [hosted quickstart](https://docs.scribase.com/docs/hosted.md).
- **Local development** — run the whole stack on your machine with the
  `scribase` CLI, below.

## Quick start (local development)

### 1. Install the CLI and its prerequisites

The CLI is a single Rust binary named `scribase`. Build it from a checkout of the
Scribase source with Rust 1.85 or newer:

```sh
cargo install --locked --path crates/scribase-cli
scribase version
```

The source repository is private while Scribase is in early access; email
[hello@scribase.com](mailto:hello@scribase.com) for access. If you only need the
hosted platform, skip the CLI and use the [SDK](https://docs.scribase.com/docs/sdk.md) instead.

Local databases use your installed PostgreSQL 17 server binaries (`initdb` and
`pg_ctl` must be on `PATH` — for example `brew install postgresql@17` on macOS or
the `postgresql-17` package on Debian/Ubuntu). The optional application services
are the upstream service binaries — `gotrue` (auth), `storage-api`
(storage), `realtime`, and `edge-runtime` (functions) — found next to the
`scribase` binary or on `PATH`. A missing service is skipped with a message;
the database always comes up.

```sh
# Check your API configuration once you have a token (optional for local work)
scribase doctor
```

### 2. Start the local stack

From your project directory, start the full local stack — Postgres, auth,
storage, realtime, and functions — with one command. No Docker and no
configuration file are required for the database; service binaries are resolved
from the same directory as the `scribase` binary or from `PATH`.

```sh
scribase dev
```

Scribase boots Postgres locally, runs bootstrap migrations, then brings up the
application services. The process blocks and prints connection information:

```
preflight: service binaries
  auth       found    /usr/local/bin/gotrue
  storage    found    /usr/local/bin/storage-api
  realtime   found    /usr/local/bin/realtime
  functions  found    /usr/local/bin/edge-runtime
database ready at .scribase
```

To start only specific services:

```sh
scribase dev --services auth,storage
```

### 3. Apply a schema

```sh
scribase dev up --schema schema.scribase
```

The schema file uses the Scribase schema language — a typed model definition
that compiles to Postgres DDL with row-level security policies baked in. See
[Aegis Policy Compiler](https://docs.scribase.com/docs/aegis.md) for the policy syntax.

### 4. Connect

`scribase dev url` prints the connection string for the primary database:

```sh
psql "$(scribase dev url)"
```

### 5. Branch for a feature

```sh
scribase branch new my-feature
# returns the branch connection string
```

Scribase uses copy-on-write snapshots to create branches in under a second.
Each branch is an independent Postgres cluster under `.scribase/`.

## Next steps

- [Hosted quickstart](https://docs.scribase.com/docs/hosted.md) — sign up, create a token, make your first API call
- [Your own cluster, by agreement](https://docs.scribase.com/docs/self-hosting.md) — for a deployment outside hosted Scribase
- [CLI reference](https://docs.scribase.com/docs/cli.md) — all commands and flags
- [Control API](https://docs.scribase.com/docs/api.md) — the `/v1` REST interface
- [SDK](https://docs.scribase.com/docs/sdk.md) — the `scribase` TypeScript client
- [Concepts](https://docs.scribase.com/docs/concepts/branching.md) — branching, auth, storage, realtime

## Configuration

The local stack resolves configuration from environment variables.

| Variable | Purpose |
|---|---|
| `SCRIBASE_HOME` | Override the `.scribase` workspace directory |
| `SCRIBASE_API_URL` | Control-plane API the CLI talks to — `https://api.scribase.com` for hosted Scribase |
| `SCRIBASE_ACCESS_TOKEN` | Personal access token or organization API key ([how to create one](https://docs.scribase.com/docs/api/tokens.md)) |
| `SCRIBASE_CURL_BINARY` | Override the `curl` binary used by the CLI |