Install with Docker
Run Glideworth in one Docker container with its data in a volume, protect first-run setup with a token, choose a passphrase, and create API keys.
The self-hosted build is the whole product. It has every feature, no licence key and no paywall, and it has no
telemetry: it reports no usage, errors, version checks or analytics to anyone. The only outbound connections the server
makes are webhooks you configure yourself. In the browser, the API reference page at /docs loads its viewer script from
a public CDN; nothing else in the app contacts a third party. The software is AGPL-3.0-only.
Glideworth runs as one container: the web app, the REST API, the MCP server and the API reference are all served on one port, with the data in a single SQLite file on a volume.
Requirements
- A Linux, macOS or Windows machine with Docker Engine 24 or newer and the Compose plugin (or Docker Desktop,
OrbStack and similar). The image is built for
linux/amd64andlinux/arm64, so a 64-bit Raspberry Pi 4 or newer works. - About 1 GB of free memory and 1 GB of disk to start with. See Sizing.
- For access from other devices over the internet: a domain name pointing at the machine, and ports 80 and 443 open for the reverse proxy.
- Without Docker you can run from source: Node 24 and pnpm 10, then
pnpm install,pnpm build,pnpm start.
Install
-
Get the code and create your settings file.
Terminal git clone https://github.com/glideworth/glideworth.git cd glideworth cp .env.example .env -
Edit
.envbefore the first start. SetGLIDEWORTH_SETUP_TOKENto a long random value of at least 8 characters, for example the output ofopenssl rand -hex 24. This stops a stranger who finds the port from choosing your passphrase first. LeaveGLIDEWORTH_BOOTSTRAP_KEYempty, or set your own secret. The example development key in.env.exampleis public and the server refuses it in production. -
Build and start.
docker compose up -d --build docker compose ps # the service should become "healthy" docker compose logs -f glideworth -
Open
http://localhost:8787(change the host port withGLIDEWORTH_PORTin.env).
Data lives in the glideworth-data Docker volume and survives restarts and upgrades. Do not point GLIDEWORTH_DB_PATH
anywhere outside /data. The container runs as a non-root user and has a health check on /health.
To stop it: docker compose stop. To remove the container but keep the data: docker compose down.
First run: passphrase and setup token
On a fresh database the web app asks you to choose a passphrase of 12 or more characters and, if you set
GLIDEWORTH_SETUP_TOKEN, to enter that token. You become the owner and are signed in. After that the setup screen is gone
for good.
-
Use a password manager. There is no email, so there is no “forgot password” link.
-
Forgot the passphrase? On the host run:
docker compose exec glideworth node dist/cli/admin.js reset-owner-passphraseIt prints a one-time token. In the app choose “Use a reset token” and enter the token and a new passphrase. The owner is signed out everywhere.
-
If you left the setup token empty, the server logs a warning at start-up. Set one, or keep the port reachable only from your own machine, until you have chosen a passphrase.
API keys
For scripts and AI assistants, create keys in the app under Settings, then API keys, or with:
docker compose exec glideworth node dist/cli/create-key.js --name laptop --scopes read
Give each tool the least scope it needs. MCP write tools stay off unless you set GLIDEWORTH_MCP_ALLOW_WRITES=true.
Sizing
These are estimates from one small test, not guarantees. An idle container with the sample household used roughly 190 MB of memory and almost no CPU, and the built image is about 500 MB. The database for a household is small: hundreds of kilobytes with the sample, a few megabytes after years of use with history and snapshots.
| Use | CPU | Memory | Disk |
|---|---|---|---|
| One person or household, occasional use | 1 core | 512 MB | 2 GB |
| Several households, regular use, 10,000-trial Monte Carlo runs | 2 to 4 cores | 1 to 2 GB | 5 GB plus backups |
Monte Carlo runs use worker threads: GLIDEWORTH_MAX_JOBS run at once and each is split over up to
GLIDEWORTH_MC_SHARDS threads. On a small machine, lower GLIDEWORTH_MAX_JOBS to 1. SQLite on one volume means one
instance serves one database: run a single container, not several replicas, on local SSD storage rather than a network
filesystem.
What this does not do
It does not terminate TLS (see reverse proxy), back up off the machine for you (see backups), or run more than one replica. Support for self-hosters is community support: GitHub Discussions for questions and issues for reproducible bugs, with no service-level agreement.
Last checked against the code on .