TiddlyInstall

Make an installer for a program, for Windows, Linux and macOS, from a web page that needs no server.

You point it at a program -- a GitHub repository, or a URL -- and say what it needs to run: Python, Node.js, Ruby, PHP, Java, .NET, R, Go, Rust, Zig, Nim, a C compiler. It builds an installer for each platform that brings that runtime with it, so the person installing does not have to have anything already.

The page is one HTML file. Save it and it keeps working: no server, no network, no account. It targets machines as old as Windows XP, Linux with glibc 2.17, and macOS 10.9, and it can install any of 30,828 runtime releases from a catalogue built into the file.

Open tiddlyinstall.html -- download it and open it in a browser. That file is the whole product.

What it will and will not tell you

An installer built here says, before it changes anything, exactly what it is about to do: what it downloads, the SHA-256 of each file, where things go, and what runs. Then it asks.

Two of those claims are checkable and one is not, and the difference is the point:

• The runtime setup is ours, provably. Every runtime install we publish is signed in advance, and an installer that uses one unchanged carries a proof that the steps inside it are the ones we published. Your machine checks that proof against a key built into the installer, offline, with no network. Change one byte of a download's hash and the proof stops matching. Two things we cannot sign in advance, because they are not written until you ask: an install command a publisher wrote themselves, and a package build, whose command carries the package name. Those carry no proof, and the installer says so rather than implying one.
• What we sign is our installer program, never the software someone installs with it. A code signature says the program is ours and unmodified -- like the signature on a web browser, which says nothing about the sites you visit.
• We cannot tell you the program is safe. We did not write it and have not read it. Install it because you trust whoever published it.

The page has a Trust page that says all of this against the file you are actually holding -- checking the documents inside it as it loads, and saying so when one does not check out -- and a Verify page that reads an installer back and tells you what it can and cannot prove about it. Neither asks you to take its word for anything.

The signing key

Everything we sign uses one Ed25519 key, id 97930ea1888d1a12. It is named in plan-key.id, and every build from this repository refuses to proceed with a different one. Comparing a page's fingerprint with that file is a check made somewhere we do not control your copy of the page -- which is the only kind worth making.

Licence

MIT, LICENSE at the root. Third-party code keeps its own notices and they travel with any copy of the one-file page; the list is under Third-party code.

---

Working on the code

Everything below is for people changing TiddlyInstall rather than using it.

Where things are

src/web_client/      the pages and their JavaScript (was web/)
src/build_server/    the Node build server (was server/)
src/installers/      the Windows, Linux and macOS base installers (was installer/)
src/shared/          the code the page and the server both run (was shared/)
src/vendor/          third-party bundles (was vendor/)
out/                 the built one-file site, gitignored (was dist/)
registry/            the runtime registry (was runtime-metadata/)
tests/ tools/                             unchanged

Renamed on 2026-09-22. Three things follow from it and are easy to get wrong: the page's relative imports (../shared/x.js, ../vendor/x.js) still resolve because all three moved into src/ together; the build server computes the repository root two levels up now, not one; and the ti-server, ti-server-mac and ti-redis systemd user units name the new paths -- a unit left pointing at the old one serves a stale page without saying so.

registry/ is the runtime registry: where to get each language's runtime, per OS, architecture and version. It is not a package registry. "Registry" on its own -- in this repository's code, on the review screen, on the installer form, in docs/launch-shapes.md's derivation ladder, and in the offline page's promise that nothing but registry lookups leaves the page -- still means npm, PyPI, RubyGems or crates.io, and none of that wording changed with the folder. So the folder is always written with its slash, and where a slash will not fit, write "the runtime registry".

Front end

Plain HTML, CSS and ES modules (ES2017, so the one-file site runs in Firefox 52 ESR, Chrome 58+, Safari 12; docs/plan.md section 1.11). No framework. The pages talk to the build server (see the API notes); serve them over http (python3 -m http.server at the repository root, then open /src/web_client/index.html), since browsers don't load ES modules from file://. Without JavaScript the pages still show the form and its CSS-only behaviours.

Third-party code

MIT, LICENSE at the root.

The one-file page carries the notices for the code that is in the page -- they are in its ti-licences block, so they travel with any copy of it. That now includes 7-Zip 9.20 (7za.exe, inside the Windows base, inside the page): the LGPL asks for the licence itself rather than an attribution line, so the full text of LGPL 2.1 is in the block, with a pointer to the source at https://www.7-zip.org/download.html. tools/build_site.py refuses to build a page without it.

Still outside the block: the three NSIS plugin DLLs in the Windows base. The table below is where those are recorded.

Which build server: ?api= on the page URL, else the one saved in this browser, else whichever server is serving the page: its own origin when a build server answers there, or https://tiddlyinstall.warpgate.io when the page came from there. A copy hosted anywhere else builds in the page and contacts nobody until Default is pressed, which offers the server the page was built with. Each page's footer shows which it is and has a change button. If the server can't be reached, a banner says so and the page retries with backoff (1 s up to 60 s) and carries on once it's back. Nothing on the page is lost.

Headless test run:

python3 -m http.server 8093 &
google-chrome --headless=new --virtual-time-budget=20000 --dump-dom http://127.0.0.1:8093/tests/tifile.html | grep -o 'PASS all [0-9]*\|FAIL [^<]*'

Build server

src/build_server/ is the build server: plain ES modules on Node.js 20 or later (node:http, no web framework), with BullMQ and ioredis for the job queue on Redis. It runs the same JavaScript as the page: src/shared/resolve.js (plans), src/shared/builder.js (jobs), src/shared/tifile.js (installer files) and src/shared/icon.js (icons). It serves the API (see the API notes), the one-file site from out/ (python3 tools/build_site.py writes it), our copies of the runtime files at /mirror/, and the built installers. (It replaced a Go server on 2026-09-19; docs/plan.md section 1.8.)

cd src/build_server && npm ci                      # BullMQ and ioredis
node src/build_server/server.js -addr :8080 -redis 127.0.0.1:6390 -public https://tiddlyinstall.warpgate.io

node src/build_server/server.js -h lists the flags: -addr, -redis, -redis-db, -data (records, sources, icons, built files, the signing keys and the plan signing key; default src/build_server/data, gitignored), -catalog and -local (the runtime catalogue and our copies of its files, default under ~/projects/installer-builder-runtimes), -policy (default src/build_server/policy.json), -site, -bases, -public (this server's URL, written into records), -workers, -mirror and -mirror-last (where plans point for our mirror, and whether it comes last). A second instance needs its own -redis-db and -data (the Mac test server's is src/build_server/data-mac). On this machine they run as the systemd user units ti-server (:8080) and ti-server-mac (127.0.0.1:8081), on Redis from ti-redis (its files in src/build_server/data/redis).

Tests:

cd src/build_server && npm test                    # node --test: unit tests and the server end to end
node tests/resolve-test.mjs              # the resolver against 3,095 saved plans and answers, also lazily loaded
node tests/linux-x86-test.mjs            # what 32-bit x86 Linux is offered, per runtime (design.md 1.11)
node tests/refusal-test.mjs              # combinations refused up front, and the many that must not be
node tests/builder-golden.mjs            # src/shared/builder.js: records and plans for every runtime, also lazily loaded
node tests/github-test.mjs               # GitHub sources: the page and the server write the same record (--live also
                                         # checks the API's file list against the real tarball; it costs rate limit)
node tests/backend-golden.mjs            # a running server (default :8080, --data src/build_server/data)
sh src/installers/unix/test_freshness.sh          # the Linux engine on stale plans: nonce, revocation list, expiry
                                         # against saved answers: errors, jobs, plans, takedown

The server test needs Redis and uses database 5 (TI_TEST_REDIS, TI_TEST_REDIS_DB). The three golden tests compare with answers saved in tests/golden/ from the Go server while it was the reference the JS was checked against byte for byte; each test's header says what is kept and how to record the goldens again after an intended change.

Tools: tools/snapshot.mjs writes the catalogue snapshot and runtimes summary the one-file site carries (and with -split DIR, the snapshot split by folder as the page carries it; -from catalog.gz -split DIR splits one already written); tools/resolve.mjs prints a plan, or the files with no copy on our mirror; tools/plansig.mjs signs and checks plans with a plan signing key; tools/mirror_fetch.py fills the mirror host from the vendors and tools/mirror_check.py says whether the manifest, the local runtime store and the mirror host agree; tools/mirror_scope.mjs says what mirroring every version we offer would cost (files and bytes, per runtime) and, with -out DIR, writes both halves of the fetch — a download_plan_all.json per folder for registry/tools/download.py --plan (the local store) and a mirror-manifest-all.json for mirror_fetch.py (the mirror host) — from one enumeration, so the two cannot disagree about what is in scope. Files we have no permission to mirror are listed in registry/store/mirror-excluded.json and left out of both.

Topping up the mirror is two halves: the mirror host and the local runtime store, or the pull achieves nothing. A mirror URL only reaches a plan through LocalIndex (src/build_server/lib/catalog.js), which walks this machine's copies under ~/projects/installer-builder-runtimes; a file that is on the mirror host but that this machine has never seen has no local path, so its plans still name the vendor alone. tools/mirror_check.py exits non-zero on exactly that state, for the manifest and every mirror host in registry/store/mirror-hosts.json.

Two manifests, deliberately separate: registry/store/mirror-manifest.json is what installers download, and registry/store/toolchain-manifest.json is what we build them with (NSIS, osslsigncode, llvm-mingw, Redis) — no plan ever names those, and keeping them out is what lets the runtime check stay a clean pass or fail. Check the second with tools/mirror_check.py registry/store/toolchain-manifest.json.

Design notes

The design notes this project was built from are not in the repository. They are working notes -- long, written to think with rather than to be read, and in places out of date with the code. Documentation written for someone else to read is a separate job and has not been done yet.

Comments throughout the source cite them by their old paths (docs/design.md, docs/format.md section 4, and so on). Those are pointers into that material, not files here.

• Runtime catalog: where to download 13 languages' runtimes per OS, architecture and major version, mirrors, checksums, and per-version limitations (metadata backup; binaries live outside git)