Grist Desktop puts a self-contained Grist spreadsheet on your laptop with no account

What the Electron build is for

Grist Desktop is an Electron build of Grist, and the README is direct about its purpose: use it to easily open and edit Grist spreadsheets on your computer. It does not need the internet, and it will work fine on a desert island, assuming you can find a power outlet. It is not tied to any online account or service.

Those three properties are the product. A Grist spreadsheet is normally a document on a hosted service, and the claim here is that the file itself is complete. The README makes that argument explicitly, saying this is the quickest way to demonstrate to the skeptical that a Grist spreadsheet on a hosted service really is fully self-contained, and that you could download it and work with it on your own hardware if you needed to.

The listed uses are the practical ones. Editing splits for ML training runs, analyzing some CSV or JSON data, and preparing some structured lists for a batch job.

The README is equally clear about what this is not for. For hosting Grist spreadsheets on a server for use by a team, better options are grist-core and grist-omnibus.

So the scope is deliberately narrow, a single-user local editor, and everything else in the repository serves that. The project is TypeScript with an Apache-2.0 licence, the current version is 0.3.16, and the last push was on 2026-10-13. Releases include v0.3.16 from 2026-09-29, v0.3.15 from 2026-09-11 and v0.3.14 from 2026-08-04.

The build sequence

Building from source needs an environment with bash, git and yarn, and the sequence is short.

git submodule init
git submodule update
yarn install
yarn run setup
yarn run build
yarn run electron:preview
yarn run electron

The two submodule commands are separate rather than a recursive clone, which matches how the repository has evolved. Then yarn install pulls the JavaScript dependencies, yarn run setup runs the setup script and installs the Python side inside the core workspace, and yarn run build produces the production build and resolves the TypeScript path mappings with resolve-tspaths.

The last two commands are for looking at your work. electron:preview runs the built main process directly with electron and the trace-warnings flag, so you get warning output without going through the packaging step, and electron runs electron-builder with publish never so you get a local build rather than a release.

The package.json shows the full set of build targets, which is where the platform support is visible. There are electron:dir for a linux directory build, electron:linux, electron:linux:appimage for the AppImage format, and electron:ci which runs the CI script. The tests are split too, with the smoke test script and the electron test runner, and the electron runner has upstream and deployment variants for testing against a real Grist server rather than the bundled one.

The workspaces configuration lists core and ext as the two packages, with a nohoist list for eslint and a few other dependencies, which is the usual Yarn arrangement for a repository that vendors an upstream project alongside its own code.

The authentication modes and why GRIST_HOST is discouraged

The environment variables are documented in full, and the two that decide the security posture are the interesting ones.

GRIST_DESKTOP_AUTH sets the authentication mode and must be one of strict, mixed or none. None allows network access as you, mixed allows anonymous network access, and strict disallows network access. It was previously called GRIST_ELECTRON_AUTH, which is still supported but deprecated, and when both are set GRIST_DESKTOP_AUTH has higher precedence.

The default is strict, which is the right default for a local app, and the three modes exist because the same binary can be run as a LAN server, which the README's screenshots show being done on Windows 10 Pro.

That last case is why GRIST_HOST and GRIST_PORT carry the advice that they are not recommended to set. GRIST_HOST is the IP address to serve from and defaults to localhost, and GRIST_PORT is the port to listen on, where the desktop build will randomly pick an available port by default. A random port is a good default for a single-user app, since it avoids conflicting with anything else on the machine.

The other settings are the user identity and the update behaviour. GRIST_DEFAULT_USERNAME and GRIST_DEFAULT_EMAIL apply only when the database is initialised during the first launch, and changing them afterwards means manually resetting the database, re-initialising it and importing your documents back. GRIST_DESKTOP_USE_UPDATE toggles the auto-update functionality and defaults to true.

For developers the README says to create a .env file in the app root, while end users are pointed at the config file instead.

The sandbox, and the Flatpak workaround

GRIST_SANDBOX_FLAVOR selects the sandbox mechanism, and the possible values are pyodide, gvisor, macSandboxExec and unsandboxed. The default is pyodide, and the README recommends sticking to the default.

That setting is what lets Grist run formula code without executing it directly on your machine, and it is the mechanism that makes an offline desktop build viable at all.

The Flatpak section explains a problem worth understanding. Grist needs two additional environment variables set to run with Python sandboxed inside a Flatpak, or GRIST_SANDBOX_FLAVOR=unsandboxed, which is not recommended. The variables are GRIST_SANDBOX pointing at /app/bin/grist-desktop and GRIST_SANDBOX_APPEND_ARGS set to --type=unimportant.

The reason is a workaround for a Flatpak electron-builder issue that prevents Grist spawning workers when using the Pyodide sandbox. Electron-builder uses the Zypak sandbox wrapper, which causes errors when Grist tries to spawn itself via the same inode. The --type=X argument causes Zypak to skip the inode check, allowing Grist to fork a new Pyodide sandbox process.

The Flatpak build itself needs Flatpak, Flatpak Builder and Electron Builder, plus librsvg2-bin for icon generation on Debian or Ubuntu, and the prepare step is a single script.

./scripts/prepare-flatpak.sh

That script generates the icons and ensures all the flatpak runtimes are installed, and the flatpak is then built with the normal build process.

The Windows symlink problem

There is a note for Windows users on importing documents, and it is a genuine limitation rather than a configuration tip.

Grist Desktop relies on symlinks to manage imported Grist documents. This feature will not work correctly on Windows by default, because of a Windows security policy where non-admin users must obtain a specific permission to create symlinks. Microsoft suggests granting this permission only to trusted users, as it could expose security vulnerabilities if used improperly.

The fix is to use the Group Policy Editor, gpedit.msc, to enable the permission for your Windows user, and the README confirms that Grist Desktop 0.2.10 has been verified to work with the permission granted. If you are unwilling to grant it, the README says to stay tuned as they work on a new solution that does not involve symlinks.

That framing is worth noting. The current state is that the app works on Windows but with a documented security compromise, and the maintainers are working on removing the need for it.

The screenshots in the README cover the platforms the app runs on in practice, including an Intel Mac editing the Meme Generator template, a Wedding Planner spreadsheet on Ubuntu, a D&D Encounter Tracker on an ARM Mac M1, a Doggy Daycare spreadsheet on a super-low-resolution Windows 7 setup, and the app running as a server on a LAN on Windows 10 Pro.

Where Grist Desktop is the wrong choice

Four cases argue against it.

The first is a team. The README says it directly: for hosting Grist spreadsheets on a server for use by a team, better options are grist-core and grist-omnibus. A desktop app with a single default user and a strict-by-default authentication mode is not a multi-user server, and pretending otherwise means opening network access on your laptop.

The second is Windows without the symlink permission. Importing documents is the core workflow of the app, and if you cannot grant the permission, the README's own advice is to wait for a solution that does not involve symlinks.

The third is if you need the hosted feature set. Grist Desktop is the desktop build, and features that depend on a server, sharing, comments and permissions in the hosted sense, are not what this artifact provides.

The alternative in the same direction is the browser and grist-core, which is the hosted server you can run yourself. The difference in approach is that the Electron build bundles the whole thing into one executable you can put on a USB stick and open on a machine with no network, while grist-core gives you the full server with collaboration, and it needs a machine and a Python environment to run. For a single file on a laptop, the desktop build wins. For a team working on the same documents, grist-core or grist-omnibus is the only sensible answer.

Editorial conclusion

Grist Desktop fits a user who needs Grist spreadsheets on a machine with no internet, or who wants to prove that a Grist file is genuinely self-contained by opening it on their own hardware. It does not fit a team that needs a shared hosted spreadsheet, because the README points at grist-core and grist-omnibus for that, and it does not fit a Windows user who will not grant symlink creation permission. Download a build from the releases page, or build it with `yarn run setup` and `yarn run build`, and if you need formulas to run, read the sandbox section before changing `GRIST_SANDBOX_FLAVOR` away from pyodide.

Frequently asked questions

Official sources

1. gristlabs/grist-desktop on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases