gristlabs/grist-core

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/gristlabs/grist-core.svg?style=card)](https://bestofgithub.dev/repo/gristlabs/grist-core)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/gristlabs/grist-core.svg)](https://bestofgithub.dev/repo/gristlabs/grist-core)

Loading README…

Variable	Purpose
ALLOWED_WEBHOOK_DOMAINS	comma-separated list of permitted domains to use in webhooks (e.g. webhook.site,zapier.com). You can set this to `*` to allow all domains, but if doing so, we recommend using a carefully locked-down proxy (see `GRIST_PROXY_FOR_UNTRUSTED_URLS`) if you do not entirely trust users. Otherwise services on your internal network may become vulnerable to manipulation.
APP_DOC_URL	the url a browser should use to reach this doc worker. In a multi-server setup, if not using `GRIST_FLEET`, every doc worker must be reachable by the browser at a public url of its own. If not using `GRIST_ROUTER_URL` to assign those automatically, `APP_DOC_URL` needs setting in practice. Wherever it is set it must be distinct for each worker, since it is how a client reaches the worker holding a document, and, where `APP_DOC_INTERNAL_URL` is unset, how other servers reach it too. Behind a single front end that means a path per worker, such as `https://grist.example.com/dw/worker-1`. Setting it alongside `GRIST_FLEET` is refused at startup, since a fleet routes clients through whichever server they reach and never uses it.
APP_DOC_INTERNAL_URL	like `APP_DOC_URL` but used by other servers to reach this one using an internal domain name resolution (like in a docker environment). It only makes sense to define this value in the doc worker. Defaults to `APP_DOC_URL`. If both are unset, an address is derived from `GRIST_HOST`, or from the interface this server reaches Redis on. Workers that share a host can be told apart by path, and the id derived from this url includes it.
APP_HOME_URL	url prefix for home api (home and doc servers need this)
APP_HOME_INTERNAL_URL	like `APP_HOME_URL` but used by the home and the doc servers to reach any home workers using an internal domain name resolution (like in a docker environment). Defaults to `APP_HOME_URL`
APP_STATIC_URL	url prefix for static resources
APP_STATIC_INCLUDE_CUSTOM_CSS	set to "true" to include custom.css (from APP_STATIC_URL) in static pages
APP_UNTRUSTED_URL	URL at which to serve/expect plugin content.
GRIST_ACTION_HISTORY_MAX_ROWS	Maximum number of rows allowed in ActionHistory before pruning (up to a 1.25 grace factor). Defaults to 1000. ⚠️ A too low value may make the "Work on a copy" feature malfunction
GRIST_ACTION_HISTORY_MAX_BYTES	Maximum number of rows allowed in ActionHistory before pruning (up to a 1.25 grace factor). Defaults to 1Gb. ⚠️ A too low value may make the "Work on a copy" feature malfunction
GRIST_ADAPT_DOMAIN	set to "true" to support multiple base domains (careful, host header should be trustworthy)
GRIST_ALLOW_AUTOMATIC_VERSION_CHECKING	Whether Grist is allowed to automatically check if a newer Grist version is available. Defaults to "true" on the default `grist` and `grist-ee` Docker images. Defaults false in `grist-oss` and everywhere else.
GRIST_ALLOW_DEPRECATED_BARE_ORG_DELETE	If set, the deprecated DELETE /api/orgs/:orgId endpoint is available.
GRIST_APP_ROOT	directory containing Grist sandbox and assets (specifically the sandbox and static subdirectories).
GRIST_ATTACHMENTS_THRESHOLD_MB	attachment storage limit per document beyond which Grist will recommend external storage (if available). Defaults to 50MB.
GRIST_BACKUP_DELAY_SECS	wait this long after a doc change before making a backup
GRIST_BOOT_KEY	if set, use this key to sign in as the installation admin at `/boot`. New installs auto-generate one and print it on startup; set this only if you want a key of your own choosing.
GRIST_BROADCAST_TIMEOUT_MS	Set the maximum time a web client has to accept a broadcast message about a document before being disconnected (default: 1 minute).
GRIST_DATA_DIR	Directory in which to store documents. Defaults to `docs/` relative to the Grist application directory. In Grist's default Docker image, its default value is /persist/docs so that it will be used as a mounted volume.
GRIST_DEFAULT_EMAIL	if set, login as this user if no other credentials presented
GRIST_DEFAULT_PRODUCT	if set, this controls enabled features and limits of new sites. See names of PRODUCTS in Product.ts.
GRIST_DEFAULT_LOCALE	Locale to use as fallback when Grist cannot honour the browser locale. Defaults to `en-US`. Should match a locale code found in `app/common/LocaleCodes.ts`.
GRIST_DOC_WORKER_ID	identity of a doc worker, which must be distinct for every server sharing a Redis. Leave it unset to have one derived. Two servers sharing a value can open the same document at once.
GRIST_DOMAIN	in hosted Grist, Grist is served from subdomains of this domain. Defaults to "getgrist.com".
GRIST_EDITION	selects which edition the `yarn install` hook sets up, `full` or `community`. Takes precedence over the `grist-edition` file written by `yarn run set-full-edition` / `yarn run set-community-edition`. Defaults to `full`. See Building from source.
GRIST_SKIP_EXT_AUTOSETUP	set to `1` to skip the `yarn install` hook that downloads the full-edition `ext` material. Useful where extensions are installed by other means (Docker builds, grist-desktop, grist-static). See Building from source.
GRIST_EXPERIMENTAL_PLUGINS	enables experimental plugins
GRIST_EXTERNAL_ATTACHMENTS_MODE	required to enable external storage for attachments. Set to "snapshots" to enable external storage. Default value is "none". Note that when enabled, a snapshot storage has to be configured as well.
GRIST_ENABLE_SERVICE_ACCOUNTS	enables the `service accounts` feature. This feature allows users to create special service accounts that they can manage and to whom they can grant restricted access to chosen resources. Useful as a way to get fine-grained api keys for use with third party automations. Unset by default
GRIST_ENABLE_REQUEST_FUNCTION	enables the REQUEST function. This function performs HTTP requests in a similar way to `requests.request`. This function presents a significant security risk, since it can let users call internal endpoints when Grist is available publicly. This function can also cause performance issues. Unset by default.
GRIST_HEADERS_TIMEOUT_MS	if set, override nodes's server.headersTimeout flag.
GRIST_HIDE_UI_ELEMENTS	comma-separated list of UI features to disable. Allowed names of parts: `helpCenter`, `billing`, `templates`, `createSite`, `multiSite`, `multiAccounts`, `importFromAirtable`, `sendToDrive`, `tutorials`, `supportGrist`, `themes`, `automations`. If a part also exists in GRIST_UI_FEATURES, it will still be disabled.
GRIST_HOST	hostname to use when listening on a port. Also decides the address a doc worker publishes for its peers, and the identity derived from it: set it to `0.0.0.0` to listen on every interface, and leave it unset to listen only on `localhost`.
GRIST_PROXY_FOR_UNTRUSTED_URLS	Full URL of proxy for delivering webhook payloads. Default value is `direct` for delivering payloads without proxying.
HTTPS_PROXY or https_proxy	Full URL of reverse web proxy (corporate proxy) for fetching the custom widgets repository or the OIDC config from the issuer.
GRIST_ID_PREFIX	for subdomains of form o-, expect or produce o-${GRIST_ID_PREFIX}.
GRIST_IGNORE_SESSION	if set, Grist will not use a session for authentication.
GRIST_INCLUDE_CUSTOM_SCRIPT_URL	if set, will load the referenced URL in a `<script>` tag on all app pages.
GRIST_IN_SERVICE	if "true", skip the first-run Quick setup gate and put the server straight into service. New installs default to "false" so the operator can finish Quick setup; existing installs default to "true".
GRIST_INST_DIR	path to Grist instance configuration files, for Grist server.
GRIST_KEEP_ALIVE_TIMEOUT_MS	if set, override nodes's server.keepAliveTimeout flag.
GRIST_LIST_PUBLIC_SITES	if set to true, sites shared with the public will be listed for anonymous users. Defaults to false.
GRIST_MANAGED_WORKERS	if set, Grist can assume that if a url targeted at a doc worker returns a 404, that worker is gone
GRIST_MAX_NEW_USER_INVITES_PER_ORG	if set, limits the number of invites to new users per org. Once exceeded, additional invites are blocked until invited users log in for the first time or are uninvited
GRIST_MAX_BILLING_MANAGERS_PER_ORG	if set, limits the number of billing managers per org
GRIST_MAX_PARALLEL_REQUESTS_PER_DOC	max number of concurrent API requests allowed per document (default is 10, set to 0 for unlimited)
GRIST_MAX_UPLOAD_ATTACHMENT_MB	max allowed size for attachments (0 or empty for unlimited).
GRIST_MAX_UPLOAD_IMPORT_MB	max allowed size for imports (except .grist files) (0 or empty for unlimited).
GRIST_ACTIVEDOC_TIMEOUT_SECONDS	Number of seconds a document is kept open without any clients before it is closed. Defaults to 30s when NODE_ENV=production is set, otherwise to 5s.
GRIST_OFFER_ALL_LANGUAGES	if set, all translated langauages are offered to the user (by default, only languages with a special 'good enough' key set are offered to user).
GRIST_ORG_IN_PATH	if true, encode org in path rather than domain
GRIST_PAGE_TITLE_SUFFIX	a string to append to the end of the `<title>` in HTML documents. Defaults to `" - Grist"`. Set to `_blank` for no suffix at all.
~~GRIST_PROXY_AUTH_HEADER~~	Deprecated, and interpreted as a synonym for GRIST_FORWARD_AUTH_HEADER.
GRIST_REQUEST_TIMEOUT_MS	if set, override nodes's server.requestTimeout flag.
GRIST_RESTART_SHELL	set to "true"/"false" to enable/disable restarting in place to apply config changes without dropping the listening socket. On by default for Linux under Node, off for Windows and Electron.
GRIST_ROUTER_URL	optional url for an api that allows servers to be (un)registered with a load balancer
GRIST_SERVE_SAME_ORIGIN	set to "true" to access home server and doc workers on the same protocol-host-port as the top-level page, same as for custom domains (careful, host header should be trustworthy)
GRIST_SERVERS	the types of server to setup. Comma separated values which may contain "home", "docs", static" and/or "app". Defaults to "home,docs,static".
GRIST_SESSION_COOKIE	if set, overrides the name of Grist's cookie
GRIST_SESSION_DOMAIN	if set, associates the cookie with the given domain - otherwise defaults to GRIST_DOMAIN
GRIST_SESSION_SECRET	a key used to encode sessions
GRIST_SQLITE_MODE	if set to `wal`, use SQLite in WAL mode, if set to `sync`, use SQLite with SYNCHRONOUS=full, if set to `nosync` (the default), use SQLite with SYNCHRONOUS=off
GRIST_ANON_PLAYGROUND	When set to `false` deny anonymous users access to the home page (but documents can still be shared to anonymous users). Defaults to `true`, unless GRIST_ORG_CREATION_ANYONE is `false`.
GRIST_FORCE_LOGIN	Setting it to `true` is similar to setting `GRIST_ANON_PLAYGROUND: false` but it blocks any anonymous access (thus any document shared publicly actually requires the users to be authenticated before consulting them)
GRIST_PERSONAL_ORGS	When set to `false` prevent new personal orgs from being created when a user signs up. Defaults to `true`, unless GRIST_ORG_CREATION_ANYONE is `false`.
GRIST_ORG_CREATION_ANYONE	When set to `false`, prevent new team orgs from being created by non-admin users. Sets default values of `GRIST_ANON_PLAYGROUND` and `GRIST_PERSONAL_ORGS` to `false`. Defaults to `true`.
GRIST_SINGLE_ORG	set to an org "domain" to pin client to that org
GRIST_TEMPLATE_ORG	set to an org "domain" to show public docs from that org
GRIST_HELP_CENTER	set the help center link ref
GRIST_TERMS_OF_SERVICE_URL	if set, adds terms of service link
GRIST_CONTACT_SUPPORT_URL	set the link to contact support on error pages (example: email address or online form)
GRIST_ONBOARDING_VIDEO_ID	set the ID of the YouTube video shown on the homepage and during onboarding
GRIST_CUSTOM_COMMON_URLS	overwrite the default commons URLs. Its value is expected to be a JSON object and a subset of the ICommonUrls interface.
GRIST_SUPPORT_ANON	if set to 'true', show UI for anonymous access (not shown by default)
GRIST_SUPPORT_EMAIL	if set, give a user with the specified email support powers. The main extra power is the ability to share sites, workspaces, and docs with all users in a listed way.
GRIST_OPEN_GRAPH_PREVIEW_IMAGE	the URL of the preview image when sharing the link on websites like social medias or chat applications.
GRIST_TELEMETRY_LEVEL	the telemetry level. Can be set to: `off` (default), `limited`, or `full`.
GRIST_THROTTLE_CPU	if set, CPU throttling is enabled
GRIST_TRUST_PLUGINS	if set, plugins are expect to be served from the same host as the rest of the Grist app, rather than from a distinct host. Ordinarily, plugins are served from a distinct host so that the cookies used by the Grist app are not automatically available to them. Enable this only if you understand the security implications.
GRIST_USER_ROOT	an extra path to look for plugins in - Grist will scan for plugins in `$GRIST_USER_ROOT/plugins`.
GRIST_UI_FEATURES	comma-separated list of UI features to enable. Allowed names of parts: `helpCenter`, `billing`, `templates`, `createSite`, `multiSite`, `multiAccounts`, `importFromAirtable`, `sendToDrive`, `tutorials`, `supportGrist`, `themes`, `automations`. If a part also exists in GRIST_HIDE_UI_ELEMENTS, it won't be enabled. Note: `importFromAirtable` and `automations` are enabled by default even without being listed here; use GRIST_HIDE_UI_ELEMENTS to disable them.
GRIST_UNTRUSTED_PORT	if set, plugins will be served from the given port. This is an alternative to setting APP_UNTRUSTED_URL.
GRIST_VACUUM_ON_CLOSE	When set to `false`, do not compact documents when they are closed for inactivity. Documents are only compacted when there is enough space to reclaim to be worth the cost of storing the result. Defaults to `true`.
GRIST_WIDGET_LIST_URL	a url pointing to a widget manifest, by default https://github.com/gristlabs/grist-widget/releases/download/latest/manifest.json is used
GRIST_LOG_LEVEL	Minimum level of log messages to output: `error`, `warn`, `info` or `debug`. Defaults to `info`.
GRIST_LOG_HTTP	When set to `true`, log HTTP requests and responses information. Defaults to `false`.
GRIST_LOG_HTTP_BODY	When set to `true`, log request bodies with API errors. If `GRIST_LOG_HTTP` is also `true`, log request bodies with all HTTP requests. ⚠️ Be aware it may leak confidential information in the logs.⚠️ Defaults to `false`.
GRIST_LOG_AS_JSON	When this variable is set to `true` or a truthy value, output log lines in JSON as opposed to a plain text format.
GRIST_LOG_API_DETAILS	When this variable is set to `true` or a truthy value, log the API calls details.
COOKIE_MAX_AGE	session cookie max age, defaults to 90 days; can be set to "none" to make it a session cookie
HOME_PORT	port number to listen on for REST API server; if set to "share", add API endpoints to regular grist port.
PORT	port number to listen on for Grist server
REDIS_URL	optional redis server for browser sessions and db query caching
GRIST_SNAPSHOT_TIME_CAP	optional. Define the caps for tracking buckets. Usage: {"hour": 25, "day": 32, "isoWeek": 12, "month": 96, "year": 1000}
GRIST_SNAPSHOT_KEEP	optional. Number of recent snapshots to retain unconditionally for a document, regardless of when they were made
GRIST_PROMCLIENT_PORT	optional. If set, serve the Prometheus metrics on the specified port number. ⚠️ Be sure to use a port which is not publicly exposed ⚠️.
GRIST_ENABLE_SCIM	optional. If set, enable the SCIM API Endpoint (experimental)
GRIST_OIDC_...	optional. Environment variables used to configure OpenID authentification. See OpenID Connect documentation for full related list of environment variables. See also Logins.
GRIST_SAML_...	optional. Environment variables used to configure SAML authentification. See SAML documentation for full related list of environment variables. See also Logins.
GRIST_IDP_EXTRA_PROPS	optional. If set, defines which extra fields returned by your identity provider will be stored in the users table of the home database (in the `options.ssoExtraInfo` object). Usage: 'onekey,anotherkey'.
GRIST_FEATURE_FORM_FRAMING	optional. Configures a border around a rendered form that is added for security reasons; Can be set to: `border` or `minimal`. Defaults to `border`.
GRIST_TRUTHY_VALUES	optional. Comma-separated list of extra words that should be considered as truthy by the data engine beyond english defaults. Ex: "oui,ja,si"
GRIST_FALSY_VALUES	optional. Comma-separated list of extra words that should be considered as falsy by the data engine beyond english defaults. Ex: "non,nein,no"
GRIST_ENABLE_USER_PRESENCE	optional, enabled by default. If set to 'false', disables all user presence features.

Variable	Purpose
GRIST_ACTIVATION	an activation key for the full edition, supplied directly instead of through the Admin Panel. Useful for scripted or headless deploys. Takes precedence over `GRIST_ACTIVATION_FILE`.
GRIST_ACTIVATION_FILE	path to a file containing the activation key, read when `GRIST_ACTIVATION` is not set.
GRIST_MCP_ENABLED	if set to "true", enable the MCP server, so external clients such as Claude can talk to Grist over JSON-RPC. Defaults to "false".
GRIST_ENABLE_OIDC_SERVER	if set to "true", enable Grist's OAuth / OIDC server, which issues the tokens that OAuth apps and MCP clients authenticate with. Defaults to "false".
GRIST_ENABLE_OIDC_DCR	if set to "true", enable OAuth Dynamic Client Registration (RFC 7591): serve `POST /oidc/reg` and advertise it in the discovery document, so OAuth and MCP clients can register without being pre-provisioned. Defaults to "false".
GRIST_OIDC_DCR_RATE_LIMIT	requests per minute allowed on the unauthenticated `POST /oidc/reg` endpoint. Defaults to 60.
GRIST_OIDC_CIMD_ALLOWED_HOSTS	comma-separated allowlist of hosts whose Client ID Metadata Document (CIMD) may be fetched, letting a client identify itself by an HTTPS metadata URL instead of pre-registering. Empty (the default) disables CIMD. `*` allows any host and should only be used together with `GRIST_PROXY_FOR_UNTRUSTED_URLS`.

Variable	Purpose
ASSISTANT_API_KEY	optional. An API key to pass when making requests to an external AI conversational endpoint.
ASSISTANT_CHAT_COMPLETION_ENDPOINT	optional. A chat-completion style endpoint to call. Not needed if OpenAI is being used.
ASSISTANT_MODEL	optional. If set, this string is passed along in calls to the AI conversational endpoint.
ASSISTANT_LONGER_CONTEXT_MODEL	optional. If set, requests that fail because of a context length limitation will be retried with this model set.
OPENAI_API_KEY	optional. Synonym for ASSISTANT_API_KEY that assumes an OpenAI endpoint is being used. Sign up for an account on OpenAI and then generate a secret key here.

Variable	Purpose	Sandbox
GRIST_SANDBOX_FLAVOR	can be gvisor, pynbox, unsandboxed, docker, or macSandboxExec. If set, forces Grist to use the specified kind of sandbox.	N/A
GRIST_SANDBOX	a program or image name to run as the sandbox. See NSandbox.ts for nerdy details.	N/A
GVISOR_LIMIT_NPROC	the number of extant processes the sandbox is allowed to spawn when running on Linux. Defaults to 8.	GVisor
GVISOR_LIMIT_MEMORY	the maximum size of the sandboxed process's virtual memory (in bytes). No limit by default.	GVisor

Variable	Purpose
GRIST_FORWARD_AUTH_HEADER	if set, trust the specified header (e.g. "x-forwarded-user") to contain authorized user emails, and enable "forward auth" logins.
GRIST_FORWARD_AUTH_LOGIN_PATH	if GRIST_FORWARD_AUTH_HEADER is set, Grist will listen at this path for logins. Defaults to `/auth/login`.
GRIST_FORWARD_AUTH_LOGOUT_PATH	if GRIST_FORWARD_AUTH_HEADER is set, Grist will forward to this path when user logs out.

gristlabs/grist-core

Grist

Features in `grist-core`

Features not in `grist-core`

Using Grist

Using Grist with OpenRouter for Model Agnostic and Claude Support

Required: Set the endpoint to OpenRouter's API

Required: Your OpenRouter API key

Optional: Specify which model to use (examples below)

or other options like

Optional: Set a larger context model for fallback

Available Docker images

The Admin Panel

Building from source

Logins

Translations

Why free and open-source software?

Sponsors

Reviews

Environment variables

Full edition feature flags:

AI Formula Assistant related variables (all optional):

Sandbox related variables:

Forward authentication variables:

Plugins:

Google Drive integrations:

Database variables:

Docker-only variables:

Testing:

Tests

License

Variable	Purpose
GOOGLE_CLIENT_ID	set to the Google Client Id to be used with Google API client
GOOGLE_CLIENT_SECRET	set to the Google Client Secret to be used with Google API client
GOOGLE_API_KEY	set to the Google API Key to be used with Google API client (accessing public files)
GOOGLE_DRIVE_SCOPE	set to the scope requested for Google Drive integration (defaults to drive.file)

Variable	Purpose
TYPEORM_DATABASE	database filename for sqlite or database name for other db types
TYPEORM_HOST	host for db
TYPEORM_LOGGING	set to 'true' to see all sql queries
TYPEORM_PASSWORD	password to use
TYPEORM_PORT	port number for db if not the default for that db type
TYPEORM_TYPE	set to 'sqlite' or 'postgres'
TYPEORM_USERNAME	username to connect as
TYPEORM_EXTRA	any other properties to pass to TypeORM in JSON format

Variable	Purpose
GRIST_DOCKER_USER	optional. When the container runs as the root user, this is the user the Grist services run as. Overrides the default.
GRIST_DOCKER_GROUP	optional. When the container runs as the root user, this is the group the Grist services run as. Overrides the default.

Variable	Purpose
GRIST_TESTING_SOCKET	a socket used for out-of-channel communication during tests only.
GRIST_TEST_FORCE_LIGHT_MODE	if set, Grist will use light mode even if system preference is dark. Some tests just assume light mode.
GRIST_TEST_HTTPS_OFFSET	if set, adds https ports at the specified offset. This is useful in testing.
GRIST_TEST_SSL_CERT	if set, contains filename of SSL certificate.
GRIST_TEST_SSL_KEY	if set, contains filename of SSL private key.
GRIST_TEST_LOGIN	allow fake unauthenticated test logins (suitable for dev environment only).
GRIST_TEST_ROUTER	if set, then the home server will serve a mock version of router api at /test/router
GREP_TESTS	pattern for selecting specific tests to run (e.g. `env GREP_TESTS=ActionLog yarn test`).

Grist

Features in grist-core

Features not in grist-core

Using Grist

Using Grist with OpenRouter for Model Agnostic and Claude Support

Required: Set the endpoint to OpenRouter's API

Required: Your OpenRouter API key

Optional: Specify which model to use (examples below)

or other options like

Optional: Set a larger context model for fallback

Available Docker images

The Admin Panel

Building from source

Logins

Translations

Why free and open-source software?

Sponsors

Reviews

Environment variables

Full edition feature flags:

AI Formula Assistant related variables (all optional):

Sandbox related variables:

Forward authentication variables:

Plugins:

Google Drive integrations:

Database variables:

Docker-only variables:

Testing:

Tests

License

Features in `grist-core`

Features not in `grist-core`