Quartz Sandbox

The live Quartz sandbox is a working demonstration site where plugins, Markdown features, native page formats and layouts can be tried without changing the engine used by the other wikis on this host. This section is its documentation, not another sandbox deployment: the full migrated Quartz documentation lives at wiki.quartz.loca.zone, while the experiments themselves run at quartz.loca.zone. Start with quick-start-cheat-sheet for the everyday commands and authoring syntax.

What is running

The sandbox has a separate checkout of Quartz on branch v5, with package version 5.0.0, pinned to commit 3dff48b5df6d84c9544a5ae19c8f2cbb01dc44e5. Its recorded runtime is /usr/bin/node v22.23.1 and /usr/bin/npm 10.9.8. The showcase receipt records 21 parsed Markdown inputs, 47 emitted HTML files and 143 emitted files in /home/loca/dev/quartz-sandbox/sandbox/dist-1789511778; native Canvas and Bases pages, generated pages and a redirect are not extra Markdown inputs.

The sandbox configuration page explains the enabled features, and the plugin roster explains the installed components. Two local plugins belong only to this sandbox: the sandbox-reading-stats transformer and the sandbox-manifest emitter. Neither is approved for the shared engine. The public 44-entry route manifest is a published-content inventory, not an inventory of every output file and not a privacy boundary.

Why the two sites are isolated

The shared engine at /home/loca/dev/quartz/quartz powers 51 wikis. Its branch is v5 and its pinned baseline here is fd720a71db0ca16f885e75fe0d689a574960e3d9, not the sandbox pin. A sandbox build must never edit, install into or build through that shared checkout. These are the concrete boundaries of the supported sandbox build and serving path:

The wrapper resolves the engine’s real path and rejects any engine outside /home/loca/dev/quartz-sandbox, even if a commit-drift override is supplied. Its default engine is the isolated checkout above, and it checks the exact pin before taking the build lock. It runs install-plugins before the Quartz build, writes a new timestamped sandbox release, refuses publication without index.html, and atomically replaces only the sandbox current link. It retains the new timestamped release and two prior timestamped releases; the earlier dist-baseline is preserved. The ordinary sandbox command therefore never targets the shared engine or a wiki release.

The serving process is separate from the builder. It confines each request to both the selected release and the fixed sandbox base, accepts only GET and HEAD, and notices an atomic current swap on the next request without a restart. The deployed service runs as loca, with ProtectSystem=strict, ProtectHome=read-only, NoNewPrivileges=true, empty CapabilityBoundingSet and AmbientCapabilities, loopback-only networking and MemoryMax=512M. nginx sends this site’s requests to that origin; it does not turn sandbox configuration into shared wiki configuration.

These boundaries describe a specific build-and-serve path, not permission to run arbitrary code against other projects. If an experiment needs a change inside the shared engine, report a BLOCKER instead of making that change. The two pre-existing dirty shared-engine paths, quartz.config.yaml and quartz.ts, are operator-owned and must remain as found.

flowchart LR
  subgraph Shared["Shared wiki publishing — off limits to sandbox builds"]
    SE["Shared engine: /home/loca/dev/quartz/quartz"]
    WV["51 wiki vaults and their per-wiki releases"]
    WN["nginx: wiki virtual hosts"]
    WD["wiki.quartz.loca.zone: documentation"]
    SE --> WV --> WN --> WD
  end
  subgraph Isolated["Isolated sandbox — separate checkout and output"]
    SV["sandbox/vault: experiment content"]
    SP["sandbox/plugins: local plugins"]
    EN["sandbox/engine: Quartz 5.0.0 at 3dff48b5"]
    EC["Own node_modules, config and custom.scss"]
    DIST["sandbox/dist-epoch and sandbox/current"]
    SERVICE["quartz-sandbox.service: 127.0.0.1:51947"]
    NG["nginx: quartz.loca.zone"]
    SV --> EN
    SP --> EN
    EC --> EN
    EN --> DIST --> SERVICE --> NG
  end

Experiments and safety assessments

There are 14 classified experiments in sandbox-experiments.json: nine marked true and five marked false. Every row below has a documentation page with a real source excerpt, the recorded rendered markers, its reason and the isolated rebuild procedure. Fixture pages are documented with the experiment that consumes them, not presented as additional classified experiments.

safe_for_shared_engine is the recorded compatibility assessment, not authorization. Even true does not authorize changing the shared engine; a requirement to do so is a BLOCKER to report, not an action. false means the receipt explicitly identifies a shared-engine risk or an unreviewed dependency or privacy boundary.

Rebuild only the sandbox

After an authorized change to the isolated sources, the sandbox’s build-and-publish command is:

cd /home/loca/dev/quartz-sandbox/sandbox && ./build.sh

This command includes publication of the new sandbox release. It is not a preview-only build, and the service does not need a restart. Do not bypass the wrapper to write directly into current, install plugins into the shared checkout, or use the wiki publishing command to build a sandbox experiment. Publishing these documentation pages is a separate operation owned by the wiki publisher.

The recorded origin invocation below explains the runtime contract; it is reference only, not a command to launch beside the already-running service:

PATH=/usr/bin:/bin PORT=51947 SANDBOX_ROOT=/home/loca/dev/quartz-sandbox/sandbox/current NODE_ENV=production /usr/bin/node /home/loca/dev/quartz-sandbox/sandbox/serve.mjs

Evidence and limits

The experiment and plugin facts come from sandbox-experiments.json and sandbox-plugin.json under /home/loca/dev/quartz-sandbox/evidence/2026-09-15-quartz-migration-f1fd35c3/, paired with the live links above. Their final showcase release is dist-1789511778. sandbox-runtime.json records the earlier manual origin and guard checks against dist-baseline; its unit_installed: false and stopped manual process describe that earlier stage, not the subsequently deployed quartz-sandbox.service.

Rendered markers prove specific DOM output, not every interaction. Search controls do not prove a search query succeeded; fold, clipboard and graph controls do not prove a keyboard, clipboard or dragging workflow. The Mermaid page preserves both the earlier zero-SVG capture and the independently checked live browser result. The visibility page distinguishes public discovery suppression from encryption and access control. The alias page distinguishes an intentional redirect stub from canonical content.

Return to quick-start-cheat-sheet for the short operational guide.