Custom IDE Model Clients

Use this page for a VS Code extension, JetBrains plugin, or other editor client that lets you set its own model endpoint. Setting names differ from client to client, but each one needs the same three values: the gateway URL, a Verdictan client API token, and a model ID.

For clients with their own guide, see Continue, GitHub Copilot, or JetBrains AI Assistant.

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.

Check what the client can set

A client can use the gateway only if you can set all of these:

Requirement	Why
The endpoint URL	The client must send requests to the gateway, not to its vendor.
The token in Authorization: Bearer <token>	The gateway reads the client token only from this header.
The model ID	The gateway routes by model ID.
The request format: Chat Completions, Responses, or Messages	These are the formats the policy chain runs on.

A client that sends its key in another header, such as x-api-key, gets 401 with missing_api_key. A client with a fixed vendor endpoint cannot use the gateway. A network proxy setting, such as HTTP_PROXY or the editor's proxy field, does not work either: the gateway is not an HTTP proxy.

Configure the client

1. Open the client's model or provider settings.

2. Enter the gateway URL in the shape the client expects:

   The client asks for	Enter
   An OpenAI-compatible base URL	http://127.0.0.1:41002/v1
   A complete Chat Completions URL	http://127.0.0.1:41002/v1/chat/completions
   A complete Responses URL	http://127.0.0.1:41002/v1/responses
   A complete Messages URL	http://127.0.0.1:41002/v1/messages

3. Enter the client API token as the API key. Don't use the gateway runtime token or a provider key.

4. Enter a model ID from GET /v1/models, or pick one if the client reads the list itself.

5. Select that model for each feature you want governed.

The gateway answers 404 for a path it does not serve. That happens when the client adds a route to a complete URL, gets /v1 where it expects a complete URL, or adds /v1 to a base URL that already ends in /v1. Change the URL until the client's requests reach one of the paths above.

If the editor runs on another machine, use your agent's published URL instead of 127.0.0.1. See Use Your Central Agent URL.

What the gateway covers

Clients often call more than one endpoint. Each endpoint below requires the client token, but only some run the policy chain:

Endpoint	Policy chain
/v1/chat/completions, /v1/responses, /v1/messages	Runs
/v1/chat/completions/ws, /v1/responses/ws (WebSocket)	Runs on complete text frames
/v1/completions (legacy completions)	Does not run
/v1/embeddings, /v1/audio/*, /v1/moderations	Does not run
/v1/models	Lists models; no model call

On the routes without the policy chain, the gateway still applies provider access, capability, and budget checks. No control inspects their input or output. Messages uses the same policy stages as the other two text families, but full policy parity with them is not guaranteed. See Runtime Request Families.

Verify

1. Check the token and the model list:

   export VERDICTAN_CLIENT_TOKEN="<client-api-token>"
   
   curl -fsS \
     -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN" \
     http://127.0.0.1:41002/v1/models

2. In the editor, select the Verdictan model, send Reply with Hello., and check that the editor shows an answer.

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

   verdictan events tail --since 10m --json

4. Check that the newest event 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.

5. Repeat the check for each feature you want governed, such as inline suggestions or edits.

An event proves that a call went through the gateway. Inline suggestions, indexing, and the client's own telemetry can use other endpoints or other models. Count a feature as governed only after you see its event.

Troubleshooting

Symptom	Cause	Fix
Connection refused	The gateway is not running on port 41002	Start it, and check /healthz with curl.
404 Not Found with no error code	The URL has the wrong shape for this client	Use the shape from the table in Configure the client.
404 with models_disabled	The policy config turns off the models endpoint	Turn it on, or enter the model ID by hand.
401 with missing_api_key	No Bearer token, a token in another header, or a value that is not a vdt_ token	Send the client API token as Authorization: Bearer. 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	The model ID does not match anything the gateway serves	Use an id from GET /v1/models.
Chat produces events but inline suggestions do not	The inline feature uses another endpoint or model	Check which model the inline feature selects. If it calls /v1/completions, no policy control runs on it.

For more checks, see IDE Integration Troubleshooting.

Next steps

• Configure Policies for IDE Traffic: controls for the prompts the client sends.
• Monitor IDE AI Usage: client traffic in events, History, and Usage.
• Runtime Request Families: routes, formats, and policy stages for each endpoint.