Configuration reference

One JSON file plus environment secrets. The standalone server reads ./instance.json, or whatever path LW_CONFIG names. (LW_CONFIG_JSON is a different thing and not interchangeable: it carries the whole config as a string and is read only by the Vercel entrypoint.) Unset keys take the defaults below - instance.example.json is a working starting point, and server/src/config/instance.ts is the authority.

signed by Lolly Demovector SVG2026-08-11Tự kiểm chứngTải tệp đã ký11 paths160 nodes83 groups10 images195 KBsigned by Lolly Demovector SVG2026-08-11Tự kiểm chứngTải tệp đã ký11 paths160 nodes83 groups10 images195 KB

Secrets are never in the config file. Config is safe to keep in git; secrets come from the environment.

deployment

Production refuses memory storage, development login, open access, missing identity, an unsafe public base URL, signing secrets shorter than 32 bytes, inconsistent worker or signer configuration, and an incompatible active pack. Helm defaults to production; the evaluation overlay and example JSON explicitly select evaluation. An old shell cannot bypass production validation with LW_ALLOW_STALE_SHELL.

Run pnpm run check:setup with the deployment's config and environment to read the same local checks as startup. It exits 1 for failed production checks and 0 otherwise; a zero exit does not turn not-tested integrations into acceptance evidence. It neither connects to the database nor calls identity, renderer or asset providers. The owner console's Customer setup page additionally checks the running store and pending migrations.

instance

pack supports materialized trees, modern profiles.json roots and legacy brand layouts. Selection lives in the Store; mounted files are never rewritten. See Design-system administration for persistence requirements and explicit tokens selection.

The publication fence records both the generation and the mounted release digest. Startup verifies this identity before /readyz succeeds; /healthz remains a liveness check. The engine pin is normalized as canonical JSON in both source and bundled servers. When upgrading a server that recorded the earlier raw-file pin identity, provision a higher positive catalogPublicationGeneration for the reviewed release once. Keep the existing fence and sequence history; deleting them would remove rollback protection.

Under a non-open access mode, a shellDir that is missing or predates the org/ governance module stops boot. In evaluation, LW_ALLOW_STALE_SHELL=1 downgrades the legacy shell guard to a warning; production validation still refuses that legacy shell.

For generated deployment files and a staged owner cutover, use Customer setup.

idp

The following settings apply to each OIDC provider independently and are not inherited by additional entries. GitHub and password entries refuse these keys. See Enterprise identity deployment for registration, claim semantics, acceptance checks and lifecycle procedures.

Gated access needs idp.issuer, proxyAuth.enabled or a password entry - or dev.enabled for local work. The server refuses to start otherwise. See identity.

Email and password (kind: "password")

For people who cannot use the instance's other sign-ins, for example because their own organisation blocks unreviewed OAuth apps. Add one entry to idp.additional:

{ "id": "email", "kind": "password", "label": "Email and password" }

• At most one password entry. It takes no issuer, clientId, clientSecretRef, groupsClaim, claimMap, hostedDomain, tenantId, scopes or authParams, and emailVerification can only be claim. It needs no secret, so setup counts it as complete.
• It can be the only sign-in: then no issuer is needed and /api/auth/login is the form itself. Such an instance has no admin to issue the first link, so the first owner gets theirs from the operator: list them in bootstrapOwners and run node scripts/password-link.ts --email <their address> where the server runs (it needs the server's LW_CONFIG, DATABASE_URL and LW_SESSION_SECRET, and prints the link). The same command lets a locked-out bootstrap owner back in. During restricted evaluation (dev.enabled on), a dev-login admin can issue links instead, and the console's sign-in screen offers the dev sign-in with the password form beside the dev sign-in.
• No self sign-up, and nothing is emailed. An admin or owner issues a one-time link from the console (Copy sign-in link on an invitation, or Copy password link on a person) and passes it on. The link sets the password and signs the person in. It works once, for 7 days, and issuing a new link for an address cancels its unused ones.
• Whoever holds a link can sign in as its address, so a link that leads to an owner, or that adds a password to an account that already signs in another way (unless it is the issuer's own), is owner-only. A link is also issued only for an address admission lets in now: an open invitation, a listed email or domain, or an account the lists still admit. All of this is asked again when the link is opened and used, on the issuer's standing at that moment, so a link stops working when its issuer is disabled or loses the admin role, or the address has since come to need an owner. "Disable access" cancels the person's unused links.
• An owner signs in with a password only when an owner (or the operator command) issued the link that set the password. A password set from an admin's link stops working for an account that is later made an owner, until an owner issues a new link.
• Every password sign-in runs the same admission, linking, invitation and "Disable access" checks as any other sign-in. Setting a new password from a link ends every session the account had. Removing the email and password sign-in from a person (their profile, or the console) deletes the password.
• Passwords are 12 to 256 characters and not the email address. They are stored as scrypt hashes (N 2^15, r 8, p 1). At most two hashes are computed at once and 32 wait; past that a sign-in gets 503 with Retry-After at once.
• Ten sign-in attempts in a row without a success lock that address for 15 minutes; a successful sign-in resets the count. Each attempt is counted before its password is checked, so parallel guesses get no more than ten checks, and attempts during a lock are not counted, so guessing does not extend the lock. An admin can lift a lock from the person (Unlock), without a new password. An unknown address, a wrong password and a locked address all get the same answer.
• The sign-in and link routes use the auth rate-limit bucket below, per client IP, on top of the lockout. A browser that runs out gets a page saying to wait a minute.
• The forms are served with Referrer-Policy: strict-origin, not no-referrer: a form post from a no-referrer page carries Origin: null, which the CSRF check refuses. A proxy in front must not replace that header on /api/auth/ (the YunoHost package's nginx sets no-referrer on /api/, so email and password sign-in does not work there as shipped).

See email and password for the flow.

policy

policy.invites is optional; leaving it out keeps the defaults above. Unknown keys and values outside the lists are refused at startup. The tier and the domain list govern invitations, which let someone new sign in; sharing a project with someone who already has an account needs manager on the project and an allowed role only. The console does not edit this block (its configuration document covers grants, overlays, chains, providers, flags and catalog fields), so change it in the configuration and redeploy. Lolly reads the limits from org-config. See sharing.

"policy": {
  "invites": { "allow": "members", "domains": ["example.com"], "maxTtlHours": 168, "projectRoles": ["viewer", "editor"] }
}

policy.requests is optional too, and unknown keys in it are refused at startup. Requests answer to the same rules as inviting: an approver may only grant what they could grant directly. lolly.ing runs with join requests on, the invitation lifetime at its 30-day default, and the password tick suggested for SUSE addresses:

"instance": {
  "name": "lolly.ing",
  "inviteNote": "If your organisation blocks Google sign-in (for example @suse.com), use GitHub or email and password."
},
"policy": {
  "invites": { "passwordDomains": ["suse.com"] },
  "requests": { "join": true, "project": true, "ttlDays": 14, "joinOpenMax": 50 }
}

policy.projectFiles values are whole numbers above zero, with maxFileBytes no larger than projectBudgetBytes and projectBudgetBytes no larger than instanceBudgetBytes; anything else is refused at startup. Budgets count finished files and unfinished uploads that have not expired, each at its size plus 4096 bytes for its database rows, so many tiny files fill a budget too. One person's unfinished uploads may declare twice maxFileBytes in all, and one person may download twice instanceBudgetBytes a day (counted per server process). The defaults are sized for a small hosted Postgres that also holds the file bytes (the pg blob driver); Neon's free plan, for example, has 1 GB of storage in all and stops writes past that storage limit. Raise them only with the storage to match.

"policy": {
  "projectFiles": { "maxFileBytes": 10485760, "projectBudgetBytes": 67108864, "instanceBudgetBytes": 268435456 }
}

policy.uploads follows the same rules: whole numbers above zero, with maxFileBytes no larger than ownerBudgetBytes and ownerBudgetBytes no larger than instanceBudgetBytes. Budgets count every upload that has not expired, finished or not, at its size plus 4096 bytes, and a file reference also at the size of its derivedFrom and report as JSON. One owner may hold 16 unfinished uploads at once.

Scoped uploads are off until policy.uploads.enabled is true, and an upgrade does not turn them on. Their bytes live in the same blob store as project files, under a separate instance budget, so the two instance budgets add up: with both defaults the blob store may hold 512 MiB of uploads instead of 256 MiB. A begin needs tool.use or catalog.submit, and members hold tool.use by default, so most members and service tokens can use that room. Size both budgets against the storage before turning uploads on. To keep the total at 256 MiB, split it:

"policy": {
  "projectFiles": { "instanceBudgetBytes": 134217728 },
  "uploads": { "enabled": true, "ownerBudgetBytes": 67108864, "instanceBudgetBytes": 134217728 }
}

To take a 500 MiB recording into a project, for example, lift the project file cap and its budgets together:

"policy": {
  "projectFiles": { "maxFileBytes": 629145600, "projectBudgetBytes": 1073741824, "instanceBudgetBytes": 2147483648 }
}

Submit is open to authors by default: anyone holding catalog.submit submits and the asset goes live immediately. Name a submit.chain when the org wants review. Quota scopes are group names, and a submission is charged to every group its submitter belongs to, so extra memberships only tighten a member's budget. See catalog.

catalog.versionKeep keeps everything by default; set a ceiling only when you deliberately want to bound blob growth - see operations and catalog.

Shorter sessionTtlHours bounds token lifetime if a directory change has not yet reached Work. With sessionMaxHours set, a cookie in use is renewed up to that cap, but each renewal checks the account, its session epoch and admission again first, so a person who left the lists stops at the end of their current cookie. Once Work receives a group/role change, authorization uses the live record on each request. Account disable and a session-epoch bump revoke existing member tokens on their next authenticated request. Token expiry does not replace the offboarding integration.

render

Production worker and SIEM service URLs require HTTPS with verified server certificates. Requests cannot follow redirects or include URL credentials, query strings or fragments. HTTP is accepted only for explicit loopback evaluation fixtures. For an internal CA, mount its public PEM read-only and set NODE_EXTRA_CA_CERTS before starting Node. Keep hostname verification enabled; NODE_TLS_REJECT_UNAUTHORIZED=0 is refused in production. The worker request HMAC continues to authenticate the control plane. TLS certificates and trust mounts need their own deployment qualification.

policy.serviceTokens.allowLegacyUnbounded defaults to true for existing credentials without expiry. New service credentials always use a bounded expiry. Rotate the legacy integrations before deliberately setting the policy to false.

Every tool in the committed packs/demo ships hooks, so instance.example.json and values-eval.yaml both set allowHooksInFastPath: true - that pack is curated in this repo end to end. Repoint instance.pack at a pack you do not fully control and this goes back to false, with a Chromium worker for the hooked tools.

The Chromium worker always enables its browser sandbox. A bounded launch begins at startup, and /readyz stays unavailable until the browser connects. Failed startup or recovery stops the worker without an unsandboxed fallback. LW_RENDER_BROWSER_STARTUP_TIMEOUT_MS controls that budget (default 30000, integer from 1000 to 120000); Helm uses renderWorker.browserStartupTimeoutMs. Qualify the exact Linux image and target runtime with the existing non-root, seccomp and container permissions before rollout. A host that refuses the sandbox must remain out of service until its runtime is qualified. The separate evaluation allowHooksInFastPath setting runs curated demo hooks in node:vm and has no browser isolation; keep that setting false when preparing production packs.

The worker itself takes LW_RENDER_MAX_CONCURRENT (default 4, Helm renderWorker.maxConcurrent): its per-pod render/rasterise cap. At capacity it answers 503 RENDER_BUSY + Retry-After immediately - no internal queueing, so saturation stays visible to the HPA - and drops out of readiness (/readyz) until a slot frees. Its own timeouts are LW_RENDER_NAV_TIMEOUT_MS, LW_RENDER_EXPORT_TIMEOUT_MS and LW_RENDER_TS_SKEW_MS (HMAC clock skew between plane and worker) - see workers/render/README.md.

Worker HMAC key and C2PA private key are secrets - see below and c2pa.

audit

The defaults print the head; operators must forward and retain it outside this deployment's control to establish an external anchor. Verify collection, retention and restricted deletion access in the receiving system - see audit.

dev

Keep this off in production. It bypasses OIDC entirely, and setting idp.issuer does not turn it off - the two coexist happily and the passwordless route stays live. The server warns at boot when it finds both.

proxyAuth

Reverse-proxy sign-in: an authenticating proxy in front of the instance (YunoHost's SSOwat, Authelia, oauth2-proxy) states who the person is in request headers. See identity for the contract and the security posture.

rateLimit

blobs

Where instance-owned catalog bytes live (materialized copies, published assets).

With no database at all, pg falls back to a memory blob store (evaluation only). The S3 credential is a secret, LW_BLOBS_S3_CREDENTIAL, formatted <accessKeyId>:<secretAccessKey>. This is the exit route for media-sized estates and the air-gap story: see off-boarding.

With pg, the server compares the bytes stored and read each month against the offload thresholds and alerts administrators when one is reached: see blob offload trigger.

Blob limits and integrity

Each S3 request signs the SHA-256 of its own body, so the store refuses a part that changed in transit. Work also computes the SHA-256 of the whole blob as the parts go out, and records it on the object as x-amz-meta-sha256 when it is known before the object is created: always for a single PUT or a blob already in memory, and for a streamed multipart upload whose caller declared the digest, which Work checks before completing the upload. Objects written by earlier versions have no recorded digest. For those, Work reports the S3 ETag, which is not a content digest, and reads the bytes back wherever it needs the SHA-256.

Every caller in this release hands the driver a file it already holds in memory, within that path's own byte cap: catalog submission, materialization, render and automation outputs, design-system pack downloads, staged deliveries and project file parts. The S3 driver sends such a file in parts without copying it again, but an upload streams from the client to the bucket only once those paths stream too.

For s3, give the blob credential s3:GetObject, s3:PutObject, s3:DeleteObject and s3:AbortMultipartUpload on the prefix, and s3:ListBucket on the bucket so that a missing blob reads as missing rather than refused. Where the store supports it, add a lifecycle rule (AbortIncompleteMultipartUpload) that removes incomplete multipart uploads after a day: a server that stops during an upload leaves its parts behind, and the store keeps them, and bills for them, until they are removed.

delivery

Fixed organization-owned destinations for intentional outbound delivery. This is separate from catalogProviders (assets coming in) and from a person's device-owned send targets. No destination exists by default, so an unconfigured instance sends nothing anywhere.

Provider options and credential forms:

For S3, endpoint selects MinIO, Ceph, Garage, UpCloud or another compatible store; omitting it uses AWS. For S3 and WebDAV, publicBaseUrl means the resulting object has a public URL; omit it for private storage. WebDAV permits HTTP for an explicitly private/air-gap deployment, but credentials then depend entirely on that network boundary - use HTTPS anywhere else. The signed-HTTPS adapter always requires TLS.

Give every destination its own write-limited credential even when the same service is already configured as a read-only catalog provider or as blobs.driver. Restrict it to the configured bucket, collection or receiver. A destination credential is not a person's connected-service credential and must not be reused as one.

See outbound delivery for the lifecycle, API and freedom boundaries.

submit

The instance-side half of catalog submit: a single optional pre-store scan hook. Everything an org tunes about submit lives under policy.submit above; this block is operator-only and never reaches the policy-as-code document or any shell.

Wiring ClamAV or an ICAP gateway is written up in operations.

notify

Notification egress. Absent (the default) means dormant: zero egress. Sends only to endpoints you configure, never phone-home; delivery is fire-and-forget, so an unreachable relay never fails or slows a request. What gets sent, and to whom, is written up in operations.

Emailing people notices

People notices go through one function (server/src/notify/people.ts), which writes the inbox message and, once email is on, also mails each recipient's verified address, or the address of an invitee or a person asking to join who has no account yet. Email is off by default, and every page and answer says so: the request page says the instance does not send email yet, and the console never shows "Emailed" for a mail that did not go.

Email is on only when all three hold: people.email is true, smtp is set, and the server's mail sender can confirm that the relay accepted each message. The sender in this release sends and forgets, so it cannot confirm, and people notices stay inbox-only even with the first two set. Still to be built: that confirming sender; plain-text mails sent as "Andy via lolly.ing" from the smtp.from address, which never carry text a person wrote (such as a request note) and end with "Not expecting this? You can ignore this email." and a link to stop emails from the instance; and caps of 50 invitation emails a day per inviter, one email per address a day, and one per request to each approver. Once a release carries them, switching email on takes these steps:

1. Pick a provider that gives you an SMTP relay on port 587 with STARTTLS and its own DNS records, such as Postmark, or Amazon SES. The sender address needs no mailbox.
2. Configure the relay in instance.json and apply it through your instance's reviewed deployment route. lolly.ing uses UpCloud/K3s; its old deploy/vm/push.sh route is historical (see current hosted production):
   "notify": {
     "smtp": { "host": "<relay host>", "port": 587, "secure": false, "from": "no-reply@lolly.ing", "user": "<relay user or API token name>" },
     "people": { "email": true, "fromName": "lolly.ing" }
   }

Put the relay password or token in LW_SMTP_PASSWORD in the server's environment through your deployment's secret store, never in the configuration file. On Kubernetes, use the existing instance Secret; the former /opt/lolly-ing/.env is not the current lolly.ing configuration. secure: false with port 587 takes STARTTLS when the relay offers it; use secure: true only for port 465.

3. Publish the DNS records the provider shows, in the domain's DNS. For lolly.ing that is Namecheap, Domain List > Manage > Advanced DNS, zone lolly.ing:

No MX record is needed to send from no-reply@.

4. Check. Wait until the provider shows the domain as verified. Then approve a request to join from a spare address, or invite one, and read the delivered mail's headers: they should show spf=pass, dkim=pass and dmarc=pass.

Keep using Copy invite message after email is on: a message sent from your own account is the one a new person is most likely to trust.

siem

Audit events pushed to the org's own receiver in signed batches (plans/35). url absent (the default) means off. Loss-free by construction: the audit log is the outbox, a durable cursor records the highest seq the receiver confirmed, and a refused batch replays whole. Long-lived server only - on a serverless deploy, poll GET /api/v1/audit with a service token instead. Delivery lag is the lw_siem_lag gauge on /metrics.

Batches use lolly.audit-projection.v1 with privacy-filtered bodies, original source hash references and separate projection proofs. Qualify the receiver's adapter before rollout. Original rows and their retention policy remain unchanged; see account lifecycle operations.

catalogProviders

Server-side catalog connectors use network.providers for outbound requests. Initial destinations must resolve entirely to public addresses unless their exact origin appears in allowedPrivateOrigins. Private deployments list only reviewed origins, including the intended scheme and port; paths and wildcards are refused. Native connections use a checked DNS answer while retaining the original Host and TLS hostname. For internal HTTPS services, use the same read-only CA trust setup described for other service connections.

Cross-origin redirects require redirectOrigins, and only GET/HEAD reads may follow them. Credential and custom headers are removed on a cross-origin hop. Every hop is checked again, with at most three redirects. Explicit error/manual redirect modes retain their stricter caller behavior. The default private and cross-origin redirect lists are empty. maxBytes defaults to 64 MiB per request and decoded response, and accepts 1 to 1 GiB; review the required media sizes before changing that limit. Requests have a 30-second budget. These controls apply to catalog federation, setup/consent checks, preview, hosted catalog bytes and publish requests. They do not define the identity provider or delivery destination policy.

Deploy-time (GitOps / air-gap) provider entries, upserted at boot as managedBy: 'config' and read-only in the API. Each entry: id (lowercase, dash-separated), kind, label, optional credentialRef (the name of the env var holding the secret), enabled, options, mapping, exposure, sync. Duplicate ids, unknown kinds and missing labels are startup errors. A provider's sync.maxAssets (a whole number) caps how many assets one sync federates from that provider. See catalog.

catalogServing

Sizing for catalogs with tens of thousands of assets. Every key has a working default.

See large catalogs.

mapping.hiddenTags lists labels this provider's assets never show: exact tags or prefixes ending in *, matched without regard to case. It is applied when the index is served, so a change takes effect at the next restart with no re-sync; the console's Tags panel shows these as set in instance.json. A database-managed provider takes the same list from the console instead (hiding tags).

Environment variables

Secrets

Optional media proofs come from the mounted publisher's verified catalog envelope. Original bytes must match its full SHA-256 digest before Work signs a caller-scoped resource map. Visible tool and asset entries and the verified, deterministically filtered preview bundle select that map. Hidden entries never enter its bundle or tool file map; guest tool metadata is limited to the shared tool while the public asset feed retains its normal visibility. /info/shots/ and fallback share cards can use exact verified bytes from the mounted instance.shellDir. Absent proofs, missing files or changed original bytes omit the optional resource and require the shell's safe preview fallback. Resource work is bounded to 4,096 referenced paths, 64 MiB per file and 256 MiB of checked bytes per view. A source pack without signed media proofs still supports tool rendering; qualify preview behavior with the paired shell release.

In development, LW_SESSION_SECRET and LW_LINK_SECRET fall back to ephemeral randoms, so sessions die on restart. In production (NODE_ENV=production) their absence throws.

Everything else

Changing configuration

Config is read at boot: edit and restart (Helm: update the ConfigMap and roll). Anything you want to change without a restart belongs in governance - grants, overlays, chains, feature flags, provider exposure - which is live-editable in the console and exportable as code. See governance.