Install
One double-click or one command, the same nineteen questions either way, and how to finish the ones you skip.
There are two ways in and they ask the same things. The double-click opens a page in your browser that
explains each answer as it asks for it. The command asks in the terminal, supports --dry-run, and is what
you would put in a script. Neither one installs anything outside this folder.
Before you start
- Node 22.6 or newer. See What it needs. The installer checks this first and stops with a link rather than half working.
- Roughly two gigabytes of disk space, most of it the packages.
- A terminal you can leave open. Closing it stops the app, which is the point: nothing is installed as a service, a daemon or a login item.
The double-click
Open the setup file
On macOS, setup.command. On Windows, setup.bat. On Linux, setup.sh. On macOS and Linux the file may
need to be made runnable once:
chmod +x setup.commandRead the check
The first screen reports the Node version it found, whether the packages are already installed, and which of the nineteen names are already set. Nothing has been changed at this point.
Answer the questions
They are grouped in the order a fresh installation needs them: the database address first, then the app's own keys, then the deployment's. Every one of them explains what stops working without it.
You can leave anything for later
Press Leave for later and the feature that needs it stays switched off. The answer is recorded so
the screen knows it was a decision rather than an oversight, and the panel's
Platform → Environment screen is where you come back and finish it.
Let it write
The installer writes the seven app names into .env.local and runs the Convex command that sets the twelve
deployment names, one at a time, showing each result. It never prints a value back that you gave it, and
it always shows a masked hint such as sk_live_...f3a9 so you can tell the right key went in.
Open it
The last screen has one button: open Loomis on http://localhost:3000. That starts the app and opens it
for you.
The first time on macOS
The setup file is a script rather than a signed application, so macOS may refuse it. That is what the dialog is about: it is not a warning about this file in particular, it is the rule for everything downloaded and not signed.
That is once per download. If a newer copy of the folder arrives, it is a new file and macOS will ask again.
The one command
Everything the installer does is also a command, and it is the same walk:
pnpm configureIt needs no packages installed beforehand, so it works on a fresh copy of the folder. It writes the same
files, keeps a dated .bak of the previous .env.local, and never echoes a value back.
| Flag | What it does |
|---|---|
--dry-run | Says what it would write and where, and writes nothing |
--yes | Takes the shipped answer for anything you are not asked, for scripted runs |
--only=app | Does one half of it: app for .env.local, deployment for the Convex names |
--file=path | Uses a different env file than .env.local |
--no-color | Plain output, for a log or a pipe |
--help | Lists the flags and the names |
`pnpm setup` is not this
pnpm has a setup command of its own and it will win. The script here is
pnpm configure.
Coming back later
Open the same setup file again and it does not install anything twice. It finds this copy already set up and shows the screen with Open on localhost, which starts the app and opens it. Closing that terminal window stops the app.
To change one answer, run pnpm configure --only=app and give just that name, or set it by hand in
.env.local. For a deployment name, the command is:
npx convex env set NAME "value"Where the answers go
| Where | Which names | Read by |
|---|---|---|
.env.local in this folder | The seven app names, such as NEXT_PUBLIC_CONVEX_URL and SETTINGS_SECRET | The Next.js process on the machine it runs on |
| The Convex deployment's environment | The twelve deployment names, such as BETTER_AUTH_SECRET and GOOGLE_CLIENT_ID | The functions and the database |
.env.local is written with restrictive permissions and is excluded from version control by .gitignore.
.env.example in the same folder lists all nineteen names with a line about each, and never contains a real
value.