---
title: Getting started
section: Start here
order: 2
summary: Install Balsa, configure access, and open your first company.
---

These instructions apply to the Balsa application repository. The documentation website is a separate project. If you do not yet have application source access, the public documentation does not grant it; follow the availability notice on the website.

## Requirements

- Node.js 22 or newer and pnpm 10 or newer.
- Docker for the included PostgreSQL service, or an existing PostgreSQL database.
- An API key for the selected model provider, OpenAI or OpenRouter.

## Set up the application

From the application repository root:

```bash
pnpm run setup
```

Setup creates `.env` when missing, fills blank application secrets, prepares file storage, installs dependencies, starts the default local PostgreSQL service when applicable, and applies migrations. Existing values are preserved. It does not supply a model-provider API key.

Edit `.env` using `.env.example` as the reference. Select the provider and set its API key privately. Configure your database if it is not the included local service. See [Configuration](/docs/configuration/).

Then run:

```bash
pnpm run doctor
pnpm dev
```

Open `http://localhost:3000`. Doctor is read-only. Resolve its failures before using the application; it names the missing setting or setup step without printing secrets.

### Setup options

```bash
pnpm run setup -- --dry-run
pnpm run setup -- --no-install
pnpm run setup -- --no-docker
pnpm run setup -- --no-migrate
pnpm run doctor -- --json
```

Use `--no-docker` when you manage PostgreSQL separately. Skipping migrations is useful for inspection, but new features still require the checked-in schema.

## Choose an access mode

With `AUTH_MODE=better-auth`, configure `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`. Enable `AUTH_ALLOW_SIGN_UP=true` while provisioning intended users. Set `AUTH_SIGN_UP_CODE` before enabling registration on a reachable host, then disable registration afterward.

The account registered with `LOCAL_OWNER_EMAIL` adopts the original local owner’s data. Secure registration before that account is created. Every registered user on a self-hosted installation receives access to all its companies; this is not a client-by-client sharing model.

For a private local evaluation, `AUTH_MODE=disabled` uses the local owner without login. Bind the app locally or provide external access control. Disabled login offers no network protection. See [Companies and users](/docs/companies-and-users/) and [Security](/docs/security/).

## Run in containers

Review `.env` before starting the full profile:

```bash
docker compose --profile full up --build
```

The app container applies migrations and stores uploads in a persistent volume. Stop it with:

```bash
docker compose --profile full down
```

Stopping retains volumes. Removing volumes deletes stored data and is not a routine troubleshooting step. See [Operating an installation](/docs/operations/) for backups and upgrades.

## Begin with evidence

Use synthetic fixtures in `fixtures/company-zero` for an evaluation, or prepare your own approved statements and exports. Entering an opening balance can establish a journal amount; it does not prove that starting cash reconciles to bank evidence.

Continue with [Your first financial review](/docs/first-review/). That guide takes you from source review to a preserved plan without assuming an upload is already complete or correct.