Getting Started with Amsonia Core

From clone to Console.

Install Docker with the Compose plugin and Go 1.25.13 or newer, then run:

git clone https://github.com/willunylabs/amsonia-core.git
cd amsonia-core
make demo

The command builds PostgreSQL, the least-privileged database roles, migrations, API, and Console. On first run it prompts for the one system administrator. Open http://127.0.0.1:8080 and sign in with that account.

make demo-status
make demo-down

Secrets stay local.

The launcher generates independent high-entropy database passwords and runtime/maintenance binding secrets in .amsonia/local.env. The directory is Git-ignored; the file is created with owner-only permissions. The administrator password is read without echo and is not stored by the launcher.

PostgreSQL is exposed only on the loopback interface for local examples. The runtime role remains a non-owner, non-superuser role without BYPASSRLS.

Manual infrastructure path.

For direct development, install PostgreSQL 16+, Node.js 22.15+, and npm 10.

Create an empty database plus separate runtime and maintenance logins. Neither runtime role should be a superuser, database creator, role creator, or RLS bypass role.

createdb amsonia_core
createuser --login --no-superuser --no-createdb \
  --no-createrole --no-bypassrls --pwprompt amsonia_runtime
createuser --login --no-superuser --no-createdb \
  --no-createrole --no-bypassrls --pwprompt amsonia_maintenance

Run migrations as the database owner, then install the least-privileged grants using the checked-in role-provisioning script. Store binding secrets outside the repository.

Migrate, bootstrap, and start

export AMSONIA_MIGRATION_DSN='postgres://db_owner@127.0.0.1:5432/amsonia_core?sslmode=disable'
go run ./cmd/amsonia migrate
go run ./cmd/amsonia bootstrap-admin
go run ./cmd/api

The API uses the non-superuser runtime DSN and an unpadded base64url tenant-binding secret. Do not expose either value to the Console or commit them.

Start the Console

npm --prefix web ci
VITE_API_PROXY_TARGET='http://127.0.0.1:8080' npm --prefix web run dev

Open http://127.0.0.1:3000 and sign in with the administrator created by the operator CLI.

Run the quality gates

make check

Then run the host business-table proof to verify that PostgreSQL, not a forgotten handler predicate, rejects cross-tenant access.

Run the RLS proof →Full repository guide ↗Security model →

Getting started