Configuration reference

Every environment variable the server reads, with the default that applies when it is unset and what setting it changes. Defaults here are taken from the code that reads each variable.

Two processes read this environment and they are not the same process. The API (packages/api) reads PORT and FASTIFY_ADDRESS; the MCP runtime (packages/mcp-server), which mounts the API in-process, reads HTTP_PORT, HTTP_HOST and the MCP_* variables. The container starts one of them according to APP_MODE. The web app is a separate static build with its own NUXT_PUBLIC_* variables, listed at the end.

For the reasoning behind these choices rather than their values, see running and configuring and deploying.

Server and transport

Library storage

The library — every entity you author — lives in a store chosen by INTERNAL_BACKEND_TYPE. This is separate from the backends your queries run against, which are entities you create through the API.

What oxigraph-persistent actually does

The Oxigraph JavaScript/WebAssembly bindings support in-memory stores only. There is no RocksDB-backed store as there is in the Rust and Python bindings. oxigraph-persistent is an in-memory store that is serialised to .nq files in LIBRARY_STORAGE_DIR on shutdown and every INTERNAL_OXIGRAPH_CHECKPOINT_INTERVAL_MS milliseconds, and restored from those files at startup. A process killed between checkpoints loses the writes made since the last one. oxigraph-memory keeps nothing.

For a store that is durable in the usual sense, use the default sqlite, or run a SPARQL server such as Oxigraph's own or Fuseki alongside and use INTERNAL_BACKEND_TYPE=http.

INTERNAL_OXIGRAPH_DB_PATH is no longer read. It named a RocksDB directory that these bindings cannot open; serialisation goes to LIBRARY_STORAGE_DIR.

See storage and caching for how the store and the in-memory cache relate.

Execution backend credentials

A Backend entity does not store credentials. It stores an authEnvKey, and the server looks up the credentials in the environment under that key. This keeps secrets out of the library store, which is exported, imported and copied.

authEnvKey must match ^[A-Z0-9_]+$. For a backend whose authEnvKey is <KEY>, the server reads, in this order:

<KEY> is the entity's authEnvKey upper-cased. A backend with authEnvKey: "qms_fuseki_dev" reads SQLIB_BACKEND_QMS_FUSEKI_DEV_USERNAME and SQLIB_BACKEND_QMS_FUSEKI_DEV_PASSWORD. A backend with no authEnvKey sends no credentials.

Caching

Entity time-to-live in the cache is not configurable by environment: it is set per entity type in packages/api/src/lib/EntityRegistry.ts, where immutable versions are held indefinitely. See storage and caching.

ETL

ETL is off by default; see feature flags and the ETL guide.

Kept results (pass-by-reference)

A run that sets keepResult has its response kept in server memory, and the response carries a Sqlib-Result-Ref handle. A later request names the handle (argumentRefs or dataGraphs[].resultRef on /execute, dataGraphResultRef on a rule set run) instead of sending the content again. Only responses the server produced are kept, and a handle is readable only by the subject that made the run. A missing, expired or foreign handle returns 410.

A restart empties the cache.

Entity size limits

A value that does not parse as an integer falls back to the default.

Rule execution and patches

Telemetry

OTLP export only happens when NODE_ENV=development. In any other environment the SDK starts with console exporters, which means an endpoint set in production is not used. Metrics are exported every 30 seconds.

Startup time

Relevant to a deployment that scales to zero, where a cold start sits in front of a user request rather than happening once a week.

Response-schema compilation is the largest single term in startup and it scales with the number of routes, not with the amount of data: on a 135-route instance it was ~890ms of a ~1.4s ready(), whether or not anything ever called those routes. Compiling each route's serialiser on its first response instead moves that off the boot path for ~2ms on that first response, which is why it is the default. SQLIB_EAGER_SERIALIZERS=true is the way back for a long-lived instance that would rather pay the whole bill before it accepts traffic.

Two other things help and are ordinary configuration rather than switches: turning off feature flags you do not serve removes their routes, and each route is worth roughly 10ms of startup; and OTEL_ENABLED=false avoids loading the OpenTelemetry SDK.

What does not help much is anything about Oxigraph itself: the WASM module instantiates in about 25ms. The data-dependent part of startup is the snapshot, which loads at roughly 180,000 quads per second, plus the cache preload — so a library of a few thousand entities is lost in the noise and one of a few hundred thousand quads is not. See what oxigraph-persistent actually does.

Read-only deployments

SQLIB_READ_ONLY=true turns sqlib into a compute service: it still parses, validates, formats and executes, but it refuses every write to its own state. The catalogue changes by redeployment, and anything a visitor authors is kept in their browser instead. It is what a public demo site runs.

It is not an auth mode and does not need one. An auth mode answers "who is this, and what may they reach", which needs principals, grants and an issuer; this answers "may this deployment's own state change at all", which gives every caller the same answer. The two compose — a public site runs SQLIB_AUTH_MODE=disabled beside this, and the full-access context that mode mints still cannot write, because the gate consults no context.

The gate refuses every mutating method and then names its exceptions, so a route added later is refused until someone decides otherwise. A route that writes on a safe method declares it with config: { readOnlyMutating: true } in its route options, and is refused like an unlisted POST. The exceptions are the routes that compute an answer and store nothing: /detect-inputs, /detect-outputs, /validate, /validate-rule-data, /format, /substitute, /execute, /sparql, the SRL compile, analyse and preview routes, the rule and rule-set execution routes, the tuple-set preview, the two test-run routes, POST /etl-jobs/:id/execute, POST /benchmark-experiments/:id/versions/:version/run, and /mcp. The list lives in packages/api/src/config/readOnly.ts, and a test fails on an entry that names no registered route, on a mutating route that is neither listed nor refused, and on one of these exceptions losing its way back.

Four of those exceptions are worth their own sentence:

• Running a test is compute; its history is the write. POST /tests/run and POST /tests/:id/run answer with a verdict, and recordTestRuns files nothing on a read-only deployment, so no run history accumulates — the same line ?record=patch draws for SPARQL.
• Running a stored ETL job is compute; its record and its file are the write. On a read-only deployment POST /etl-jobs/:id/execute opens no EtlExecution and writes no output file, and returns the RDF in the response as output, up to ETL_RESPONSE_OUTPUT_MAX_BYTES. What runs is the job version's stored SQL; the request carries none. The run reads at most SQLIB_READ_ONLY_ETL_MAX_ROWS source rows, and when the request asked for more (or for no limit) the response says so in rowLimitApplied.
• Running a frozen benchmark version is compute; its runs and observations are the write. On a read-only deployment the run route accepts only a version that is already frozen (it does not freeze one), returns the run and its observations in the response, and stores none of them. A plan over the request cap is refused with 422, naming the cap; a second run while one is in flight gets 429 with Retry-After. The freeze route stays refused.

The caps on those runs, read only on a read-only deployment and reported by /health as readOnlyRunLimits:

• /mcp is all POST, so refusing it would take every tool, reads included, off a read-only deployment. Admitting it opens no write path: a tool call reaches its route through app.inject and meets the same hook there, so a mutation tool is refused at the inner route.

Three things it deliberately does not do:

• It does not refuse SPARQL against a registered backend. POST /sparql with a backendId passes through, UPDATEs included. A bare endpoint is refused with 405, for the reason /backends/probes is: a public server that fetches a URL the caller chose is a request forgery primitive. Which SPARQL a visitor may run is a grant, not this flag: SQLIB_AUTH_MODE=anonymous with query:saved on a backend admits the seeded queries and nothing typed. Whether a store accepts a write is the store's answer: sqlib's own read-only backends refuse through ReadOnlySparqlExecutor, and an endpoint somebody else owns refuses, or does not, on its own terms. What it does refuse is ?record=patch, on GET and POST alike, because recording a patch writes sqlib's state. (GET /sparql refuses an UPDATE with 405 on every deployment, read-only or not: a GET must not change anything.)
• It does not enable anything. FEATURE_ETL, FEATURE_PLAYGROUND_ETL and FEATURE_ASSISTANT are still off by default, and the ETL routes that take SQL in the request — POST /etl-jobs/preview and POST /playground/etl/execute — are absent from the exceptions above, as is every route that would store a job version. Turning a flag on is not enough to let a visitor's own SQL run on a read-only deployment.
• It does not authenticate. Every visitor is the same anonymous caller.

/health reports it as readOnly, beside the auth mode, so the SPA can offer browser-local authoring rather than a button the server will refuse.

The SPA draws no control whose only outcome is a refusal. Save and the entity ⋮ go from every work area, the benchmark and test chips go from the run bar, Save to Tuples, Save to Data and Save as test go from a rule set's Inputs tab, and the tag controls go from the Details panel — absent rather than disabled, the rule the rail already follows for a switched-off section. Everything acting on the browser's own copy stays: scratch queries, rule sets and argument sets, the values in them, Discard, and the inline data a rule set runs against. A parameterised query is authored and run the same way it is on a writable deployment, with the values sent inline to POST /sparql.

A visitor's own SPARQL endpoint is registered the same way. The backend picker in the run sentence takes a URL pasted straight into it — + SPARQL endpoint… at the foot of the menu — and keeps it as a browser backend: stored in that browser, named after its own URL, and never posted to the server. Renaming one, or changing its query method, is done under Backends like any other, and writes to the browser rather than to the server. Queries against it run from the browser to the endpoint, so the address, any headers and the results do not pass through sqlib. Browser backends are not a read-only feature — they work on any deployment — but they are what makes a read-only one usable against data it was not seeded with.

Before /health answers, and if it cannot be reached, the SPA assumes it may write. That direction is deliberate: a client that wrongly believes it may write shows a button and surfaces the server's refusal, while one that wrongly believes it may not hides a working feature and looks broken.

Authentication

Auth is off unless SQLIB_AUTH_MODE says otherwise. An invalid value for any of these throws at startup rather than falling back. See the security model for what the layer does and does not cover.

The API serves OAuth 2.0 Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource, at every path-suffixed form of it (/.well-known/oauth-protected-resource/mcp), and, under APP_BASE_PATH, at <base path>/.well-known/oauth-protected-resource too. The document lists the configured issuers as authorization_servers. It is public in every mode, and answers 404 when no issuer is configured. Every 401 carries WWW-Authenticate: Bearer resource_metadata="…", which is how an MCP client finds the authorization server with no client configuration.

Environments

Feature flags

Seventeen FEATURE_* variables switch sections of the product on and off, and the API unregisters the routes behind some of them. They have their own page: feature flags, which lists each key, its variable, its default and what disappears when it is off.

Development and seeding

These are read by development recipes and seeders, not by a normal deployment.

The web application

packages/web is a Nuxt SPA built ahead of time (ssr: false), so these are read at build time and baked into the bundle.

The three build-stamp variables exist for builds that cannot work the values out for themselves: an image built from a source copy with no .git directory finds no commit, and one built outside the repo finds no manifest. Pass what the build system knows.

A deployed static build can be re-pointed without rebuilding by serving a /config.json beside it. The client plugin packages/web/src/plugins/runtime-config.client.ts fetches it at startup and overrides apiBaseUrl, the four auth* values and any subset of featureFlags. A missing file, a non-JSON response or a parse failure logs a warning and leaves the build-time values in place. See deploying.