Getting started

• Node.js 20 or newer. The Git Republic needs nothing else: no database, no package installs, no build step. Check with node --version.
• git, to get the code and keep copies in step.
• Optional: Radicle (rad), to replicate copies peer to peer; cloudflared, to put a node online from home.

It runs on macOS, Linux and a Raspberry Pi.

git clone https://github.com/ttschoonover/entity
cd entity
node cli/index.js help

The code is on GitHub, and the modules are in a separate repository. It is © Timothy Schoonover, all rights reserved: ask before using it for your own group.

Each republic lives in its own folder, with its own copy of the code beside its record, so each can upgrade on its own schedule. The program is called entity; to type it as a command, add this to ~/.zshrc (Mac) or ~/.bashrc (Linux):

entity() { node "$PWD/cli/index.js" "$@"; }

node cli/index.js app

This opens a control panel in your browser. Create a republic asks for a name, your member id and a password, lets you pick a starting shape and the modules you want, shows every setting with what it does, and founds and serves the republic. Afterwards the panel starts and stops it, changes its settings, installs modules, publishes it on Radicle and upgrades it. It answers only on your own computer. Everything below can be done either way.

cp -R entity my-republic && cd my-republic
entity preset list
entity preset apply worker-coop
entity found --id you --name "My Republic"
entity serve --settle

Open http://localhost:7780. found makes your key (in ~/.entity/keys/) and the first record; serve --settle runs the page and records each act as soon as it arrives.

A preset sets the starting rules and modules. The ones included are: assembly, worker-coop, housing-coop, society, company, currency, micronation, federation, fandom and proprietor. Everything a preset sets can be changed later, by decision.

• On the page: use your key file (Use a key file I already have), then add a password or a passkey under Ways to sign in, so you never need the file again.
• New members open the page and join with a username and a password or passkey. Depending on the rules, they are members at once, or once the members admit them.
• A password works on any device. A passkey belongs to one device and one web address: add one on each device you use.

• Propose anything on the page: a change to a setting, an office, a budget, a module. The page picks the rule it needs.
• Vote on the Votes tab. Each rule has its own quorum, threshold and number of readings: the more a change matters, the harder it is.
• Edit anything after it is made (titles, seats, terms, a grant's powers) with the Edit form beside it: it proposes the change under the rule that created it.
• Reverse a mistaken decision from its page (Propose reversing this): a new decision that undoes it. The record itself is never edited.
• Delegate with grants: a treasurer may be allowed to spend within the budget, and nothing more. Every use is published, and can be undone.
• Remove a member from their page, by decision, with a reason; the record keeps everything they did.

Offices, elections, budgets, meetings, a forum, a wiki, signed agreements, an investment fund and more are modules. Point the republic at a module source once:

entity module source github:ttschoonover/entity-modules@main

Then, on the page: Settings → Install or upgrade modules. Each install is a proposal, pinned to the exact code (its digest) the members approve; once it carries, every copy fetches that code, checks it, and installs it. From the terminal: entity module available, entity module add NAME --as you.

A Raspberry Pi at home is enough for most groups. With a domain on Cloudflare:

cloudflared tunnel login
cloudflared tunnel create mynode
cloudflared tunnel route dns mynode coop.example.org
cloudflared tunnel run --url http://localhost:7780 mynode

For several sites, list each hostname and its port in ~/.cloudflared/config.yml (ingress:). A node's own settings are in its node.json: settleAfter (seconds to wait before settling; 0 for at once), publishOnSettle, look and colour (the page's default style), and finality.signAs (to sign checkpoints automatically).

entity radicle init            # publish on Radicle (add --private for members only)
entity sync --settle           # push and pull, then settle
rad clone rad:z…               # someone else takes a full copy

Every copy replays and checks the whole record. To decide between copies that disagree, install finality and name the validators who sign checkpoints (see Modules).

entity upgrade check dir:../entity     # does the record replay exactly with the new code?
entity upgrade propose dir:../entity --as you
entity upgrade apply                   # once the members approve it

Modules upgrade the same way, one at a time (entity module upgrade NAME), or from Settings on the page.

Two things matter: the republic's folder (its record) and your keys (~/.entity/keys/). Copies on Radicle or other members' machines also hold the record; only you hold your key, unless you sign in with a password or passkey.

The Manual covers every part in depth; Commands lists every command; Modules describes each module and its settings; the Cookbook has recipes for common situations; Guarantees lists each promise the software makes, with how it keeps it.