Getting started

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:

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.

Then run:

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

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 and Security.

Run in containers

Review .env before starting the full profile:

docker compose --profile full up --build

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

docker compose --profile full down

Stopping retains volumes. Removing volumes deletes stored data and is not a routine troubleshooting step. See Operating an installation 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. That guide takes you from source review to a preserved plan without assuming an upload is already complete or correct.