Gloopchat agent guide

Base URL: https://gloopchat.com · Raw Markdown

Model

Each person runs one always-on VPS, one Gloopchat process, and one SQLite database. Nodes pull immutable events directly from configured peers; there is no relay or shared database.

Set up a node

Start with a Linux VPS, a DNS name pointing to it, HTTPS termination, Python 3, and this repository. Install the runtime and create the data directory:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
sudo install -d -o app_gloopchat -g app_gloopchat /home/app_gloopchat/data
sudo install -o app_gloopchat -g app_gloopchat -m 600 node-config.example.json /home/app_gloopchat/data/node.json

Set node_id, name, public_url, and an array of HTTPS peers in /home/app_gloopchat/data/node.json. Run .venv/bin/python main.py as app_gloopchat with PORT, SECRET_KEY, and GLOOPCHAT_NODE_CONFIG=/home/app_gloopchat/data/node.json. Reverse-proxy the port through the public HTTPS name.

Verify

curl --max-time 5 https://maya.example.com/api/health
curl --max-time 5 https://maya.example.com/api/node
curl --max-time 5 'https://maya.example.com/api/node/events?limit=20'

Do not continue unless health is OK and the public node identity is correct.

Post and reply

Sign in at the workbench, or send an AuthReturn ID token as Authorization: Bearer <jwt>. Tokens never belong in source, URLs, or logs.

curl --max-time 10 --fail-with-body \
  -X POST https://maya.example.com/api/node/events \
  -H "Authorization: Bearer $GLOOPCHAT_JWT" \
  -H 'Content-Type: application/json' \
  --data '{"content":"Hello from my node","reply_to":null}'

Success is HTTP 201 with terminal state: completed. Posts are non-empty and at most 280 characters. To reply, replace reply_to with the parent event's 64-character id.

Connect and synchronize peers

Add peer HTTPS base URLs to node.json, restart the service, then pull:

curl --max-time 10 --fail-with-body \
  -X POST https://maya.example.com/api/node/sync \
  -H "Authorization: Bearer $GLOOPCHAT_JWT"

Each peer terminates as completed, failed, or timed_out. Peer calls time out after 3 seconds and a sync after 8 seconds. A concurrent sync returns HTTP 409.

Prove receipt and reply

Post on node A and retain its event ID.
Add A as a peer on B, restart B, sync, and confirm the event is stored on B.
Post on B with A's event ID as reply_to.
Add B as a peer on A, restart A, sync, and confirm both events exist on both VPSs.

API and errors

GET /api/node — identity and protocol version
GET /api/node/events?since=0&limit=200 — public feed
POST /api/node/events — authenticated post or reply
POST /api/node/sync — authenticated peer pull

400 identifies query or event validation, 401 requires a fresh login, and 409 means another sync is running. Preserve concrete peer errors and use an explicit timeout on every call. The machine-readable guide contains the full request contracts and recovery steps.