Skip to main content
suchi demo seeds a fresh DATA_DIR from a versioned corpus manifest. It first applies the built-in Household filing tree; manifest category codes refer to that tree. SUCHI_DEMO_MODE=1 adds the runtime controls needed for a disposable public showcase. The mechanism ships in the main binary. Corpus and deployment artifacts are maintained separately in johnnybravo-xyz/suchi-demo.

​
Seed data

Useful flags: Exactly one of --corpus-url, --corpus-file, or --corpus-dir is required. Suchi never chooses or downloads a corpus release implicitly. The manifest’s integer schema_version is the only compatibility gate; its version identifies the content and may advance independently while the schema remains supported. The hosted image embeds its reviewed tarball and seeds only when its dedicated data directory has no database. Normal suchi serve startup never fetches content. All three sources are operator-selected trust boundaries. A URL uses its .sha256 sidecar when available and can also receive an explicit expected checksum, but remains accepted without either. A local archive or extracted directory is not authenticated by the CLI. Verify inputs independently and use HTTPS for remote sources. A checksum proves byte identity, not that a corpus is appropriate or harmless. Downloaded and local archives share a neutral corpus cache. Verified content reuses the cache only when its checksum marker matches; an unverified source is read or fetched again and replaces the prior cache every time. Local and remote corpus archives are limited to 256 MiB compressed, 1 GiB extracted, and 10,000 entries; remote checksum responses are limited to 4 KiB. Extraction rejects absolute and parent-traversal paths and does not materialize links. Manifest fixtures must name top-level regular files in fixtures/; paths cannot escape that directory, and directories or other non-regular files fail the seed. Fixtures may include curated exact-day dates in the manifest:
The seeder validates dates and inserts them with the document and processing job in one transaction. They use the existing fact table with status=accepted and extractor=demo-corpus; no model confidence or human review is invented. Evidence must come from the fixture. Reseeding preserves existing documents; updated fixtures take effect on a fresh demo volume at the next reset. Corpus v0.4.1 places three public multilingual examples at the front of the dashboard’s recent-document pile: a Japanese electricity bill, a Korean mobile bill, and a German electricity statement. The seeder preserves manifest order; because one seed run gives fixtures the same timestamp, the document list’s descending ID tie-breaker makes the manifest’s final fixtures appear first. A fixture can also replace an earlier fixture and name document links, both by filename:
A version must follow the fixture it replaces, and link targets must be other fixtures in the same manifest; otherwise the seed fails before writing. The two become one document with version history. Links are written after every fixture is stored, creating each named document-link field on first use. The seeder records each fixture’s filename as an import source, which is how these references resolve. A fixture whose original is kept can carry the number on its label:
Numbers must be positive and unique, and only the newest fixture in a version history may hold one, matching how a replacement takes over its predecessor’s number. The seed fails before writing otherwise. Visitors can then find the document with asn:4021. Factur-X, ZUGFeRD and XRechnung invoices need no manifest field. Post-ingest reads the embedded XML like any upload and fills the extraction-managed invoice_* custom fields.

​
Guided feature tour

The first dashboard visit in a browser redirects to the Demo guide once per session. Its first step runs a real rich query against the anonymized Northstar Cloud renewal cluster. The second step opens Calendar’s read-only examples across all months and years, each linked to its document. The third step searches the same cluster with version:all: the Workspace agreement lists the notice, quote and addendum that name it as Governing contract, and the revised quote keeps its earlier version. Public demo identities cannot use Ask your documents or invoke any model provider. The guide labels Ask your documents as available on private installations, not as a live demo action. It does not substitute a canned answer. A persistent help icon in the top-right returns to the guide after the visitor explores Search or another screen.

​
Runtime controls

Demo mode refuses to start alongside SUCHI_DEV=1 or OIDC. Use a dedicated DATA_DIR; demo credentials and retention rules are intentionally unsuitable for a normal archive.

​
Visitor sessions

POST /api/demo/session returns a signed anonymous token for read-only browsing. It requires no database write. The browser uses an HttpOnly cookie; JavaScript does not store a credential. Header-based read clients can still send the returned token as X-Suchi-Demo-Token. The first mutation receives demo_upgrade_required. The SPA calls POST /api/demo/session/upgrade, receives an HttpOnly session cookie for a scratch user, and retries the request. Concurrent writes share one upgrade. The same session authorizes preview/download links and survives a page reload. It expires at the configured scratch TTL; reload to begin a new visit after expiry. Signing out revokes the session and clears both demo cookies. Scratch users can upload and modify their own documents but cannot read another visitor’s uploads or mutate shared configuration and taxonomy. The seeded corpus remains read-only and visible to every visitor. These demo exceptions apply only to the unnamed original system 1. Demo seeding uses that internal default explicitly; anonymous and scratch principals cannot enter a named system, even if a document grant exists. Do not introduce prefixed taxonomies into a public showcase to broaden demo access. Calendar’s read exception is limited to accepted, curated demo-corpus date facts. Document visibility, Trash exclusion, and token read scopes still apply before counts and pagination. Pending/rejected facts, date extraction and review, and Ask your documents remain denied. No capabilities are granted to demo identities, and ordinary users still need archive_intelligence. Cookie-authenticated demo mutations use the same same-origin Fetch Metadata checks as ordinary browser sessions. A scratch cookie does not grant access to account administration, token management, or another visitor’s documents. Both session endpoints use a per-IP token bucket. The default is 5 requests per second with a burst of 10.

​
Shared-state guard

httpx.DemoReadOnly permits reads and document-scoped writes. It rejects mutations to shared surfaces including:
  • admin settings and setup state
  • taxonomy and automations
  • users, groups, ACLs, and tokens
  • folder layouts, mail settings, saved views, and share links
Rejected shared writes return 403 with code: "demo_read_only". Document handlers still enforce ownership, so the broader document route allowance does not let a scratch visitor change the corpus or another visitor’s upload.

​
Expiry and cleanup

Scratch users use the visitor-*@demo.local pattern. The reset ticker runs at half the configured TTL and deletes expired matching users, their documents, and cascading session/token records. It cannot select ordinary users or seeded demo rows; disabled visitors are retained for operator investigation. It never deletes CAS bytes: a reference check cannot account for an in-flight upload reusing a blob. Expiry removes access, not physical bytes. Reclaim disk space with the server and all archive writers stopped, using suchi gc, or through the deployment’s full volume reset. The sibling deployment’s nightly reset stops the server, recreates only its dedicated demo volume and lets the image entrypoint seed it again. Suchi does not expose a partial in-place reset that could leave corpus blobs or metadata behind.

​
Deployment boundaries

  • Put the instance behind TLS and an edge request-size limit.
  • Keep BACKUP_INTERVAL=0 unless demo state is intentionally retained.
  • Keep LLM, OIDC, mail intake, and other outbound integrations disabled.
  • Monitor session mint rates, disk use, and audit_events.
  • Treat visitor uploads as untrusted and disposable.
The main repository does not promise a hosted public instance. Availability, fixtures, automations, DNS, image version pairing, and reset operations belong to the separate demo project.