ackandClaude Fable 5.1
0d01e23d7c
From the development repository at 299f73d, 2026-10-11: hosting from the site documented; a page loaded from a notebook and left unchanged is not kept again; notebooks and pages are deleted from the chooser, to the system's Trash (--trash); the Notebooks button. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
4.3 KiB
Kokkoja in five minutes
The shortest path from nothing to a shared page, for someone who is at home in a terminal. Everything here is said at more length in A host's Kokkoja, A guest's Kokkoja and How Kokkoja works.
What you are installing
Kokkoja has three parts. The client is plain JavaScript that runs
in a browser. The local program, kokkoja.py, serves the client to
your own browser and keeps your notebooks as directories of SVG files;
without it the notebooks live in the browser's storage. The relay
passes the participants' messages, encrypted end to end so that it
cannot read them, and serves the client as a web site, from which anyone
can host or join with nothing installed; Andy's relay at
kokkoja.andykopra.com is there for you, and you can run your own.
Requirements
- Linux or macOS. Windows is untried.
- Python 3. The local program uses the standard library only; nothing is installed with pip.
- Firefox, Brave, Chrome or Safari.
- A pen tablet, or the pencil of a tablet, for handwriting. A mouse does for pointing and rough marks.
Install
git clone https://git.andykopra.com/ack/kokkoja-rel.git kokkoja
cd kokkoja
or download and unpack
https://git.andykopra.com/ack/kokkoja-rel/archive/main.zip. Nothing
else touches your system. Updating is git pull; removal is deleting
the directory.
Host a session
With nothing installed: open https://kokkoja.andykopra.com/, enter a
name, press Start a session; the notebooks are then in the browser.
With the program, for notebooks as files:
python3 kokkoja.py --relay wss://kokkoja.andykopra.com/relay
The program prints http://localhost:8760/#token=… and opens your
browser there. Enter a name, choose a notebook, press Start a
session. The relay is remembered, so from now on python3 kokkoja.py
suffices. Keep the terminal open while the session lasts; Ctrl-C ends
the program.
Session in the toolbar shows the invitation: a link such as
https://kokkoja.andykopra.com/#join=wss://kokkoja.andykopra.com/relay%23<secret>.<host id>
Send it by any means, or let the other person scan the QR code under it.
The part after # is never sent to the web site; it carries the
session's secret, so treat the link as you would a meeting link.
Join a session
Open the invitation link in a browser. Enter a name and press Join. That is all; the page is in front of you. A guest with the local program installed can instead paste the link into their own program's start screen, and then their notebooks are files on their computer rather than in the browser's storage.
The screen in one paragraph
The toolbar holds the pen, text, eraser and hide tools, colours and
line widths, the view commands (Fit, A4, Widen, Shrink, Extend), the
host's page buttons (New, Image, Notebooks), your notebook, Keep, Export
and Session. Rest the pointer on any button for two seconds for its
explanation. Each participant writes on a layer of their own that
nobody else can change. The page is saved continuously to the current
notebook, Current.svg; Keep makes a dated copy. Rest the pen on an
image to move it, near a corner to scale it. Ctrl (Command on a Mac)
with the wheel, or with a pen drag, zooms.
Where things are
- Notebooks:
~/Documents/Kokkoja/<notebook>/, one SVG file per page, which any browser displays. - The program's settings, including your identity key and the remembered
relay:
~/.config/kokkoja/on Linux,~/Library/Application Support/kokkoja/on macOS. - Options:
--notebooks DIR,--port N(default 8760),--no-browser,--site URL,--config DIR.
Your own relay
python3 -m venv .venv && .venv/bin/pip install -r relay/requirements.txt
.venv/bin/python relay/kokkoja_relay.py --host 0.0.0.0 --port 8770
Then hosts start with --relay ws://<host>:8770. For a public server
with TLS, the web site and a systemd service, deploy/ has the nginx
and systemd files and deploy/README.md the steps. The relay stores
nothing and sees only ciphertext.
Tests and types
.venv/bin/pip install -r tests/requirements.txt
.venv/bin/python -m unittest discover tests
npm install && npm run check
The end-to-end test needs Firefox and geckodriver; the type check is TypeScript over JSDoc comments and is the only use of npm.