Start9 Deployment

StartOS is the sovereign-server OS behind Start9. LaWallet NWC ships as a StartOS service package (.s9pk) that bundles the web app, NWC listener, and its own PostgreSQL database into one installable app — nothing external to wire up. It wraps the same published images as every other target: masize/lawallet-nwc and masize/lawallet-nwc-listener.

From 2.7.0:1 the Community marketplace listing and the sideload .s9pk share one layout (main + db, Postgres dumped with withPgDump()). They use the same package id (lawallet-nwc) and are interchangeable: you can install from the marketplace or sideload, then take the other track as an in-place update.

Sideload 2.7.0:0 kept Postgres on main/postgresql/data. Updating that install to 2.7.0:1 (marketplace or sideload) copies the cluster onto db once and then removes the old tree.

Install from the Start9 Community registry

The Community listing is the default path for new StartOS installs. Open Marketplace → Community and install LaWallet NWC.

Wait for the listing to reach 2.7.0:1 (or later) so it includes the NWC vault key and the shared layout. Until then, sideload the current lawalletio release below.

Sideload the current release

Sideload if you already installed from lawalletio, or if you need a .s9pk before the Community listing publishes the same version:

1. Download the universal package — lawallet-nwc.s9pk. It supports both x86_64 and aarch64 StartOS servers. You can also choose a specific version from the release history.
2. In the StartOS dashboard, open System → Sideload a Service, select the downloaded .s9pk, and complete the install.
3. Start the service. Postgres starts first; once it is ready, the web app applies pending Prisma migrations and starts automatically.
4. Open the service's Web UI from the StartOS dashboard.

Take v2.7.0 or later. The v2.6.0 asset predates start-sdk 2.0 and cannot install on StartOS 0.4 (generateSecret charset). From 2.7.0:1 the sideload package matches the Community layout.

Build the package yourself

Build from lawalletio/lawallet-startos when you need to inspect or change the package. The build machine needs the StartOS SDK, including start-cli, plus Node.js, Docker, and make.

git clone https://github.com/lawalletio/lawallet-startos.git
cd lawallet-startos
npm install
make universal

This produces lawallet-nwc.s9pk, a universal package that you can upload through System → Sideload a Service as above. To make separate architecture-specific packages instead, run make; it creates lawallet-nwc_x86_64.s9pk and lawallet-nwc_aarch64.s9pk.

For a StartOS host already configured for the SDK, make install builds and sideloads the package directly. See the package repository for its current build and update details.

First run — claim root

There is no admin password. LaWallet NWC authenticates with Nostr:

1. In the Web UI, sign in with a NIP-07 browser extension (Alby, nos2x) or by pasting your nsec.
2. The first user to sign in claims the root admin role — do this immediately.
3. Set your domain, create lightning addresses, connect a remote wallet (NWC), and issue cards from the dashboard.

Make lightning addresses resolve on your domain

LaWallet NWC serves public .well-known endpoints that your domain must forward to the service so lightning addresses and Nostr identity resolve. The onboarding wizard probes these three:

• /.well-known/lnurlp/<username> — LUD-16 lightning address callback
• /.well-known/nostr.json — NIP-05 identity
• /.well-known/lawallet.json — instance discovery

LUD-21 payment verification still lives at /.well-known/verify. Forwarding the whole /.well-known/ prefix (the recipes the wizard prints) covers that path too.

Point your domain at the StartOS interface for the service. The in-app onboarding wizard prints copy-paste rewrite recipes (Cloudflare, Nginx, Caddy, Vercel, and more).

What's managed for you

The package generates and persists six independent secrets on first install and sets the runtime environment automatically. Secrets live on main (store.json); Postgres lives on db.

Do not reuse KEY_VAULT_SECRET as NWC_VAULT_SECRET. They encrypt different data.

Existing installs are upgraded safely: if the listener-request or NWC vault secrets are missing from an older store.json, the package generates and persists them once. Postgres and JWT secrets are never regenerated. Configure the NIP-57 receipt signer nsec in Admin → Settings → NWC Services. It is encrypted with the generated vault key and is not a StartOS environment variable.

The web startup pass encrypts any legacy plaintext RemoteWallet NWC rows before its health check becomes ready. The listener waits for that health check and uses the same generated key.

For the full env-var reference (used when self-hosting outside StartOS), see apps/web/.env.example.

Health & backups

• Health check: the service reports healthy once GET /api/health responds (it verifies the database connection). The Payment Listener has its own check on GET /health.
• Backups: from 2.7.0:1, StartOS dumps Postgres from db and copies main. Sideload 2.7.0:0 backups that still have main/postgresql/data are migrated onto db when you restore onto 2.7.0:1.

Limitation

The bundled landing screen links to https://lawallet.io (baked into the published image at build time). Your admin dashboard and wallet work regardless.

Updating

Image tags plus package version are bumped automatically when LaWallet NWC publishes a release — see UPDATING.md in the package repo. Sideload .s9pk files publish from that repo automatically. The Community marketplace listing is a separate tree (Start9-Community/lawallet-startos); lawalletio opens a PR there after each bump, and Start9 reviews before it ships. Layouts match from 2.7.0:1, so a sideload install and a Community install of the same version are interchangeable.