gezel Gezel Help

Local-first: your data stays on your disk

Gezel is built on one stubborn idea: your work belongs to you, on your machine, in files you can read.

What that means in practice

  • No gezel account. There is no sign-up and no gezel server holding your chats, and your conversations and files are never sent to us. When you use a cloud AI provider, the app talks directly from your computer to that provider.

  • Files all the way down. Your crew, their characters, their memories, your projects, your chat history — all ordinary files in one folder. Back it up, sync it, move it to a new machine, grep it. The Where files live article gives the map.

  • Local models keep your words local. Run a model on your own hardware and your prompts, and its answers, never leave the machine.

What does leave your machine

When you use a cloud provider, the text of your conversation (and any files Gezel reads for you in that conversation) goes to that provider to generate the response — the same as using their product directly, under their terms. You choose the provider; gezel adds no middleman of its own.

Gezel also uses the internet for a few ordinary jobs:

  • Downloads you start. Models you choose to install (usually from Hugging Face), the on-device engines that run them (from gezel's own releases on GitHub, checked against pinned fingerprints), and knowledge catalogs you add.

  • Tools it sets up. On first start gezel installs its browser-automation tools, fetching Playwright from npm and a Chromium browser through Playwright's own installer. Other tools you or Gezel add later also come from npm.

  • Updates. The desktop app checks gezel's GitHub releases for new versions; you can turn automatic checks off. Live catalog updates, if you switch them on, check npm about once a day.

  • Web search, when you allow it. Gezel can search and fetch web pages only once outside services are turned on in Settings → Security & compliance. What it searches for then goes to that search service: Wikipedia by default, or Brave if you add a Brave Search key.

Apart from web searches, none of these carry your conversations or files. The strictest level in Settings → Security & compliance also turns off update checks. What leaves this computer sets out every kind of traffic against each security level.

Credentials

Keys you give gezel for a provider are kept in your operating system's keychain — Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux — and sent only to that provider.

GitHub is the one service where gezel can use a sign-in you didn't give it directly. For GitHub work (cloning and syncing a linked repository, pull requests, GitHub connectors), gezel uses the GitHub token you saved in Settings. Without one, it uses a sign-in you already have: GH_TOKEN or GITHUB_TOKEN in its environment, or the GitHub CLI's (gh auth token). Engine downloads from GitHub are anonymous. They use a token only when you set GEZEL_GITHUB_TOKEN or GITHUB_TOKEN, to avoid GitHub's hourly limit, and never ask the GitHub CLI. Gezel asks the GitHub CLI only when that work comes up, never for a project with no GitHub link. The token goes only to GitHub, or to your linked repository's own GitHub server, and never to another git host. Gezel doesn't save it to disk or show it to a model. To stop this, sign out of the GitHub CLI, or save a token of your own in Settings for GitHub work. Where no keychain is available, such as on a headless server, gezel keeps them in an encrypted file inside its own folder, protected by your account's file permissions; in that case, keep the folder out of cloud sync. The background service on your machine answers only on this computer and asks for a pass that changes every time it starts, so other devices on your network can't reach it. That pass can't keep out programs already running under your account on this computer, or anyone with administrator rights: like you, they can open the files where it's kept. So be as careful about what you install as you would be anyway. The security model has the details.

Watch this article as a slideshow · Read it as markdown, for AI agents