Emacs with Verdictan

Register your Verdictan gateway as a gptel backend, and the prompts you send with it go through your policies. gptel sends OpenAI-style Chat Completions requests to the gateway. Get one prompt working, then check a rewrite.

Before you start

• A gateway on http://127.0.0.1:41002 with at least one provider target. See Gateway Setup for IDEs.
• A client API token. See API Tokens for IDEs.
• One model ID from the gateway's authenticated GET /v1/models response.
• The gptel package installed in Emacs.

Configure gptel

1. Export the token in the environment that starts Emacs:

   export VERDICTAN_CLIENT_TOKEN="<client-api-token>"

2. Register a Verdictan backend and make it the default. Merge this into your existing gptel configuration:

   init.el

   (setq gptel-model 'your-model-id
         gptel-backend
         (gptel-make-openai "Verdictan"
           :protocol "http"
           :host "127.0.0.1:41002"
           :endpoint "/v1/chat/completions"
           :key (lambda () (getenv "VERDICTAN_CLIENT_TOKEN"))
           :models '(your-model-id)
           :stream t))

3. Replace both your-model-id symbols with an id from GET /v1/models.

4. Start Emacs from the shell that exports VERDICTAN_CLIENT_TOKEN, or restart it there.

gptel sends the value that :key returns as Authorization: Bearer. The lambda reads the variable from the Emacs process environment each time, so the token stays out of your configuration file. An Emacs daemon keeps the environment it started with. Export the variable before you start the daemon.

:models takes model names as symbols. It only fills gptel's model menu; it does not create anything on the gateway. A model in the menu that the gateway does not serve fails at request time.

To register the backend without making it the default, call gptel-make-openai on its own. Then pick a model such as Verdictan:your-model-id with -m in gptel-menu. See the gptel README for other backend options.

Verify

1. Check the token and the model list:

   curl -fsS \
     -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN" \
     http://127.0.0.1:41002/v1/models

2. Run M-x gptel to open a chat buffer, type Reply with Hello., and press C-c RET (gptel-send). Check that the reply shows in the buffer.

3. In a second shell, read the recent events:

   verdictan events tail --since 10m --json

   The newest event in the events array has a timestamp from the moment you sent the prompt. Event delivery can take a few seconds, so run the command again if the event is not there yet.

4. Select a few lines in a scratch buffer and run M-x gptel-rewrite. Run the same command again, and check that this request also has an event.

An event proves that a request went through the gateway. Count a command as governed only after you see its event.

Other Emacs packages

Another package can use the gateway if you can set all of these:

• The host 127.0.0.1:41002 with the path /v1/chat/completions, or the base URL http://127.0.0.1:41002/v1
• A token that the package sends as Authorization: Bearer <token>
• A model ID from GET /v1/models

The gateway reads the client token only from the Authorization header. A package that sends its key in another header gets 401. Check the package's own documentation for the option names, and confirm each command with verdictan events tail. An operating-system proxy setting does not route a package through the gateway.

Troubleshooting

Symptom	Cause	Fix
Connection refused	The gateway is not running on port 41002	Start it, and check /healthz with curl.
401 with missing_api_key	Emacs did not inherit VERDICTAN_CLIENT_TOKEN, or the value is not a vdt_ token	Restart Emacs, or its daemon, from a shell that exports the variable. Don't use the gateway runtime token.
401 with invalid_api_token or tokens.expired	The token is revoked or expired	Check the token on the Console API Tokens page.
422 with no_matching_provider	gptel-model does not match anything the gateway serves	Use an id from GET /v1/models.
404 from the gateway	:endpoint is not /v1/chat/completions	Fix the endpoint, or leave it out: gptel uses /v1/chat/completions for hosts other than api.openai.com.
A reply but no event	The buffer uses another backend	Pick a Verdictan: model with -m in gptel-menu. Then see IDE Integration Troubleshooting.

Next steps

• Configure Policies for IDE Traffic: controls for the prompts Emacs sends.
• Monitor IDE AI Usage: Emacs traffic in events, History, and Usage.
• API Tokens for IDEs: scope and rotate the token gptel uses.