Foundry Local SDK reference

C# SDK Reference

Install packages

dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI

The C# samples in the GitHub repository are preconfigured projects. If you're building from scratch, you should read the Foundry Local SDK reference for more details on how to set up your C# project with Foundry Local.

Project configuration

The sample repositories include a .csproj file that handles platform detection automatically. If you're building a project from scratch, use this configuration as a reference:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- Windows: target Windows SDK for WinML hardware acceleration -->
  <PropertyGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0-windows10.0.19041.0</TargetFramework>
    <Platforms>ARM64;x64</Platforms>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <!-- Non-Windows: standard .NET -->
  <PropertyGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(RuntimeIdentifier)'==''">
    <RuntimeIdentifier>$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local" />
  </ItemGroup>

  <!-- Linux GPU support -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
  </ItemGroup>

  <!-- Shared utilities -->
  <ItemGroup>
    <Compile Include="../Shared/*.cs" />
  </ItemGroup>

</Project>

The following table explains the key project settings:

Quickstart

Use this snippet to verify that the SDK can initialize and access the local model catalog.

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;
using System.Linq;

var config = new Configuration
{
  AppName = "app-name",
  LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
  builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

await FoundryLocalManager.CreateAsync(config, logger);
var manager = FoundryLocalManager.Instance;

var catalog = await manager.GetCatalogAsync();
var models = await catalog.ListModelsAsync();

Console.WriteLine($"Models available: {models.Count()}");

This example prints the number of models available for your hardware.

Samples

• For sample applications that demonstrate how to use the Foundry Local C# SDK, see the Foundry Local C# SDK Samples GitHub repository.

API reference

• For more details on the Foundry Local C# SDK read Foundry Local C# SDK API Reference.

Native Audio Transcription API

The C# SDK includes a native audio client for transcribing audio files on-device using Whisper models. This runs inference in-process without needing the REST web server.

Get an audio client

After loading a Whisper model, get an audio client:

var audioClient = await model.GetAudioClientAsync();

Audio transcription methods

AudioClient settings

Example

var audioClient = await model.GetAudioClientAsync();
audioClient.Settings.Language = "en";
audioClient.Settings.Temperature = 0.0f;

await foreach (var chunk in audioClient.TranscribeAudioStreamingAsync(
    "recording.mp3", CancellationToken.None))
{
    Console.Write(chunk.Text);
}

References:

• Transcribe audio files with Foundry Local

JavaScript SDK Reference

Install packages

npm install foundry-local-sdk openai

Quickstart

Use this snippet to verify that the SDK can initialize and access the local model catalog.

import { FoundryLocalManager } from 'foundry-local-sdk';

console.log('Initializing Foundry Local SDK...');

const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});
console.log('✓ SDK initialized successfully');

// Explore available models
console.log('\nFetching available models...');
const catalog = manager.catalog;
const models = await catalog.getModels();

console.log(`Found ${models.length} models:`);
for (const model of models) {
    console.log(`  - ${model.alias}`);
}

This example outputs the list of available models for your hardware.

Samples

• For sample applications that demonstrate how to use the Foundry Local JavaScript SDK, see the Foundry Local JavaScript SDK Samples GitHub repository.

API reference

• For more details on the Foundry Local JavaScript SDK read Foundry Local JavaScript SDK API Reference.

References

• Integrate with inference SDKs
• Use Foundry Local native chat completions API

Python SDK Reference

Install packages

pip install foundry-local-sdk openai

Quickstart

Use this snippet to verify that the SDK can initialize and access the local model catalog.

import asyncio
from foundry_local_sdk import Configuration, FoundryLocalManager


async def main():
    config = Configuration(app_name="app-name")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    models = manager.catalog.list_models()
    print(f"Models available: {len(models)}")


if __name__ == "__main__":
    asyncio.run(main())

This example prints the number of models available for your hardware.

Samples

• For sample applications that demonstrate how to use the Foundry Local Python SDK, see the Foundry Local SDK Samples GitHub repository.

Configuration

The Configuration class allows you to customize the SDK behavior:

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    model_cache_dir="./foundry_local_data/model_cache",
    web={"urls": "http://127.0.0.1:55588"},
)

Core API

Native Chat Completions API

After loading a model, get a chat client:

client = model.get_chat_client()

Native Audio Transcription API

After loading a Whisper model, get an audio client:

audio_client = model.get_audio_client()

References:

• Transcribe audio files with Foundry Local
• Use Foundry Local native chat completions API
• Use chat completions via REST server

Rust SDK Reference

Install packages

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

Quickstart

Use this snippet to verify that the SDK can initialize and access the local model catalog.

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("app-name"))?;

    let models = manager.catalog().get_models().await?;
    println!("Models available: {}", models.len());

    Ok(())
}

This example prints the number of models available for your hardware.

Samples

• For sample applications that demonstrate how to use the Foundry Local Rust SDK, see the Foundry Local SDK Samples GitHub repository.

Configuration

The FoundryLocalConfig struct allows you to customize the SDK behavior:

use foundry_local_sdk::FoundryLocalConfig;

let config = FoundryLocalConfig::new("app-name")
    .with_log_level("info")
    .with_model_cache_dir("./foundry_local_data/model_cache")
    .with_web_urls("http://127.0.0.1:55588");

Core API

Native Chat Completions API

After loading a model, create a chat client with optional settings:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);

Message types: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

Native Audio Transcription API

After loading a Whisper model, create an audio client:

let audio_client = model.create_audio_client();

References:

• Transcribe audio files with Foundry Local
• Use Foundry Local native chat completions API
• Use chat completions via REST server

C++ SDK reference

Prerequisites

The C++ SDK provides a header-only wrapper over the native Foundry Local runtime. Your deployed application doesn't require the Foundry Local CLI or a .NET runtime.

Clone the native chat sample to start with a configured CMake project:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

The C++ samples require:

• CMake 3.20 or later.
• A C++20 compiler.
• The NuGet CLI on your PATH.

Configure and build the sample:

cmake -S . -B build
cmake --build build --config Release

During configuration, the sample restores version 2.2.1 of the Microsoft.AI.Foundry.Local.Runtime NuGet package to build/_packages. The package contains the C++ headers and native libraries for Windows, Linux, and macOS. You don't need a separate WinML package.

The CMake configuration selects the runtime assets for your operating system and architecture and copies the required native libraries beside the executable. On macOS and Linux, run the executable from build. On Windows, run the .exe file from build.

Select native assets that match your application's operating system and architecture:

Add build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include to your compiler's include path. Link the native library from the package's build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native directory:

• foundry_local.lib on Windows.
• libfoundry_local.so on Linux.
• libfoundry_local.dylib on macOS.

Deploy the matching native runtime and dependency libraries beside your executable or in the platform's library search path. Keep the restored package versions together. Don't mix headers and native libraries from different releases.

Quickstart

Replace the sample's main.cpp with the following code to initialize the SDK and count the models in the catalog:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

The example prints Models available: followed by the catalog's model count. It doesn't download or load a model. Keep the manager alive while you use catalog, model, or metadata objects obtained from it.

Reference: C++ wrapper declarations for Configuration, Manager, and Catalog.

Core API

The wrapper uses resource acquisition is initialization (RAII) to release native handles when objects leave scope.

API reference and samples

Use the public header and maintained examples for the complete API and inference workflows:

• C++ API declarations.
• Foundry Local samples.