Connected apps

Gezel isn't only a place you visit — it can also serve your models and gezellen to other programs on your computer. A code editor, a writing tool, or a browser extension that knows how to talk to an AI service can talk to gezel instead, and get your local models with all of gezel's know-how applied.

Everything described here lives in Settings → Connected Apps.

How an app connects

Apps speak to gezel using the same "OpenAI-style" language most AI tools already know. Two things make it work:

1. An address. The address panel in Settings → Connected Apps shows where gezel is listening on your machine. On most personal installs that is https://127.0.0.1:6228/v1; when the Gezel machine service is installed, the app API moves to a per-launch port (shown in the panel) because the machine service holds 6228. For apps that need an address that never changes, turn on Ollama emulation — it always answers at http://127.0.0.1:11434.

2. Permission. The first time an app asks for access, gezel shows you an approval request — who is asking, and for what. Nothing gets through until you approve, and you can revoke any app later from the same panel.

Codex and other agent harnesses

The authenticated address also serves the OpenAI Responses API at /v1/responses. That lets a harness such as Codex keep ownership of its coding tools, sandbox, approvals, and conversation loop while a model installed in gezel supplies the inference. VS Code, OpenCode, and pi connect the same way through the chat endpoint — see VS Code, OpenCode, and pi below.

For Codex, use Use Gezel in Codex in this Settings screen. Gezel creates an isolated gezel-local Codex profile, a model catalog, and a dedicated revocable credential. It does not edit Codex's main configuration, authentication, conversations, sandbox rules, or approval settings. Start Codex with the command shown on the card (codex --profile gezel-local).

If the card says Needs attention, the gezel-local profile on disk was hand-edited or was written by a different Gezel installation, so gezel will not touch it. Repair Codex setup writes a fresh profile pointed at this copy of gezel and keeps the old file beside it as gezel-local.config.toml.backup. The one conflict repair cannot resolve is another connected app holding the Codex credential identity — revoke that app first.

Keep Gezel running while Codex uses the local model. If you want the model bridge available without keeping the desktop window open, turn on Gezel's daemon autostart setting.

The managed profile talks to a narrow, authenticated loopback bridge. Operationally it provides the stable address that an Ollama-style integration needs, but it keeps bearer authentication: only the Responses and model-discovery routes are present, and the credential grants no access to Gezel projects, files, terminals, or settings. The token is read by Codex through a command-backed provider credential rather than copied into a project or shell profile. Revoking the Codex entry under Connected Apps immediately stops it from using the bridge.

One-click setup is available only when the desktop and the Gezel service are on the same computer. In remote-service mode the card stays read-only, because writing a profile on the service host would not configure Codex on the computer in front of you.

Codex custom providers use wire_api = "responses". The managed profile also sets the top-level web_search = "disabled": Codex otherwise advertises a provider-hosted search tool that a local inference server cannot truthfully execute. Do not combine the Gezel profile with Codex's --search flag, which explicitly turns that hosted tool back on. Ordinary Codex tools such as shell commands, patching, and helper-agent namespaces remain available because Codex executes those itself.

The setup card puts eligible gezels first. Choosing one gives Codex that gezel's character (about.md), effective local model, and tuning while Codex keeps its own tools, sandbox, approvals, and conversation loop. The profile stores the stable gezel id, so renaming the gezel does not break the connection. Raw installed models remain available in a separate fallback group for users who want inference without a gezel persona.

The gezel you choose on the card is the profile's default, not its only option: gezel writes a model catalog listing every eligible gezel and local model, so Codex's own model picker shows the whole crew and you can switch between them inside a Codex session.

A gezel appears here only when its effective local model is installed and can participate in Codex's caller-executed tool loop. The facade does not attach Gezel chat sessions, memories, project context, or MCP tools, and it does not silently route unknown aliases through the fallback gezel. It also refuses codex-cli: / anthropic-cli: targets because those are full nested agent harnesses rather than inference providers.

VS Code

Use Gezel in VS Code uses VS Code's built-in custom-endpoint support, so it does not install or require the Gezel VSIX. Gezel adds one provider named Gezel to the selected VS Code profile's chatLanguageModels.json. Every eligible gezel and raw local model then appears in VS Code's native model picker while VS Code keeps control of its agent tools, permissions, and conversations.

This is a shared profile file, so setup uses a narrow merge: entries belonging to other providers are preserved, and Remove setup removes only Gezel's entry. Named VS Code profiles have separate files; choose the profile you want before setup. To move the integration later, clear it and set up the other profile.

There is one important tradeoff. Without an extension, VS Code cannot give Gezel access to its encrypted extension secret store. The dedicated VS Code credential is therefore written as plain text in chatLanguageModels.json. Gezel limits the effect of that exposure: the credential has inference-only scope, talks to a VS Code-only listener on 127.0.0.1, reaches only chat completions and model discovery, and is individually revocable. It cannot read Gezel projects, files, terminals, chats, or settings. The profile file is written with private file permissions where the operating system supports them.

The listener's port stays stable even though the ordinary Gezel daemon port can rotate. Keep Gezel running while VS Code uses the models; daemon autostart makes that available without keeping the desktop window open. Gezel periodically reconciles the provider entry, so installing or removing a model, changing a gezel, or changing an effective context limit updates VS Code's model picker automatically.

If the card says Needs attention, Gezel could not prove it owns the existing provider entry or could not safely parse the shared file. Repair VS Code setup first saves the complete existing file beside it as chatLanguageModels.json.backup, then replaces the conflicting Gezel entry. Other parseable provider entries remain in place. If the entire file is damaged, the backup is the recoverable original and the repaired file contains only the working Gezel provider.

OpenCode

OpenCode connects the same way, through Use Gezel in OpenCode in this Settings screen. Gezel writes its own settings file, a model list covering your eligible crew, and a dedicated revocable credential. It never edits your own OpenCode configuration, sessions, or permissions — instead it hands you a command that points OpenCode at the Gezel-owned file for that run:

OPENCODE_CONFIG=<path shown on the card> opencode

On Windows the card shows the PowerShell form of the same command. OpenCode merges configuration files rather than replacing them, so your own settings still apply; Gezel only adds a provider named gezel.

The gezel you choose is the one OpenCode starts with. Every eligible gezel and local model is listed in the file, so OpenCode's own model picker shows the whole crew and you can switch inside a session. Gezel also pins OpenCode's small model — the one it uses for titles and summaries — to the same choice, so a machine set up for local inference never quietly reaches for a cloud provider you have not configured.

Without the command

Add to OpenCode writes one further file — gezel.js, in OpenCode's own plugins folder — and from then on the gezel provider is in every OpenCode session on that computer, no command needed. This is the one file Gezel places outside its own home, so it is worth being precise about what it is: a file Gezel adds and owns, never an edit to a file of yours. It holds no password. It reads Gezel's settings and credential when OpenCode starts, and does nothing at all when Gezel is not running or not set up — an unrelated OpenCode session is never affected either way. opencode --pure starts without it, and without any other plugin.

It deliberately does not change which model OpenCode starts with: that stays your choice in OpenCode's own model picker, because this file loads in every project. To check it took effect, run opencode models — the crew appears under gezel/.

Remove from OpenCode deletes it, and removing the whole setup deletes it too. If a gezel.js written by a different Gezel installation — or edited by hand — is already there, Gezel says so and leaves it exactly as it is; Replace OpenCode plugin keeps the old one beside it as gezel.js.backup.

If the card says Needs attention, the managed file was hand-edited or was written by a different Gezel installation, so gezel will not touch it. Repair OpenCode setup writes a fresh file and keeps the old one beside it as opencode.json.backup. The one conflict repair cannot resolve is another connected app holding the OpenCode credential identity — revoke that app first.

Because the credential lives in its own file and the config references it by path, revoking the OpenCode entry under Connected Apps immediately stops it from using the bridge, and no secret is ever copied into a project or shell profile.

As with Codex, a gezel appears here only when its effective local model is installed and can take part in a caller-executed tool loop, one-click setup needs the desktop and the Gezel service on the same computer, and Gezel must stay running while OpenCode uses the model. The bridge carries only inference: the credential grants no access to Gezel projects, files, terminals, or settings.

pi

pi is a coding agent that keeps its own tools, permissions, and conversation loop, and lets a provider supply the model. Gezel writes a small extension of its own — plus the model list that extension reads — and hands you a command that loads it for that run:

pi -e <path shown on the card>

Both files live in Gezel's own folder, so this mode writes nothing into pi at all. pi merges what an extension registers with your own configuration; Gezel only adds a provider named gezel, and never touches your models.json, settings, or sessions.

Without the command

Add to pi copies that same extension into pi's own extensions folder, and from then on the gezel provider is in every pi session on that computer. It is a file Gezel adds and owns, never an edit to a file of yours. It holds no password: it reads Gezel's model list and credential when pi starts, and quietly does nothing when Gezel is not running. pi -ne starts without it, and without any other extension.

To check it took effect, run pi --list-models — the crew appears under gezel/. Remove from pi deletes it, and removing the whole setup deletes it too. If a gezel.js written by a different Gezel installation — or edited by hand — is already there, Gezel says so and leaves it alone; Replace pi extension keeps the old one beside it as gezel.js.backup.

Unlike the Codex profile, nothing here pins pi's own default model. The extension loads in every project, so which model pi starts with stays your choice in its model picker. If you point pi somewhere else with PI_CODING_AGENT_DIR in your shell, note that the gezel service cannot see a variable set only in your login shell — the card shows the folder it actually resolved.

As with the others, a gezel appears here only when its effective local model is installed and can take part in a caller-executed tool loop, one-click setup needs the desktop and the Gezel service on the same computer, and Gezel must stay running while pi uses the model.

Who answers: gezel choices and the fallback

Gezel presents your crew to connected apps as model choices, including each gezel's name and role. When an app chooses one, that gezel answers with their character, model, and settings.

Some apps cannot choose from that list and ask for a hardcoded model such as gpt-4o. The fallback gezel answers those requests. It defaults to your Meester, so there is always a useful front door; you can choose another gezel from Settings → Connected Apps.

Supporting behaviors

Gezel knows how to get the best out of each model — catching runaway rambling, tidying leaked reasoning, applying model-specific fixes. The Supporting behaviors switch controls whether connected apps get that help too. On (the default) is recommended; off gives plain serving with just the model's tuned settings.

Emulating Ollama

Some tools don't ask where your AI lives — they simply look for Ollama on its standard port. The Emulate Ollama switch makes gezel answer there, so those tools discover your crew with zero setup.

One honest caveat, spelled out next to the switch: Ollama's convention is no password. While emulation is on, any program on this computer can use your models without asking first. Gezel keeps this off unless you turn it on, only ever answers your own machine, and refuses to take the port if the real Ollama is already running.

Keeping an eye on things

Every chat an app completes through these endpoints is recorded in the History tab (look for "App chat" entries), and the tokens they consume count in the Usage view — so you can always see who has been using your models, and how much.

If you are developing one of these applications, continue with the technical guide Building connected apps with gezel-app-sdk.