Configuring URL Exceptions for Local Development

This guide explains how to use URL exceptions to route calls to your local service instances instead of the deployed instances. This is useful when you want to debug one or more services locally while everything else continues to run in the deployed environment.

IMPORTANT While you have a URL exception enabled you will not be able to use the services externally from the local environment. For example, if you are running CoreAPI locally on your laptop and then try to use the User Portal from your phone, you will get an error because User Portal will try to use the local URL and the CoreAPI service is not available on your phone. Be sure to disable the URL exception when you are finished so that you restore the normal behavior of your deployed instance.

Overview

In FoundationaLLM, many services discover the target URL for other services via configuration. A URL exception lets you override that URL for a specific User Principal Name (UPN) (your Entra ID sign-in/email), so that only your user is routed to the local endpoint.

This is commonly used when:

You are debugging a specific API locally and want traffic routed to it without changing global configuration.
You are testing integration behavior (request/response payloads, authorization, throttling, etc.) against your local changes.
You are using the Code Interpreter and need local routing for dependent APIs to properly render images/download files.

CoreAPI edge case (Code Interpreter images/files)

If you want to render images or download files produced by the Code Interpreter, you typically need both:

CoreAPI running locally
ContextAPI running locally
URL exceptions configured so calls route to those local instances

If you miss this setup, the UI may show an error message where an image should be (because the retrieval/download path still routes to the deployed services).

Summary table (exceptions to configure)

Use the table below as a quick reference. For each exception you enable, set Enabled to true.

Note

The Default Local URL values below reflect common launchSettings.json defaults for the repo. Your local profile may differ (for example, HTTP vs HTTPS). Use the URL your local service is actually listening on.

Service (API Endpoint)	When to enable	Default local URL	Principal Name (UPN)	Enabled
CoreAPI	Route requests (including Code Interpreter asset retrieval) to your local CoreAPI while keeping the rest deployed. Required for Code Interpreter image/file retrieval when paired with ContextAPI local routing.	`https://localhost:63279/`	Your UPN (example: `user@foundationallm.ai`)	`true`
ContextAPI	Route context operations to your local ContextAPI. Often paired with CoreAPI when debugging Code Interpreter sessions and asset retrieval.	`https://localhost:6004/`	Your UPN	`true`
OrchestrationAPI	Route orchestration (agent/tool execution flow) to your local OrchestrationAPI.	`https://localhost:7324/`	Your UPN	`true`
GatewayAPI	Route gateway traffic to your local GatewayAPI (useful when debugging routing/proxy behavior).	`https://localhost:7209/`	Your UPN	`true`
LangChainAPI	Route LangChain operations to your local LangChainAPI.	`http://localhost:8765/`	Your UPN	`true`
ManagementAPI	Route configuration/management operations to your local ManagementAPI (primarily used when developing ManagementAPI itself).	`https://localhost:63267/`	Your UPN	`true`
PythonCodeSessionsAPI	Route Code Interpreter code session execution to a local Python code sessions service. Configured on the agent’s Code tool, not on API Endpoints.	`http://localhost:8000`	Your UPN	`true`

Configure URL exceptions for API endpoints (Management Portal)

Use the steps in this section for all services listed above except PythonCodeSessionsAPI.

Enable (add) a URL exception

Open the Management Portal.
In the left navigation, go to API Endpoints.
Find the API endpoint you want to override (for example, ContextAPI).
Click the Edit (gear/cog) icon for that API endpoint.
Scroll to the URL exceptions: section.
Click Add URL Exception.
In the dialog, provide:
- URL: your local service URL (for example https://localhost:6004/)
- User Principal Name: your UPN (for example zoinertejada@foundationallm.ai)
- Enabled: set to true
Click Save in the dialog.
Click Save Changes on the API endpoint edit page.

Disable a URL exception (keep it, but stop routing locally)

Open the API endpoint edit page (Steps 1–4 above).
In the URL exceptions table, locate your exception row.
Click the Edit (gear/cog) icon on that row.
Set Enabled to false.
Click Save in the dialog.
Click Save Changes on the API endpoint edit page.

Delete a URL exception (remove it entirely)

Open the API endpoint edit page (Steps 1–4 above).
In the URL exceptions table, locate your exception row.
Click the Delete (trash) icon on that row.
Click Save Changes on the API endpoint edit page.

Service-by-service guidance (API Endpoints)

This section calls out what to set and when you usually enable each exception.

CoreAPI

Enable when: you want CoreAPI requests (including Code Interpreter asset retrieval paths) routed to your local CoreAPI.
URL: https://localhost:63279/ (or your local CoreAPI URL)
Principal Name: your UPN
Enabled: true

ContextAPI

Enable when: you want context operations routed to your local ContextAPI; commonly paired with local CoreAPI for Code Interpreter troubleshooting.
URL: https://localhost:6004/ (or your local ContextAPI URL)
Principal Name: your UPN
Enabled: true

OrchestrationAPI

Enable when: you are debugging orchestration behavior (agent execution, tool selection/execution paths, policy, retries, etc.) locally.
URL: https://localhost:7324/ (or your local OrchestrationAPI URL)
Principal Name: your UPN
Enabled: true

GatewayAPI

Enable when: you are debugging gateway routing/proxy behavior locally.
URL: https://localhost:7209/ (or your local GatewayAPI URL)
Principal Name: your UPN
Enabled: true

LangChainAPI

Enable when: you are debugging LangChain integration behavior locally.
URL: http://localhost:8765/ (or your local LangChainAPI URL)
Principal Name: your UPN
Enabled: true

ManagementAPI

Enable when: you are running ManagementAPI locally and want management/configuration calls to route to it for your user.
URL: https://localhost:63267/ (or your local ManagementAPI URL)
Principal Name: your UPN
Enabled: true

Configure PythonCodeSessionsAPI routing (Agent Code tool override)

PythonCodeSessionsAPI is not configured through API Endpoints URL exceptions. Instead, you configure a per-user override on an agent that has the Code Interpreter tool enabled.

Enable/disable code session endpoint overrides for a user

Open the Management Portal.
In the left navigation, go to Agents and select All Agents.
Select an agent that uses the Code Interpreter tool.
Click the agent’s Edit (gear/cog) icon.
Scroll to the Tools section.
Find the Code tool and click its Configure (gear/cog) icon.
In the Configure Tool dialog, find Tool properties and click Add Property.
Set the property:
- Property Key: code_session_endpoint_overrides
- Property Type: Object / Array
- Property Value: add entries in this form (example):

[
  {
    "upn": "user1@foundationallm.ai",
    "endpoint": "http://localhost:8000",
    "enabled": false
  },
  {
    "upn": "user2@foundationallm.ai",
    "endpoint": "http://localhost:8000",
    "enabled": true
  }
]

Click Save in the property dialog.
Click Save in the Configure Tool dialog.
Click Save Changes on the agent edit page.

Remove (delete) a code session endpoint override entry

To delete an override entry, edit the same property value and remove the corresponding object from the array, then save.

Operational notes

Restart required after changes

In most cases, changes to URL exceptions (or agent tool overrides) require the ManagementAPI to be restarted so it reloads the latest configuration.

If you run ManagementAPI locally, restart the local process.
If you are relying on the deployed ManagementAPI, restart the deployed instance so the configuration refreshes.

Table of Contents