Ternbook is a web directory made for the modern internet. It is easy to get onto, and has features like Webmaps and instance gossiping.
This page is meant for developers who want to make their own Ternbook instance. For people who want to add their website to a Ternbook instance, check here.
Ternbook is an open-source protocol built for the human, anti-algorithmic web.
In-line with that spirit of transparency: about 98% of the codebase is generated
using LLM based coding agents (Replit agent) with the remaining 2% consisting of
human architectural design, testing, and fine-tuning.
Every single feature was thoroughly reviewed, integrated, and deployed to production
by a human (me!!!!). The system design is real, the protocol works, and the code is
fully audited for your self-hosting peace of mind. The Render page is the "proof"
that it works!!
This project is optimized to be run on Replit and Render (for now, if you managed to like run on another service LMK and I'll update the README).
Make sure to set .env variables or else Ternbook can't function!
DATABASE_URL (needed for storing website info)
SESSION_SECRET (this can be random)
IAL_SECRET (ditto)
PORT (you can default to 8080)
TERNBOOK_ORIGIN (this is required for gossip to function)
Render
-
Install dependencies:
pnpm install --frozen-lockfile && pnpm run typecheck:libs && pnpm --filter "@workspace/ternbook" run build && pnpm --filter "@workspace/api-server" run build && mkdir -p artifacts/api-server/dist/public && cp -r artifacts/ternbook/dist/public/* artifacts/api-server/dist/public/
-
Run the project:
pnpm --filter "@workspace/api-server" run start
For Active development other than render
-
Install dependencies:
pnpm install
-
Run the project:
pnpm run dev:standalone
For Devs looking to locally test Prod (make sure to install dependencies before doing this!)
-
Compile
pnpm run build
-
Run the project
cd artifacts/api-server pnpm run start
Note
I actually haven't done a local machine deploy yet. If anyone has successfully done it, LMK. note to self: remove this notice if done!!!
-
Get the Code
I recommend git for this because it easy!
git clone https://github.com/11bunno11/ternbook.git
-
Install Dependencies
Navigate into the project folder using your terminal and install the required workspace tools:
cd ternbook pnpm install(Note: The root configuration will block standard npm or yarn execution to ensure strict lockfile safety across environments!)
-
Spin up the App To run the full multi-layered system (Express API server + Vite compiler) on a single port with instant hot-reloading, run:
pnpm run dev:standalone
Note
For the full specifications, check here.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/healthz |
Health check |
| GET | /api/sites |
Paginated site listing with tag filtering |
| GET | /api/tags |
All valid tags (core content, vibe, system) |
| GET | /api/search |
Full-text search with query syntax |
| GET | /api/random |
Random site for discovery ("Wander") |
| GET | /api/map |
Graph nodes + links for D3 visualization |
| POST | /api/heartbeat |
Site registration / renewal |
| GET | /api/gossip/send |
Pull recent-heartbeat bundle (for other instances) |
| POST | /api/gossip/receive |
Accept a heartbeat bundle from a federated instance |
Contributions, bug reports, and feature requests are completely welcome! I'll prioritize bug reports and high quality Pull Requests. If you want a feature to be made, fork the Repo and make the thing you want to have on Ternbook, and open a PR (some may be rejected). Alternatively, do discussions, and if many agree on a feature to be implemented, I might make it real.
If you found any security issues, contact me here and I'll look into it.
Look at SECURITY.md for more precise info.
This project is licensed under the AGPLv3 License - see the LICENSE file for details.
