Xcode with Verdictan

Add your Verdictan agent to Xcode as a chat provider, and the conversations you have with its models go through your policies. Xcode calls a chat provider with the Chat Completions API, which the gateway serves. Agents, the built-in ChatGPT and Claude options, and GitHub Copilot for Xcode do not use this provider.

Before you start

• A connected gateway with at least one provider target, and an agent with a published hostname. See Gateway Setup for IDEs and Use Your Central Agent URL.
• A client API token. See API Tokens for IDEs.
• A version of Xcode that has Intelligence in its settings.

Use the published hostname, not 127.0.0.1:41002. Xcode's Locally Hosted option takes only a port and a description, so it cannot send a token. A connected gateway answers a request without a token with 401 and missing_api_key.

Add Verdictan as a chat provider

1. Choose Xcode > Settings and select Intelligence in the sidebar.
2. Under Chat, click Add a Chat Provider and select Internet Hosted.
3. Set the URL to https://<published-hostname>, without /v1.
4. Fill in the key details so that Xcode sends the header Authorization: Bearer <client-api-token>. Don't use the gateway runtime token or a provider key.
5. Click Add.

Xcode appends /v1/models and /v1/chat/completions to the URL you enter. A URL that already ends in /v1 makes it call /v1/v1/models, which the gateway does not serve. See Apple's Setting up coding intelligence.

Apple's guide does not describe the individual key fields in the Internet Hosted sheet. The model list is your check: the gateway answers GET /v1/models only for a valid client token, so Xcode lists the gateway's models only when the header is right.

When Project Context is on in a conversation, Xcode adds relevant code from your project to the prompt. Your policies see that code as part of the request.

Verify

1. Check the token and the model list through the published hostname:

   export VERDICTAN_CLIENT_TOKEN="<client-api-token>"
   
   curl -fsS \
     -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN" \
     https://<published-hostname>/v1/models

2. In Xcode, check that the new chat provider lists the same model IDs.

3. Press Command-0, click New Conversation, and choose a Verdictan model under Chat.

4. Send Reply with Hello. Do not edit files. Check that the reply shows in Xcode.

5. In a terminal, 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 message. Event delivery can take a few seconds, so run the command again if the event is not there yet.

An event proves that the conversation went through the gateway. Do the same check for the coding tools popover in the source editor if you use it with this model.

Xcode traffic by coverage

Xcode traffic	Goes through Verdictan
Conversations and coding tools with a model from the Verdictan chat provider	Yes, when a matching event appears
Agents under Agents, such as those you install with Get or add over the Agent Client Protocol	No. A chat provider does not change where agents send requests.
ChatGPT in Xcode and Claude Sonnet & Opus under Chat	No. They connect to OpenAI and Anthropic.
GitHub Copilot for Xcode	No. See the next section.

GitHub Copilot for Xcode

GitHub Copilot for Xcode is a separate app with its own model settings. GitHub documents bring-your-own-key for its chat with a fixed list of providers: Anthropic, Azure, Google Gemini, Groq, OpenAI, and OpenRouter. You add one from Manage Models in the Copilot chat model picker. GitHub does not document a custom OpenAI-compatible endpoint there, so this guide does not route Copilot for Xcode through Verdictan. See GitHub's bring your own key overview.

Don't enter a Verdictan token in a provider form that sends it to another vendor's hostname.

Troubleshooting

Symptom	Cause	Fix
Xcode lists no models	The URL ends in /v1, or the key fields do not produce Authorization: Bearer <client-api-token>	Enter the URL without /v1, and check the key fields. The curl check above shows the expected result.
401 with missing_api_key	No Bearer token reached the gateway, for example from a Locally Hosted provider	Use Internet Hosted with the published hostname and the client 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 selected model does not match anything the gateway serves	Pick a model that GET /v1/models lists.
curl to the published hostname fails	The agent has no published binding, or the relay is not connected	See the troubleshooting table in Use Your Central Agent URL.
Long replies fail through the published hostname	The relay waits up to 30 seconds for each relayed request	Check provider response time. See Use Your Central Agent URL.
A reply but no event	The conversation used an agent, a built-in chat option, or another provider	Start a new conversation and choose a Verdictan model under Chat. Then see IDE Integration Troubleshooting.

Next steps

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