The guard direction from 2026-11-04 is corrected: the co-op DOES use Loomio and
wants every new member added. Removing members/notifications is not the goal —
not duplicating them is. The feature is switched back ON and the sync is made
idempotent instead.
Enablement
* LOOMIO_SYNC_ENABLED now defaults to ENABLED (kill switch: set =0 to pause).
Restoring LOOMIO_API_KEY and deploying is all that is needed again.
Non-duplicating ADD (the real fix), two layers:
* (a) live pre-check against Loomio group membership (b3 index, ordered and
paginated stably). An address already in the group is skipped SILENTLY —
it is never placed in an invite payload, so no API call about it can fire
a notification or email.
* (b) members.loomio_invited_at: an address we have handed over before is
never sent again, even if it is not (yet) visible in the live roster.
* FAIL CLOSED if the live roster cannot be read.
* remove_absent is never sent.
Removal reconciliation preserved (deactivation must still propagate):
* A member in the group who is no longer active is removed via a TARGETED
b3 DELETE by membership id — it names only the member being removed, so it
cannot re-invite or notify anyone staying. Operator allowlist
(LOOMIO_ALWAYS_KEEP) is never removed. 404 (already gone) counts as
success, so a re-run neither errors nor churns.
* The keep-set is computed from the UNFILTERED active list: an active member
whose Cloudron account is not yet activated is not removed (only their
invite is deferred).
Tests: tests/test_loomio_guard.py (26/26) — add/dedupe, silent skip, record
guard, fail-closed, remove-once, allowlist-never-removed, targeted removal
(no present member in any payload), double-run no-op for both phases, 404
tolerance, kill switch.
Member Portal — membership middleware for the Inference Cooperative
Reconciles three systems into one membership lifecycle:
| System | Role | Source of truth for |
|---|---|---|
| Open Collective | Billing | Who is a paying member |
| Cloudron | Identity/SSO | Who can log in |
| LiteLLM | Inference | Who can use models, and how much |
Architecture
Open Collective (billing)
│ webhook
▼
┌─────────────────────────────┐
│ Member Portal (this app) │
│ - OC webhook handler │
│ - Cloudron user management │
│ - LiteLLM key management │
│ - key-injection proxy │
└─────────────────────────────┘
▲
│ X-User-Email header (LibreChat forwards identity)
│
LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend
The three responsibilities
- Webhook handler (
POST /webhook/opencollective) — listens for Open Collective membership events and activates/deactivates members. - Key injector (
/v1/*) — reads the member's email from theX-User-Emailheader, looks up their LiteLLM key, and forwards the request to the gateway with that key. - Admin (
/health,/) — health and status.
Configuration (environment variables)
| Variable | Purpose |
|---|---|
CLOUDRON_API |
Cloudron API origin (auto-set by Cloudron) |
CLOUDRON_TOKEN |
Cloudron API token (Read+Write) |
MEMBERS_GROUP_ID |
Cloudron group ID for members (grants chat access) |
LITELLM_BASE |
LiteLLM gateway URL |
LITELLM_MASTER_KEY |
LiteLLM master key |
OPENCOLLECTIVE_WEBHOOK_SECRET |
Optional webhook signature secret |
PORTAL_KEK |
Required. Base64-encoded 32-byte key-encryption key. Member chat keys (members.key_token) are stored AES-256-GCM-encrypted at rest (enc1: prefix) and decrypted in memory only when served (dashboard, LibreChat key feed, LiteLLM management). Generate with python3 -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())". If unset, the portal runs but refuses to encrypt new keys, keeps legacy plaintext, and logs CRITICAL. Rotating it requires re-encrypting every row (decrypt with the old key, encrypt with the new). |
ALLOWANCE_POLICY |
report (default) | on. report computes every allowance decision and changes nothing; on performs renewals and sends the one reminder. Deactivation is gated separately by ALLOWANCE_DEACTIVATE. |
ALLOWANCE_DEACTIVATE |
off (default) | on. When on, a member who was reminded and is still unpaid after the grace window is moved to the inactive group. Defaults off so renewals/reminders can run before anyone loses access. |
PAYMENT_GRACE_DAYS |
Days after the single reminder before an unpaid member is deactivated (default 7). |
Tier budgets
Governance decision (set in Loomio). Defaults:
free— $2/month of tokensmember— $15/monthsupporter— $30/month
LibreChat wiring
Point LibreChat's custom endpoint at this portal (not directly at LiteLLM), and add the identity header:
endpoints:
custom:
- name: "Inference Cooperative"
apiKey: "${LITELLM_KEY}"
baseURL: "https://portal.inference.coop/v1"
headers:
X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
models:
default: ["deepseek-v4-flash", "gpt-oss-120b"]
fetch: true
Status
Scaffold — the three handlers are stubbed with the correct integration points. Remaining work before production:
- Verify Open Collective webhook event names + payload shape
→
order.processed(every payment),new member(first only),firstPaymentflag - Verify Cloudron user-creation API payload (role/group assignment)
→
POST /api/v1/userswith{username, email, displayName, role, active}→ group assignment viaPUT /api/v1/users/:userId/groupswith{groupIds: [...]} - Add a persistent store (SQLite) for email→key mapping
→
key/listreturns token strings (not objects), so we store email→token locally - Verify LiteLLM key/generate + key/list payload shapes against live gateway
→
key/generatereturns{key: "sk-..."};key/listreturns{keys: ["<token>", ...]} - Add HMAC signature verification for the OC webhook (if OC supports it)
- Wire the OIDC addon for admin access
Scheduled tasks (scheduler addon)
Three jobs run inside the container via CloudronManifest.json → addons.scheduler:
- membership_sweep (nightly 3am) —
sweep.shcalls the portal's own/admin/sweep(auth:X-Admin-Token=WEBHOOK_TOKEN) to reconcile members against the live Open Collective list: provisions missed signups, deactivates lapsed members, syncs Loomio + Matrix. Idempotent; a missed webhook self-heals within 24 hours. The same sweep also runs the payment-driven allowance reconciliation (below). - rag_refresh (nightly 3:30am) —
rag_refresh.pypulls this repo's sibling docs from the Gitea raw API (public, no credentials), uploads changed files to Open WebUI (OWUI_API_KEY), attaches them to the shared knowledge collection (DOCS_KNOWLEDGE_ID), reindexes, and re-grants the members group. State persists in/app/data/rag_refresh_state.json. - metrics_snapshot (nightly 3:15am) —
metrics_snapshot.pyrecords one row per day into themetrics_dailytable: members, newsletter subscribers, Matrix membership, spend, request counts, and energy/CO₂. A source that cannot be read yields NULL for that metric rather than a zero.spend_usdis the co-op-wide total and deliberately spans every team, the co-op's own operator accounts included;operator_spend_usdis the breakout of that portion, served through/broker/metricsso the member dashboard can show the co-op's own share alongside the total.--backfillrebuilds history idempotently. Methodology: Energy and carbon metrics.
Verify after any manifest change: the deploy log must show
setupAddons: ... scheduler ... listing all three tasks, and each script must
succeed when run manually inside the container.
Allowance renewal (payment-driven, join-day anchored)
Each member has a monthly allowance (MEMBER_BUDGET, currently $15). The
allowance renews on the day of the month the member joined, never on the day
Open Collective happened to charge them — OC aligns every member's charge onto
the collective's common billing day, so anchoring to the payment date let an
early charge move the boundary and skip a cycle entirely. The join day is stored
per member (members.anchor_day) and the reset is pinned there.
Whether the allowance renews is decided by asking Open Collective directly, on
the sweep's own schedule (not inferred from webhook delivery): a member with a
live recurring contribution (order status ACTIVE or PROCESSING — a payment
in flight is not a missed payment) renews; a member with no live recurring
contribution gets one reminder email, and is deactivated only after
PAYMENT_GRACE_DAYS. One-time payments are not an allowance cycle — they top up
the non-expiring credit balance and are untouched here. There are no annual
contributors (verified 2026-11-04: 104 orders, 87 MONTHLY, 17 ONETIME, zero
annual), so only the monthly case is implemented.
Every decision (renewed / reminded / deactivated, plus the payment date or its
absence) is written to allowance_log and answerable from that record. Run
POST /admin/allowance?mode=report (X-Admin-Token) for a no-op report that
changes nothing; mode=send performs renewals and sends the reminder and
requires ALLOWANCE_POLICY=on. Deactivation additionally requires
ALLOWANCE_DEACTIVATE=on.
Energy & carbon metrics
The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens, using per-model factors whose provenance varies: measured for GreenPT, assumed equal for one sibling model, and an explicit order-of-magnitude estimate for providers that disclose nothing. Only output tokens count, and a day with no measured tokens is recorded as NULL rather than zero.
Energy and carbon metrics documents the factor table, the
formulas, the tripwire that catches unit errors, the schedule, and — most importantly —
which parts are measurements and which are estimates. What members are told is in
co-op/docs/energy.md.