The short path

Four steps to a running planner.

  1. Get the code

    Clone the repository. You need Docker with the Compose plugin, or Node 24 and pnpm 10 to run from source.

  2. Configure

    Copy .env.example to .env and set a setup token, so nobody else can choose your passphrase first.

  3. Start it

    docker compose up -d --build, then open port 8787 and choose a passphrase of 12 or more characters.

  4. Back it up

    The database is one file. The backup command is safe while the server runs. Copy backups off the machine.

Terminal
git clone <repository address>   # the repository is being prepared for public release
cd glideworth
cp .env.example .env

# Edit .env: set GLIDEWORTH_SETUP_TOKEN to a long random value
# (for example the output of: openssl rand -hex 24) and leave GLIDEWORTH_BOOTSTRAP_KEY empty.

docker compose up -d --build
docker compose ps                  # wait for "healthy"
# Open http://localhost:8787 and choose a passphrase of 12 or more characters.

The full guide, with a reverse proxy, every setting, upgrades and troubleshooting, isSelf-host with Docker. Running from source is described in the repository's README.

Requirements

What you need.

  • A Linux, macOS or Windows machine running Docker Engine 24 or newer with the Compose plugin (or Docker Desktop, OrbStack and similar). The image is built for amd64 and arm64, so a 64-bit Raspberry Pi 4 or newer works.
  • About 1 GB of free memory and 1 GB of disk to start. As a rough guide from one small test, an idle container with the sample household used about 190 MB of memory; simulations are the heavy part, and more cores make them faster. These are estimates, not guarantees.
  • To reach it from other devices over the internet: a domain name, a reverse proxy that terminates TLS, and ports 80 and 443 open.
  • Without Docker: Node 24 and pnpm 10, then pnpm install, pnpm build and pnpm start.
Your responsibilities

What you run and maintain yourself.

Self-hosting is free of charge and not free of work. Running the server means you are the operator.

  • HTTPS. The container speaks plain HTTP. Bind it to loopback and put a reverse proxy that terminates TLS in front, then set GLIDEWORTH_TRUST_PROXY=true and GLIDEWORTH_PUBLIC_URL. Caddy needs three lines:
Caddyfile
glideworth.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8787
}
  • Backups. A backup on the same volume protects against mistakes, not against losing the disk. Copy backups elsewhere regularly, and store them as carefully as the live data, because a backup holds your whole plan and your hashed credentials.
  • Upgrades. You choose when. Read the release notes, back up first, then pull and rebuild. Database migrations run automatically at start-up. Tax-table updates and fixes reach you when you upgrade.
  • Security. Keep the image up to date, set the setup token before exposing a new instance, and keep the port off the public internet until you have a passphrase and TLS.
  • Your passphrase. With no email, recovery is a command on the host.
  • One instance. A single container per database, on local storage.
Backups and upgrades

Both are a few commands.

Back up

Terminal
# A consistent copy, safe while the server runs
docker compose exec glideworth node dist/cli/admin.js backup --out /data/backups/manual.db

# Copy it off the volume, and then off the machine
docker compose cp glideworth:/data/backups/manual.db ./glideworth-backup.db

Restore

Stop the server first. The current database is kept next to the restored one in case you need to undo it.

Terminal
docker compose stop glideworth
docker compose run --rm --no-deps \
  -v "$PWD/glideworth-backup.db:/restore/backup.db:ro" \
  glideworth node dist/cli/admin.js restore --from /restore/backup.db --force
docker compose up -d

Upgrade

Use release tags rather than the development branch for anything you rely on.

Terminal
docker compose exec glideworth node dist/cli/admin.js backup --out /data/backups/pre-upgrade.db
git pull
docker compose up -d --build
docker compose logs --tail 50 glideworth   # migrations run at start-up

You can also export one household as portable JSON from the app. That is not a full backup, since it leaves out users, API keys and version history.

Network behaviour

What the server talks to.

A self-hosted Glideworth is local-first. Your data lives in one SQLite file on your machine or Docker volume. It sends no telemetry, no analytics and no version check, uses no hosted AI and links to no accounts. The only network calls the server makes are the webhooks you configure, and those are blocked for private addresses unless you allow them. In the browser there is one optional dependency on the internet: the API reference page at/docs loads its viewer script from the jsDelivr CDN. The web app itself does not. Building the Docker image downloads dependencies once, which is you fetching software, not the app reporting anything.

If you connect an AI assistant, it sees what its tools return, within the scopes of its key, and the provider of the model sees that too. See API and MCP and security.

Support

The support boundary.

Self-hosting support is community support. Questions go to GitHub Discussions and reproducible bugs to GitHub issues, once the repository is public, with logs and without real financial data, passphrases or API keys. There is no service-level agreement, no private support channel and no guaranteed response time for people who run it themselves. Security problems go to the private route, never to a public issue.

Questions

Self-hosting questions.

Is anything switched off in the self-hosted build?

No. It is the whole product under the AGPL-3.0 licence: no licence key, no feature that needs payment, and no telemetry. Code that exists for the hosted service, such as billing and multi-customer accounts, is in the same repository and stays out of the way of a self-hosted install.

What happens if I forget my passphrase?

There is no email, so there is no reset link. On the host, run the admin command reset-owner-passphrase, which prints a one-time token you enter in the app with a new passphrase. The owner is signed out everywhere.

Can I run several copies for availability?

No. SQLite on one volume means one instance serves one database. Run a single container, with the volume on local SSD storage rather than a network filesystem.

Can I move to the hosted service later, or back?

Yes in principle: both run the same code and Glideworth imports its own export file. The hosted service is not open yet, so only the self-hosted direction can be done today.

Rather not run a server?

Glideworth Cloud runs the same code for you.