lolly-work

The Lolly control plane - identity and provisioning, governance, online services, telemetry analytics. Open source under the Mozilla Public License 2.0 (MPL-2.0); designed to be hosted by an organisation (SUSE first), brand-agnostic so any deployment is just config + a pack mount.

The compass: OSS = individual freedom · OSS + control plane = organizational freedom. Lolly renders on-device by design; everything hosted lives here (the public MCP server is the one exception).

The 1.1.3 release records the matched Lolly source, component versions, migrations and the checks required before publication. The 1.1.2 release keeps its own page, and the 1.1.1 and 1.1.0 releases keep their own records in past releases.

The default server and render-worker containers use Node 26.12.1. CI checks Node 26; the SUSE BCI and admission images retain their separately qualified Node 24 base. The source minimum remains Node 24.

Getting started

The official installation directory lists upstream images, Helm/Rancher, European cloud foundations, YunoHost and the neutral VM/Dokploy packages, with their publication and qualification status.

A running web UI + CLI, dead easy. The one install guide is docs/install.md (served in the console too, at /admin#/docs):

• See it now, install nothing - the hosted sandbox at https://lolly.work (passwordless personas, governed console, live GET renders).
• Evaluate locally - pnpm install && pnpm run demo (Node 24+) → a fully-seeded governed deployment at http://localhost:8787.
• Deploy for real - self-hosted: single host (Compose / systemd) or Kubernetes/Helm. The safest, most sovereign path is the SUSE stack - SLES + SUSE Rancher Prime (paid) or openSUSE Leap + Rancher Community (free): SUSE's reproducible builds + governed EU (Prague) supply chain, air-gappable, no US hyperscaler (docs/deployment.md → Hosting and operating-system choices).

The hosted demo runs on UpCloud in Frankfurt, on openSUSE Leap and K3s, in a separate evaluation namespace. Its sample data resets on restart; it is never the production deployment model. Prerequisites and per-OS steps (SLES / openSUSE Leap / macOS) are in docs/install.md; the full operator set is in docs/ (below).

Documentation

The complete Lolly and Work documentation lives at https://lolly.tools/info. The canonical Markdown and navigation are maintained in the Lolly repository.

This repository's docs/ directory is a generated, version-pinned bundle for the console at /admin#/docs and offline installations. Existing guide links continue to work. docs-pin.json records the exact canonical source and every file hash; pnpm run verify:docs-pin checks the bundle without a separate Lolly checkout.

To change a guide, edit its canonical source, then follow the bundle update instructions. Keep the docs pin appropriate for the Work release; updating documentation does not repin the engine.

Layout

docs/           operator documentation (also served at /admin#/docs)
server/src/     the app - Node, node:http + node:crypto, native TS; no framework and no third-party crypto.
                Runtime deps are the render plane (jsdom, resvg, sharp), Postgres (pg) and collab (ws, yjs)
  config/       instance.json loader (+ env secrets)
  iam/          OIDC (generic, Keycloak-first), HMAC tokens, member/guest sessions
  rbac/         roles + fine-grained grants evaluator
  policy/       tool overlays (input locking), org-config payload assembly
  links/        signed expiring revocable links (share/embed/download/guest-edit)
  audit/        hash-chained append-only log
  telemetry/    ingest (attr allowlist, attribution policy at the door), rollups
  approvals/    chains, steps, separation of duties
  catalog/      submit, lifecycle, versions, collections + the provider drivers
  collab/       live co-editing gateway, rooms, guest links
  scim/         SCIM 2.0 provisioning (Users, Group membership)
  observability/ Prometheus metrics + SIEM forwarding
  inbox/        message bridge audience targeting
  fleet/        X-Lolly-Client parsing + version registry
  blobs/        instance-owned bytes behind the BlobStore seam
  store/        memory + Postgres drivers behind one conformance-tested seam
  render/       render plane: jsdom fast path, Chromium worker client, LRU cache
  api/          router + the HTTP app
workers/render/ the Chromium render worker (its own container image)
migrations/     Postgres schema
deploy/         compose (single VM), helm (Kubernetes), vercel (the hosted demo)
packs/          deployment pack mount (your pack is data, never committed; packs/demo ships)

Run it

# Install the pinned package manager once (or use Corepack).
npm install --global [email protected]
pnpm install                              # once per checkout
cp instance.example.json instance.json   # dev provider enabled, gated mode, packs/demo
npm start                                # → http://localhost:8787

# sign in at http://localhost:8787/admin, or mint a cookie for scripting:
curl -i 'http://localhost:8787/api/auth/[email protected]'   # → session cookie
curl -s http://localhost:8787/healthz

After signing in, open Customer setup at /admin#/setup for guided configuration, identity and a checked sample.

The example config ships an owner and an admin persona: role is derived from group membership (literal defaults or idp.roleGroups mappings), so only an owner can reach instance.config or store a catalog-provider credential. Full walkthrough and verification steps: docs/install.md.

pnpm test             # node:test over tests/ (Postgres conformance runs when LW_TEST_DATABASE_URL is set)
pnpm run typecheck    # tsc --noEmit (needs devDependencies installed)

When changing console assets, run pnpm console:build and commit the updated console/index.html. Its revision URLs are derived from the entire console source tree, including imported modules and styles. pnpm console:check refuses stale references; normal tests, direct start and YunoHost releases run that check. Both container profiles and the optional Vercel package generate the same URLs. Assets remain ordinary ES modules with no-cache revalidation; there are no manually maintained bundle copies. The image release probe loads the entry selected by the HTML, follows its imports, and exercises a transfer preview in an isolated authenticated memory-store fixture.

Admin console: http://localhost:8787/admin - dashboards (activity, top tools, formats, fleet), links, messages, audit (hash-chain view), people, and Docs (this repo's docs/, rendered in-console). Light/dark, no build step, no external assets.

Admin CLI (same API as the console, parity by construction):

pnpm run cli login --email [email protected]   # or `npm link` once, then plain `lw`
pnpm run cli summary          # or: whoami · fleet · audit verify
pnpm run cli links --all
pnpm run cli msg send --title "Update by Aug 15" --severity action --shells tauri --max-engine 1.52.99

Postgres: set DATABASE_URL and migrations auto-apply on boot; without it the memory store runs (evaluation semantics - state resets on restart).

Secrets come from env (LW_SESSION_SECRET, LW_LINK_SECRET, LW_IDP_CLIENT_SECRET); in dev they fall back to ephemeral randoms - sessions die on restart, which is correct.

Demo lolly-work

There are two entrypoints, and they don't share state - pick the one that matches what you're showing. The store is in-memory either way (unless DATABASE_URL is set), so seeded/created data evaporates on restart.

pnpm run demo - the full self-contained demo (see DEMO.md for detail). Builds its own config (it ignores instance.json), seeds everything - 4 personas, tool overlays, an approval chain, projects/sessions, catalog lifecycle, messages, telemetry, fleet, links, approvals - and serves the built web shell from the sibling OSS repo (../lolly, or LOLLY_OSS_DIR) same-origin at /. Same-origin is what activates the in-shell employee governance UX: the sign-in gate, locked tool inputs, and the locked user profile (identity fields IdP-locked, feature-flag toggles hidden).

pnpm run demo    # → http://localhost:8787 (PORT=8788 for another port)

Sign-in links are printed at boot (dev provider, no passwords). To demo the locked profile: sign in as [email protected], open the profile view in the shell - firstname/lastname/email/title render padlocked (mode: locked, source: idp in GET /api/v1/org-config). The admin console is at /admin - sign in as [email protected]. A shell dist built before the org governance module makes the demo fall back to open mode (data + console still demo; the in-shell governance UX needs a fresh pnpm run build:web in the OSS repo - the demo never builds anything).

npm start - split development. Boots from instance.json with an empty store: control plane + console on :8787, your own Lolly dev server (e.g. Vite on :5173) separately. Set instance.appUrl (e.g. "http://localhost:5173") so the console's "Open Lolly" and deep links point at your dev shell, and instance.pack at a real pack mount (e.g. the OSS repo) so the Design-system tab and console theming show the actual brand tokens instead of the neutral fallback. Cross-origin means no shared session cookie - the in-shell governance UX won't activate here; use pnpm run demo for that.

What is available

Customer setup at /admin#/setup guides an owner through six steps: deployment, identity, provisioning, brand/assets, sample output and finish. It generates validated non-secret configuration, checks the settings after restart, records observed owner sign-in and creates a checked downloadable sample.

For external originals, open Providers at /admin#/providers. WebDAV / Nextcloud and Google Drive have typed configuration, exact member groups, original-file testing and sync before activation. Google Drive also captures registered browser consent and seals the refresh token. The other provider kinds retain their advanced forms and documented consent flows.

The control plane also provides:

• OIDC/proxy identity, SCIM provisioning, member/guest sessions, current role mappings, deny-wins grants, service-token revocation and owner-only credential administration.
• Tool and input governance, managed brand sources, approval chains, signed links, catalog lifecycle, collections, versions and fifteen read-only provider kinds.
• Recoverable renders and batches, retained output/evidence downloads, fixed organization delivery targets and automation output references. Rendering uses the pinned, unmodified engine; available formats depend on the installed pack and worker.
• Telemetry, fleet and activity views, hash-chained audit, SIEM forwarding, migrations, retention and erasure, with memory evaluation and durable Postgres deployment paths.
• Compose, systemd and Helm deployment, a separate Chromium worker, API and CLI access, and operator documentation served inside the console.

The status and roadmap records verified behavior and remaining acceptance work. Real customer identity/source tests, matched employee-client and worker releases, service-token scopes/expiry, editable-default precedence and approval-bound ordinary exports remain separate work. A passing local example does not complete customer acceptance.

Third-party provider terms

Catalog providers are integrations, not replacements: the external system stays the source of truth and lolly consumes read-only inside its own workflow. Every deployment brings its own API tokens/OAuth apps (none ship in this repo), drivers use only publicly documented endpoints, and provider names appear descriptively only - this project includes an integration for Brandfolder etc., and is not affiliated with those services.

House rules carried from the OSS repo: zero-dep server style (the services/ca/services/mcp pattern), engine consumed pinned and unmodified when it arrives, no SUSE strings in code - the deployment name lives in instance.json.

License

lolly-work is licensed under the Mozilla Public License 2.0 - see LICENSE. The vendored Lolly engine (vendor/@lolly/engine, vendor/@lolly-tools/core) is also MPL-2.0, consumed as a pinned, unmodified snapshot. Bundled third-party code keeps its own permissive licenses (MIT / BSD / Apache-2.0) and fonts are OFL-1.1; every required notice is reproduced in THIRD-PARTY-NOTICES.md with the machine-readable graph in sbom.cdx.json.