@bendyline/gezel-service

gezeld, the Gezel service. A local HTTP service that owns chat sessions, routes to LLM providers, manages memories, tasks and projects, and reads and writes everything under ~/.gezel/.

This is what @bendyline/gezel-cli runs behind the scenes. Install it directly only if you are embedding Gezel or running the service standalone.

npm install @bendyline/gezel-service
npx -p @bendyline/gezel-service gezeld

gezeld runs in the foreground and is configured through environment variables (see Environment); npx -p @bendyline/gezel-service gezeld --help lists them. Always name the @bendyline/ package with npx: a bare npx gezeld outside the folder where you installed it asks npm for an unrelated package.

What it contains

• Hono HTTP API on loopback, bearer-token authenticated
• Store — the single read/write path for all on-disk state
• ChatManager — session lifecycle, persistence, provider-state resume
• Providers: Copilot, OpenAI, Anthropic, llama.cpp, MLX, ds4, and a deterministic mock for tests
• A per-session MCP bridge over stdio and streamable HTTP
• Memory (sqlite-vec), history, tasks, usage tracking, engine downloads
• The bundled web UI at dist/ui/, so gezel start --web serves a full browser interface from a Node-only install with nothing else to fetch

Entry points

import { startService } from '@bendyline/gezel-service';

const { port, clientToken, stop } = await startService({ home: '/tmp/gezel-home' });
console.log({ port, clientToken });
await stop();

Optional peers

The base npm install leaves out a few large or native pieces. Cloud providers, native engines, the HTTP API, MCP, UI, tasks, and file features work without them. Install each only when this deployment needs it:

npm install @huggingface/transformers@^4.3.1 kokoro-js@^1.2.1

npm consumers should also add two overrides to the application's root package.json (npm ignores overrides declared by dependencies). kokoro-js 1.2.1 still declares Transformers.js ^3.5.1; without the override npm installs a second, 3.x copy beside the service's 4.x one, and the service hands Kokoro tensors built from its own copy. adm-zip 0.6.1 is the first release that clears its advisory:

{
  "overrides": {
    "adm-zip": "0.6.1",
    "kokoro-js": { "@huggingface/transformers": "^4.3.1" }
  }
}

The desktop installers and the relocatable Node distribution already include this ML runtime with the reviewed overrides. Both paths use one Transformers 4.x / ONNX Runtime line rather than installing independent 3.x and 4.x stacks.

Native engines

On-device inference needs native engine binaries. They are not bundled — the service downloads them on first use from the native-v* releases in the Gezel repository, verifying the release's SHA256SUMS against a digest built into this package before trusting any individual archive hash. Set GEZEL_LLAMA_SERVER_BIN (and siblings) to point at your own builds instead, or GEZEL_NATIVE_BIN_DIR at a directory containing all of them.

Cloud providers need none of this.

Shared speech models

Speech-to-text (Whisper) and text-to-speech (Kokoro) weights come from a pinned catalog in @bendyline/gezel/speech-models, a Node-only module of the @bendyline/gezel package that other desktop apps can use too. Every file is pinned by revision, size, and SHA-256 and verified before use.

• Verified files are kept once per user, in <GEZEL_HOME>/engines/speech-assets/<sha256>. Each app keeps its own installation that hard links to those files (or copies them, without another download, when they are on a different volume), so two apps never download the same model twice, and removing one app's installation never breaks another's.
• Downloads and cleanup coordinate across processes; a cached file is deleted only when no installation still uses it.
• Lookup also finds models already present in Gezel's older model folders, in read-only model homes (GEZEL_READONLY_MODEL_HOMES), and in the desktop app's machine-wide assets folder. It never reads the machine service's private state.
• Nothing downloads on its own: a health check never fetches a model, and an older Kokoro export updates only when you pull the model again.
• An app that must keep its files to itself can give SpeechAssetStore a root of null, which turns sharing off.

Environment

Stability

Public API under semver. The HTTP API is versioned separately under /api; prefer @bendyline/gezel-client over calling it directly.

Documentation

• Repository and full documentation
• Notices and third-party licenses (also shipped in this package as dist/NOTICE.md)

MIT © Bendyline