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. The package lives in its own repo, lawalletio/lawallet-startos, and wraps the same published image as every other target, masize/lawallet-nwc.

Property	Value
Package id	`lawallet-nwc`
Images	`masize/lawallet-nwc` (web) + listener + `postgres:15-alpine`
Architectures	`x86_64`, `aarch64`
Web UI	port `2288` (LAN, `.local`, Tor, or a custom domain)

Install the current release

LaWallet NWC is not yet listed in the Start9 Marketplace. Until the listing is available, install the current release by sideloading its package:

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.
In the StartOS dashboard, open System → Sideload a Service, select the downloaded .s9pk, and complete the install.
Start the service. Postgres starts first; once it is ready, the web app applies pending Prisma migrations and starts automatically.
Open the service's Web UI from the StartOS dashboard.

The releases/latest download always resolves to the newest package release. When LaWallet NWC is added to the Start9 Marketplace, you will be able to install and update it from the Marketplace instead.

Build the package yourself

Build from lawalletio/lawallet-startos when you need to inspect or change the package, or prefer not to use a released artifact. 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:

In the Web UI, sign in with a NIP-07 browser extension (Alby, nos2x) or by pasting your nsec.
The first user to sign in claims the root admin role — do this immediately.
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 three public .well-known endpoints that your domain must forward to the service so lightning addresses and Nostr identity resolve:

/.well-known/lnurlp/<username> — LUD-16 lightning address callback
/.well-known/nostr.json — NIP-05 identity
/.well-known/verify — LUD-21 verification

Point your domain at the StartOS interface for the service and forward those paths. 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 JWT, listener authentication, NWC vault, and PostgreSQL secrets on first install (stored on the service's main volume), and sets the runtime environment automatically:

Variable	Value
`DATABASE_URL`	bundled localhost Postgres
`JWT_SECRET`	generated on install
`LISTENER_AUTH_SECRET`	generated once; shared by web/listener
`NWC_VAULT_SECRET`	encrypts RemoteWallet/proxy NWC data; shared by web/listener
`LISTENER_URL`	private bundled listener
`NODE_ENV`	`production`
`PORT` / `HOSTNAME`	`2288` / `0.0.0.0`

Existing installs are upgraded safely: if the listener or NWC vault secrets are missing from an older store.json, the package generates and persists them once. 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).
Backups: StartOS backs up the main volume — database, cached Nostr profiles, and the generated secrets — so a restore reproduces the instance exactly.

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

The package's web image tag and version are bumped automatically whenever LaWallet NWC publishes a release — see UPDATING.md in the package repo.

On this page