Table of Contents

Using the Local Services Management Script

This guide explains how to use the Manage-LocalServices.ps1 PowerShell script to start, stop, monitor, and rebuild FoundationaLLM services running on your local development machine.

Why Use This Script?

Managing FoundationaLLM locally involves up to nine separate services across .NET, Python, and Node.js runtimes. Starting them one-by-one, checking ports, and hunting for stale processes is tedious and error-prone. This script provides a single command for each operation:

  • Start all or selected services in new terminal windows, then wait for health checks to pass.
  • Stop all or selected services by locating the processes listening on their known ports.
  • Status — see a consolidated table of every service and whether it is Running, Starting, or Stopped.
  • Rebuild the .NET solution so all API projects pick up your latest code changes.

The script is equally useful for humans running it from a terminal and AI agents automating local development workflows.

Prerequisites

Before using the script, complete the environment setup described in Running FoundationaLLM Services Locally. In particular:

  1. .NET SDK installed and the solution built at least once (dotnet build src\FoundationaLLM.sln --configuration Debug).
  2. Python virtual environments created for each Python service (LangChainAPI, ClaudeAgentSessionAPI, PythonCodeSessionAPI) with required packages installed.
  3. Node modules installed for UserPortal and ManagementPortal (npm install in each directory).
  4. Environment variables set as described in the prerequisites section of running_locally.md.

Script Location

devtools/scripts/powershell/Manage-LocalServices.ps1

The script auto-detects the repository root by walking up from its own location until it finds src\FoundationaLLM.sln. You can override this with the -RepoRoot parameter if needed.

Usage

Parameters

Parameter Required Description
-Action Yes Operation to perform: Start, Stop, Status, or Rebuild.
-Services No Comma-separated list of service names. When omitted, the action applies to all services.
-RunInCursorTerminal No Runs a single service inline in the current shell instead of spawning a new window. Requires -Action Start and exactly one -Services value. Designed for Cursor IDE agent integration.
-RepoRoot No Path to the repository root. Auto-detected by default.

Start All Services

.\Manage-LocalServices.ps1 -Action Start

This opens a new PowerShell window for each service, then polls their health endpoints until they report healthy (or the per-service timeout expires). The command finishes with a status table.

Start Specific Services

.\Manage-LocalServices.ps1 -Action Start -Services CoreAPI,LangChainAPI,UserPortal

Only the listed services are started. All others are left as-is.

Start a Service in Cursor Terminal (Agent Mode)

.\Manage-LocalServices.ps1 -Action Start -Services LangChainAPI -RunInCursorTerminal

Runs the service inline in the current shell instead of opening a new window or tab. The service's stdout and stderr stream directly into the terminal. This is designed for use within Cursor's integrated terminal so that the AI agent can monitor the service's console output in real time.

Note

-RunInCursorTerminal requires exactly one service. The service runs in the foreground and blocks the terminal — use Ctrl+C to stop it. Health checks and the status table are skipped since the agent can read the output directly.

Stop All Services

.\Manage-LocalServices.ps1 -Action Stop

Finds processes listening on each service's known port and terminates them (including child process trees for Node.js services). Finishes with a status table.

Stop Specific Services

.\Manage-LocalServices.ps1 -Action Stop -Services CoreAPI,LangChainAPI

Check Status

.\Manage-LocalServices.ps1 -Action Status

Displays a table like:

Service                Type     Port  Status   URL
-------                ----     ----  ------   ---
CoreAPI                dotnet  63279  Running  https://localhost:63279
ContextAPI             dotnet   6004  Running  https://localhost:6004
ManagementAPI          dotnet  63267  Stopped  https://localhost:63267
OrchestrationAPI       dotnet   7324  Running  https://localhost:7324
LangChainAPI           python   8765  Running  http://localhost:8765
ClaudeAgentSessionAPI  python   8200  Stopped  http://localhost:8200
PythonCodeSessionsAPI  python   8000  Stopped  http://localhost:8000
UserPortal             node     3000  Running  http://localhost:3000
ManagementPortal       node     3001  Running  http://localhost:3001

Status values:

Status Meaning
Running The service's health endpoint returned a successful response.
Starting The port is open but the health check has not yet succeeded.
Stopped Nothing is listening on the service's port.

Rebuild .NET Solution

.\Manage-LocalServices.ps1 -Action Rebuild

Runs dotnet build src\FoundationaLLM.sln --configuration Debug from the repository root. After the build completes (or fails), a status table is printed so you can see which services are still running.

Tip

After a rebuild, you typically need to restart the .NET services for them to pick up the new binaries. A common workflow is:

.\Manage-LocalServices.ps1 -Action Stop -Services CoreAPI,ContextAPI,ManagementAPI,OrchestrationAPI
.\Manage-LocalServices.ps1 -Action Rebuild
.\Manage-LocalServices.ps1 -Action Start -Services CoreAPI,ContextAPI,ManagementAPI,OrchestrationAPI

Service Names Reference

Use these exact names with the -Services parameter:

Name Type Port Description
CoreAPI dotnet 63279 User-facing operations (completions, sessions)
ContextAPI dotnet 6004 Context operations (skill management, tool sessions)
ManagementAPI dotnet 63267 Agent configuration and administration
OrchestrationAPI dotnet 7324 Agent execution coordination
LangChainAPI python 8765 LangChain-based orchestration
ClaudeAgentSessionAPI python 8200 Claude Agent Tool session management
PythonCodeSessionsAPI python 8000 Code Interpreter sandbox
UserPortal node 3000 End-user chat interface
ManagementPortal node 3001 Administrative configuration interface

How It Works

Starting Services

Each service is launched in a new PowerShell window via Start-Process powershell -ArgumentList '-NoExit', '-Command', .... This keeps each service's stdout/stderr visible in its own terminal. The script then polls each service's health endpoint at 3-second intervals until either:

  • The health check returns a 2xx/3xx response (service marked Running), or
  • The per-service timeout expires (.NET: 60s, Python: 30–90s, Node: 30s).

If a service's port is already in use when the script runs, it is skipped with a message.

Stopping Services

The script finds the process owning each service's port using Get-NetTCPConnection -LocalPort <port> -State Listen, then kills the process tree with taskkill /PID <pid> /T /F. This ensures child processes (e.g., Node.js workers spawned by npm) are also terminated.

Health Checks

  • .NET APIs: GET https://localhost:<port>/instances/_/status with -SkipCertificateCheck (self-signed dev certificate).
  • Python APIs: GET http://localhost:<port>/status or /health depending on the service.
  • Node Portals: GET http://localhost:<port>/ — any non-error response indicates the dev server is ready.

Troubleshooting

Port already in use

If a service fails to start because its port is taken by a stale process:

# Find what's using the port (e.g., 63279)
Get-NetTCPConnection -LocalPort 63279 -State Listen | Select-Object OwningProcess
# Kill the stale process
Stop-Process -Id <pid> -Force

Or use the script itself to stop the conflicting service first:

.\Manage-LocalServices.ps1 -Action Stop -Services CoreAPI
.\Manage-LocalServices.ps1 -Action Start -Services CoreAPI

Python virtual environment not found

If a Python service fails with "cannot find .venv", ensure you have created the virtual environment in the correct location. For example:

cd C:\Repos\foundationallm\src\python\LangChainAPI
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

.NET build errors or missing changes

If .NET services start but don't reflect your code changes, ensure you rebuilt:

.\Manage-LocalServices.ps1 -Action Rebuild

Then restart the .NET services.

Health check times out but service is running

Some services take longer to initialize on first start (e.g., loading models, connecting to Azure resources). Check the service's terminal window for progress. If needed, the service may succeed shortly after the script's timeout — run -Action Status to recheck.