> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# 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](https://tonbo.dev/docs/reference/nodejs/sql-functions.md#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](https://tonbo.dev/docs/platform/api-keys.md#open-by-name)). |
| `TONBO_API_ORIGIN` | The Management API’s origin when no [apiOrigin](https://tonbo.dev/docs/reference/nodejs/open.md#option-api-origin) is given. By default `https://api.tonbo.dev`. |
| `TONBO_AUTH_ORIGIN` | The token endpoint’s origin when no [authOrigin](https://tonbo.dev/docs/reference/nodejs/open.md#option-auth-origin) 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()](https://tonbo.dev/docs/reference/nodejs/sql-functions.md#load-ursula-vfs)). |

## 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](https://tonbo.dev/docs/databases/connect.md#token)). Through `/tonbo`, it serves the stream in place of the API key’s tokens (see [Tokens](https://tonbo.dev/docs/reference/nodejs/tokens.md#sources)). |
| `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](https://tonbo.dev/docs/databases/limits.md#transaction)). 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](https://tonbo.dev/docs/reference/nodejs/open.md#option-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.