Environment variables

Last updated 29 October 2026

The environment variables the package and its extension read.

An empty value counts as unset. Set them before the process starts: the extension reads each of its settings once, at its first use, and the variables of an open by name at each one.

Opening by name

The /tonbo entry points read these at each open by name and each resolveDatabase(), since 0.11.1; since 0.11.2, the extension’s tonbo_resolve reads them for the entry, as it does for any host (see SQL functions).

Variable	What it does
`TONBO_API_KEY`	The Tonbo API key when no `apiKey` option is given, before the login file (see Opening by name).
`TONBO_API_ORIGIN`	The Management API’s origin when no apiOrigin is given. By default `https://api.tonbo.dev`.
`TONBO_AUTH_ORIGIN`	The token endpoint’s origin when no authOrigin is given. By default `https://tonbo.dev`.
`XDG_CONFIG_HOME`	Where the login `tonbo login` saved is found: `$XDG_CONFIG_HOME/tonbo/credentials.json`, else `$HOME/.config/tonbo/credentials.json`.

The package

Variable	What it does
`SQLITE_URSULA_VFS`	The path of the extension library to load instead of the prebuilt one, for a platform without one (see loadUrsulaVfs()).

The extension

Variable	What it does
`URSULA_VFS_TOKEN_FILE`	A file holding the bearer token, read while no open of the process has set one, again when the file changes, and after a token was refused (see The token file). Through `/tonbo`, it serves the stream in place of the API key’s tokens (see Tokens).
`URSULA_VFS_CA_FILE`	A PEM bundle of the certificate authorities trusted for `https://` stream URLs, in place of the bundled Mozilla roots, and since 0.11.2 for the name lookup and the API key’s token exchanges too, which go out from the extension. `NODE_EXTRA_CA_CERTS` does not apply to any of them.
`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY`	The proxy the extension’s requests go through, and since 0.11.2 the name lookup and the token exchanges with them.
`URSULA_VFS_MAX_COMMIT_BYTES`	The most bytes of pages one commit may hold: 128 MiB by default, at most 1 GiB, at least 4096 (see Limits). A value out of range is clamped, and one that is not a number keeps the default.
`URSULA_VFS_MAX_REQUEST_BYTES`	A request limit below the server’s, for a proxy in front of it that refuses larger bodies. By default the server’s alone.
`URSULA_VFS_IDLE_MS`	How long a connection to the server is kept after its last request, for the next one to reuse: 90000 by default; 0 never reuses one.
`URSULA_VFS_MIN_UPLOAD_KBPS`	The slowest upload, in KiB/s, a request’s time limit allows for: 256 by default, at least 1. A body of `n` bytes may take 5 seconds plus `n` divided by the rate.
`XDG_CACHE_HOME`	The user cache of the default cache root, `$XDG_CACHE_HOME/sqlite-ursula/0.8`; else `~/.cache` on Linux and `~/Library/Caches` on macOS (see dir).

A value the extension cannot use is logged once on stderr as setting_adjusted, with the value it used instead. The variables URSULA_VFS_ABORT_AT, URSULA_VFS_PANIC_IN, URSULA_VFS_FAIL_SYNC, URSULA_VFS_SNAPSHOT_DUE_BYTES, URSULA_VFS_SNAPSHOT_HOLD and URSULA_VFS_HOST_DIR are hooks for the extension’s own tests: leave them unset, since some of them kill the process on purpose.