Table of Contents

Running FoundationaLLM Services Locally

This guide provides the command lines needed to run FoundationaLLM services locally for development and debugging purposes.

Why Run Services Locally?

Running services locally is useful when:

  • Debugging with breakpoints - Step through code execution in your IDE to diagnose issues or understand behavior.
  • Testing local code changes - Validate your modifications before committing or deploying.
  • Integration testing - Inspect request/response payloads, authorization flows, and error handling.
  • Hybrid development - Run only the services you're actively modifying locally while the rest continue to run in the deployed environment.
Tip

The recommended approach is hybrid development: run only the services you are actively developing locally, while all other services use the deployed instance. This minimizes setup complexity and ensures you're testing against real infrastructure.

Prerequisites

Before running services locally, ensure your development environment is properly configured:

  1. Environment setup - Follow the complete setup guide in Configure local development environment.

  2. Required tools:

    • .NET SDK (for .NET APIs)
    • Node.js and npm (for User Portal and Management Portal)
    • Python 3.x (for Python APIs)

  3. Environment variables:

    • FoundationaLLM_AppConfig_ConnectionString - Azure App Configuration connection string (for .NET projects)
    • FOUNDATIONALLM_APP_CONFIGURATION_URI - Azure App Configuration URI (for Python projects)
    • FOUNDATIONALLM_VERSION - The version of your FoundationaLLM deployment

  4. RBAC permissions - Your user account needs appropriate permissions on Azure resources (Cosmos DB, Storage, Key Vault, App Configuration). See the development-local.md guide for details.

Configure URL Exceptions

When running services locally in a hybrid setup, you need to configure URL exceptions to route traffic from the deployed environment to your local instances. This ensures that only your user's requests are routed locally, without affecting other users.

Important

For detailed instructions on configuring URL exceptions, see Configuring URL Exceptions for Local Development.

The following table summarizes the URL exceptions you may need to configure:

Service Default Local URL Notes
CoreAPI https://localhost:63279/ Required when debugging Core API
ContextAPI https://localhost:6004/ Required for context operations
OrchestrationAPI https://localhost:7324/ Required for orchestration debugging
LangChainAPI http://localhost:8765/ Required for LangChain debugging
ManagementAPI https://localhost:63267/ Required when debugging Management API
PythonCodeSessionsAPI http://localhost:8000 Configured on agent's Code tool, not API Endpoints
ClaudeAgentSessionAPI http://localhost:8200 Configured on agent's Claude Agent tool, not API Endpoints

Running Services Locally

Build the .NET Solution

Before running any .NET service, rebuild the solution to include your changes:

cd C:\Repos\foundationallm\src
dotnet build FoundationaLLM.sln --configuration Debug
Note

This ensures all recent changes to APIs and shared libraries are compiled. The --configuration Debug flag enables debug symbols for breakpoint debugging.

Core API

The Core API handles user-facing operations including completions and session management.

cd C:\Repos\foundationallm\src\dotnet\CoreAPI
dotnet run --configuration Debug --no-build

Expected: Core API starts and listens on https://localhost:63279.

Context API

The Context API handles context operations including skill management and tool-initiated operations.

cd C:\Repos\foundationallm\src\dotnet\ContextAPI
dotnet run --configuration Debug --launch-profile https --no-build

Expected: Context API starts and listens on https://localhost:6004.

Management API

The Management API handles agent configuration and administrative operations.

cd C:\Repos\foundationallm\src\dotnet\ManagementAPI
dotnet run --configuration Debug --no-build

Expected: Management API starts and listens on https://localhost:63267.

Orchestration API

The Orchestration API coordinates agent execution and tool invocation.

cd C:\Repos\foundationallm\src\dotnet\OrchestrationAPI
dotnet run --configuration Debug --launch-profile https --no-build

Expected: Orchestration API starts and listens on https://localhost:7324.

LangChain API (Python)

The LangChain API provides LangChain-based orchestration capabilities.

cd C:\Repos\foundationallm\src\python\LangChainAPI
$env:FOUNDATIONALLM_ENV="dev"
$env:FOUNDATIONALLM_APP_CONFIGURATION_URI="https://your-appconfig.azconfig.io"
& '.\.venv\Scripts\python.exe' '-m' 'uvicorn' 'app.main:app' '--reload' '--port' '8765'

Expected: LangChain API starts and listens on http://localhost:8765.

Note

Replace your-appconfig.azconfig.io with your actual Azure App Configuration URI. The --reload flag enables auto-reload when code changes are detected.

PythonCodeSessionsAPI (Code Interpreter)

The PythonCodeSessionsAPI provides a sandbox environment for Code Interpreter tool execution.

Setup requirements:

  1. Create the required data directory: C:\mnt\data

    Important

    This directory must be on the same drive as your repository (typically C:).

  2. Ensure the Python virtual environment is set up with required packages.

Run the service:

cd C:\Repos\foundationallm\src\python\PythonCodeSessionAPI\app
..\.venv\Scripts\Activate.ps1
& '..\.venv\Scripts\python.exe' '-m' 'uvicorn' 'main:app' '--reload' '--port' '8000'

Expected: PythonCodeSessionsAPI starts and listens on http://localhost:8000.

Alternative: You can also run this service using the VS Code/Cursor debug configuration:

  1. Open the Debug panel
  2. Select the PythonCodeSessionAPI configuration
  3. Press F5 to start debugging
Note

When running PythonCodeSessionsAPI locally, you need to configure the endpoint override on the agent's Code tool rather than through API Endpoints. See Configuring URL Exceptions for Local Development for details.

ClaudeAgentSessionAPI (Claude Agent Tool)

The ClaudeAgentSessionAPI provides a session environment for the Claude Agent Tool, wrapping the Claude Agent SDK to execute code, perform web searches, and run file operations.

Prerequisites:

  1. Claude CLI - The claude CLI must be installed and available on your PATH. The API uses shutil.which("claude") to locate it at startup.

  2. Anthropic API key - The .env file at src/python/ClaudeAgentSessionAPI/.env must contain a valid ANTHROPIC_API_KEY. The API loads it automatically via python-dotenv at startup.

  3. Data directory - The API automatically creates C:\mnt\data on Windows as its working directory (equivalent to /mnt/data in production Linux containers).

  4. Ensure the Python virtual environment is set up with required packages.

Run the service:

cd C:\Repos\foundationallm\src\python\ClaudeAgentSessionAPI
& '.\.venv\Scripts\python.exe' '-m' 'uvicorn' 'app.main:app' '--port' '8200' '--host' '0.0.0.0'

Expected: ClaudeAgentSessionAPI starts and listens on http://localhost:8200.

Warning

Do not use the --reload flag on Windows. Uvicorn's reload mode forces a SelectorEventLoop which does not support the subprocess transports required by the Claude Agent SDK. Always start without --reload.

Note

The --host 0.0.0.0 flag is required because on Windows, localhost may resolve to IPv6 [::1] while the ContextAPI connects via IPv4 127.0.0.1. Binding to 0.0.0.0 ensures the service is reachable on all interfaces.

Note

When running ClaudeAgentSessionAPI locally, you need to configure the endpoint override on the agent's Claude Agent tool rather than through API Endpoints. This follows the same pattern as the PythonCodeSessionsAPI. See Configuring URL Exceptions for Local Development for details.

User Portal

The User Portal is the end-user interface for interacting with agents.

cd C:\Repos\foundationallm\src\ui\UserPortal
npm run dev

Expected: User Portal starts and is accessible at http://localhost:3000.

Alternative: Use the "User Portal UI - Backend" configuration in the VS Code/Cursor debug panel.

Management Portal

The Management Portal is the administrative interface for configuring agents and system settings.

cd C:\Repos\foundationallm\src\ui\ManagementPortal
npm run dev

Expected: Management Portal starts and is accessible at http://localhost:3001.

Alternative: Use the "Management Portal UI - Backend" configuration in the VS Code/Cursor debug panel.

Configuration Notes

When running services locally:

  • Azure resource connectivity - Local services connect to deployed Azure resources (Cosmos DB, Storage accounts, Key Vault, etc.) using your Entra ID credentials.
  • Authentication - Services authenticate using your local Azure CLI or Visual Studio credentials.
  • Hybrid operation - Only run the services you're actively developing locally. All other services should use the deployed instance to ensure realistic testing conditions.
Warning

While you have URL exceptions enabled, you will not be able to use the services externally from the local environment. For example, if you are running CoreAPI locally and then try to use the User Portal from your phone, you will get an error because the requests will attempt to route to your local URL. Be sure to disable URL exceptions when finished to restore normal behavior.