svnscha - tutorial

AI Agents in .NET: Beyond DevUI - LibreChat Integration

2026-01-04T00:00:00+00:00

Welcome back to the AI Agents in .NET series. In the introduction, I built a basic conversational agent. In Part 1, I added database persistence, embeddings, and semantic search capabilities.

Today I'm breaking free from the built-in DevUI. Time to escape the developer dungeon.

Don't get me wrong - DevUI is fantastic for development and debugging.

This post connects those agents to LibreChat through OpenAI-compatible endpoints.

The first version failed when a tool-calling agent was used through a downstream client. The solution was a reusable middleware pattern called ToolCallFilterAgent, which I explain below.

The Problem with DevUI

DevUI served me well. It let me test agents, inspect tool calls, and debug issues. But it has limitations:

Single-purpose: It's a development tool, not a production interface
No multi-user support: One conversation at a time
Limited customization: You get what you get

For real-world use, I need something more flexible. And rather than building my own chat UI (been there, done that in early 2025, don't want to repeat), let's leverage existing open-source solutions.

Why LibreChat?

I mentioned LibreChat in my DGX Spark post, and I really enjoy it. Like, really like it.

It's:

OpenAI API compatible: Speaks the same language as ChatGPT
Self-hosted: Your data stays yours (take that, cloud overlords)
Feature-rich: File uploads, conversations, presets, the whole shebang
Beautiful: Actually looks like something you'd want to use - not like a developer accidentally vomited JSON onto a webpage

The key insight? LibreChat doesn't care what's behind the API. It just needs something that speaks OpenAI's protocol. And guess what the Microsoft Agent Framework already supports?

The Plan

Here's what I'm building:

%%{init: {"theme": "dark"}}%%
flowchart LR
    LC[LibreChat] -->|OpenAI API| K[Knowledge API]
    K -->|Agent Framework| A[Agents]
    A --> KA[Knowledge]
    A --> KSA[KnowledgeSearch]
    A --> KTA[KnowledgeTitle]
    KSA -->|Vector Search| PG[(PostgreSQL)]

LibreChat talks to our Knowledge API using the standard OpenAI chat completions format. Our API routes requests to our agents based on the model parameter. From LibreChat's perspective, it's just another OpenAI-compatible endpoint with multiple models to choose from.

Removing DevUI, Embracing Swagger

First things first - I'm removing the DevUI dependency and redirecting to Swagger for API exploration. DevUI is great for debugging, but for an API-first approach, Swagger makes more sense. Plus, Swagger has that nice "I'm a real API" energy.

The home page now redirects to Swagger:

app.MapGet("/", () => Results.Redirect("/swagger"));

Clean and simple. The API is now focused on being a backend service. Goodbye, training wheels.

Exposing OpenAI-Compatible Endpoints

The Agent Framework provides a beautiful MapOpenAIChatCompletions method that exposes agents as OpenAI-compatible endpoints. Each agent gets its own endpoint path. It's almost too easy (foreshadowing...).

I collect agent builders during registration and map them after building the app:

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ... OpenAI client setup ...

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
});

var app = builder.Build();

// ... middleware setup ...

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

Now each agent has its own endpoint:

/Knowledge/v1/chat/completions
/KnowledgeSearch/v1/chat/completions

Pretty slick, right?

Setting Up LibreChat

Before I go further, let me get LibreChat running so I can test this integration. If you don't have LibreChat running yet, here's the quick setup. (If you do, feel free to skip ahead and judge my configuration choices.)

Docker Compose

mkdir -p ~/librechat
cd ~/librechat
git clone https://github.com/danny-avila/LibreChat.git .
cp .env.example .env

The LibreChat Configuration

Create librechat.yaml and point LibreChat at the API:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch"]
        fetch: false

      titleConvo: false
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Docker Compose Override

Create docker-compose.override.yml to mount the config:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
    extra_hosts:
      - "host.docker.internal:host-gateway"

The extra_hosts line is crucial - it lets containers reach the host machine where the Knowledge API runs.

Fire It Up

docker compose up -d

Navigate to http://localhost:3080, create an account (it's local, don't worry), and you should see "Agent Framework" in the endpoint list.

But wait - if you select "Knowledge" and send a message, LibreChat hits /v1/chat/completions with "model": "Knowledge". My per-agent endpoints live at /Knowledge/v1/chat/completions instead. Houston, we have a routing problem.

The Model Routing Middleware

LibreChat (and most OpenAI clients) expect a single endpoint at /v1/chat/completions where the model parameter determines the underlying model but in this scenario it should determines routing:

{
  "model": "Knowledge",
  "messages": [{"role": "user", "content": "What's on your mind?"}]
}

I need middleware that reads the model from the request body and rewrites the path to the agent-specific endpoint. Nothing fancy, just some good old path mangling:

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException)
            {
            }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

The key points:

Enable buffering: I need to read the body to extract model, then reset it for the actual handler
Path rewriting: Transform /v1/chat/completions → /{model}/v1/chat/completions
Error handling: Return a proper OpenAI-style error if model is missing

Now when LibreChat sends a request, it gets routed to the right agent automatically. Back to LibreChat - select "Knowledge" from the dropdown, send a message, and... it works! Streaming responses, proper formatting, everything.

At this point, I thought I was done. Celebrated with a coffee. Time to test KnowledgeSearch...

The Tool Call Disaster (And How I Fixed It)

I switched to the KnowledgeSearch model in LibreChat, asked it to search for something, and... nothing. The request just hung. Then cancelled. No error message. No response. Just the cold, judgmental silence of broken software.

I dug through LibreChat's source code, traced the request flow, added logging everywhere. Console.WriteLine debugging like it's 2005.

Note: We should get to Observability very soon...

The Problem

My KnowledgeSearch agent uses tools - specifically the SearchConversationHistory function. When the agent executes a tool, the response stream includes FunctionCallContent and FunctionResultContent alongside the text. This is how the Agent Framework communicates "I'm calling a tool" and "here's what the tool returned."

LibreChat receives the stream and interprets the function call as something it should execute. That fails because the function exists in the backend rather than in LibreChat, so LibreChat cancels the request.

[Our Agent] → "I'll search for that" → FunctionCallContent{SearchConversationHistory}
[Our Agent] → [executes tool internally]
[Our Agent] → FunctionResultContent{results...}
[Our Agent] → "Based on the search, here's what I found..."
          ↓
[LibreChat] → Sees FunctionCallContent → "I need to call this function!"
[LibreChat] → Can't find function → Cancels request
          ↓
[User] → "Why isn't anything happening?" 😤

The frustrating part? You can't disable this behavior in LibreChat. It's doing the right thing for its use case - if it sends a function call to an upstream model, it expects to handle the response. But I'm the upstream model, and I've already handled my own tool calls. We're both right, and that's the most annoying kind of bug.

The Solution

Don't send tool call content downstream. Filter it out before it leaves the API. If LibreChat never sees the tool calls, it can't get confused by them. taps forehead

Meet ToolCallFilterAgent - a delegating agent that wraps any agent and strips FunctionCallContent and FunctionResultContent from responses. It's like a bouncer for your API responses:

/// <summary>
/// A delegating agent that filters out tool call content from responses.
/// This prevents downstream consumers from seeing FunctionCallContent and FunctionResultContent
/// that they cannot execute.
/// </summary>
public sealed class ToolCallFilterAgent : DelegatingAIAgent
{
    public ToolCallFilterAgent(AIAgent innerAgent) : base(innerAgent) { }

    public override async Task<AgentRunResponse> RunAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        CancellationToken cancellationToken)
    {
        var response = await InnerAgent.RunAsync(messages, thread, options, cancellationToken);
        response.Messages = FilterToolCalls(response.Messages);
        return response;
    }

    public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var update in InnerAgent.RunStreamingAsync(messages, thread, options, cancellationToken))
        {
            yield return FilterToolCalls(update);
        }
    }

    private static IList<ChatMessage> FilterToolCalls(IEnumerable<ChatMessage> messages) =>
        messages.Select(m => new ChatMessage(m.Role,
            m.Contents.Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList()
        )).ToList();

    private static AgentRunResponseUpdate FilterToolCalls(AgentRunResponseUpdate update) =>
        new(update.Role, update.Contents
            .Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList());
}

Now in the AgentFactory, I wrap KnowledgeSearchAgent:

public static AIAgent CreateKnowledgeSearchAgent(IChatClient chatClient, IServiceProvider services, string key)
{
    var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

    var agent = chatClient.CreateAIAgent(new ChatClientAgentOptions
    {
        Id = key,
        Name = key,
        ChatOptions = new ChatOptions
        {
            ConversationId = "global",
            Instructions = KnowledgeSearchSystemPrompt,
            Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync, "SearchConversationHistory")],
            ToolMode = ChatToolMode.Auto
        }
    });

    // Wrap with filter to prevent downstream consumers from seeing tool calls they can't execute
    return new ToolCallFilterAgent(agent);
}

The agent still uses tools internally, but clients only see the final text response. Clean and transparent. What happens in the backend stays in the backend.

Back to LibreChat - KnowledgeSearch now works! The agent searches, finds results, and responds - all without LibreChat ever knowing tools were involved. It's like magic, except it's just careful filtering.

Title Generation with KnowledgeTitleAgent

LibreChat has a feature called titleConvo - it automatically generates titles for conversations using the AI. But my main agents have tools and complex system prompts that are overkill for simple title generation. It's like using a flamethrower to light a candle.

The solution: a dedicated title agent. It's intentionally simple - no tools, no embeddings, just a focused system prompt:

/// <summary>
/// Simple agent for generating conversation titles.
/// No tools, no embeddings - just a basic helpful assistant.
/// Designed for use with LibreChat's title generation feature.
/// </summary>
public static class KnowledgeTitleAgent
{
    private const string TitleSystemPrompt = @"You are a helpful assistant that generates concise, descriptive titles for conversations.
When given conversation content, create a brief title (3-7 words) that captures the main topic or purpose.
Be specific and informative. Avoid generic titles like 'Chat' or 'Conversation'.";

    public static ChatClientAgent Create(IChatClient chatClient, IServiceProvider services, string key)
    {
        return chatClient.CreateAIAgent(new ChatClientAgentOptions
        {
            Id = key,
            Name = key,
            ChatOptions = new ChatOptions
            {
                ConversationId = "global",
                Instructions = TitleSystemPrompt,
            }
        });
    }
}

agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
    AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));

Now update librechat.yaml to use the title agent:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch", "KnowledgeTitle"]
        fetch: false

      titleConvo: true
      titleModel: "KnowledgeTitle"
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Now LibreChat uses KnowledgeTitle specifically for generating conversation titles, while Knowledge and KnowledgeSearch handle the actual conversations.

The Complete Program.cs

Here's what Program.cs looks like after all these changes:

using System.ClientModel;
using Knowledge.Services;
using Knowledge.Shared.Agents;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

var builder = WebApplication.CreateBuilder(args);

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    if (string.IsNullOrWhiteSpace(settings.ApiKey))
    {
        logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets or environment.");
    }

    var options = new OpenAIClientOptions();
    if (!string.IsNullOrEmpty(settings.ApiEndpoint))
    {
        options.Endpoint = new Uri(settings.ApiEndpoint);
    }

    var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);
    var chatClient = client.GetChatClient("gpt-4.1").AsIChatClient();

    // Configure embedding service
    var embeddingClient = client.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();
    builder.Services.AddEmbeddingService(embeddingClient);

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
        AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));
});

// Register background service for embedding processing
builder.Services.AddHostedService<EmbeddingBackgroundService>();

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

var app = builder.Build();

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException) { }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

app.UseRouting();

app.ConfigureKnowledgePipeline();

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

app.MapGet("/", () => Results.Redirect("/swagger"));

app.LogStartupComplete();

app.Run();

That's it. No CORS configuration needed (LibreChat makes server-side requests). No custom request/response models. No manual streaming code. The framework does the heavy lifting - I just wire it up. Sometimes the best code is the code you don't have to write.

The key insights:

Each agent gets its own endpoint via MapOpenAIChatCompletions
Inline middleware handles routing from /v1/chat/completions based on model
ToolCallFilterAgent hides internal tool execution from downstream clients
KnowledgeTitleAgent handles title generation without tool complexity

LibreChat Test

Open LibreChat, select "Agent Framework" as the endpoint, choose a model from the dropdown (Knowledge, KnowledgeSearch, or KnowledgeTitle), and start chatting. You should see:

Streaming responses (that satisfying typing effect)
Tool calls working transparently (KnowledgeSearch uses tools, but you only see the results)
Automatic title generation (thanks to KnowledgeTitle)

Architecture Overview

Let me step back and look at what I've built (and maybe pat myself on the back a little):

%%{init: {"theme": "dark"}}%%
flowchart TB
    subgraph Clients
        LC[LibreChat]
        API[Direct API Calls]
    end

    subgraph "Knowledge API"
        MR[Model Router Middleware]
        E1["/Knowledge/v1/chat/completions"]
        E2["/KnowledgeSearch/v1/chat/completions"]
        E3["/KnowledgeTitle/v1/chat/completions"]
    end

    subgraph Agents
        KA[Knowledge Agent]
        KSA[KnowledgeSearch Agent]
        KTA[KnowledgeTitle Agent]
        TCF[ToolCallFilterAgent]
    end

    subgraph Storage
        PG[(PostgreSQL)]
    end

    LC -->|"/v1/chat/completions"| MR
    API --> MR
    MR -->|"model: Knowledge"| E1
    MR -->|"model: KnowledgeSearch"| E2
    MR -->|"model: KnowledgeTitle"| E3
    E1 --> KA
    E2 --> TCF
    TCF --> KSA
    E3 --> KTA
    KSA -->|Vector Search| PG

The flow is clean:

Request comes in to /v1/chat/completions with "model": "KnowledgeSearch"
Middleware rewrites path to /KnowledgeSearch/v1/chat/completions
Framework routes to the agent, which is wrapped in ToolCallFilterAgent
Agent executes tools internally, filter strips tool content from response
Client sees clean text output

Multiple clients, multiple agents, one simple routing pattern. It's almost... elegant?

Swagger is still available at /swagger for API exploration and testing.

Summary

I've taken the agents from a development-only DevUI to something that can serve real users through a proper chat interface. And I did it with surprisingly little code - plus one hard-won debugging lesson that I'm still a bit salty about.

The main points are:

MapOpenAIChatCompletions does the heavy lifting - one line per agent, full OpenAI compatibility
Each agent gets its own endpoint - clean separation, easy to test directly
Simple inline middleware handles routing - LibreChat sends to /v1/chat/completions, I rewrite to /{model}/v1/chat/completions
Tool-calling agents need filtering - the ToolCallFilterAgent pattern is essential when exposing agents to downstream clients that don't understand your internal tool calls.
Dedicated agents for specific tasks - KnowledgeTitleAgent for titles, KnowledgeSearch for search, Knowledge for general chat

Next Steps

I've got a solid foundation now - persistence, embeddings, semantic search, a proper UI, and automatic title generation. But there's more to explore:

Observability: OpenTelemetry, Jaeger, understanding what's happening at scale
Agent Loop: Exploring the magic behind automated AI Agents
Authentication: Proper API key validation for production deployments (because "meh, whatever" isn't a security strategy)

But first, I'm letting this settle. Play with LibreChat, see how your agents perform with real conversations, and notice what's missing. The best features come from actual use - not from staring at code and imagining what users might want.

See you in the next post. 🚀

The companion repository has been updated with the part/02-connect-librechat branch containing all the code from this post. Check it out on GitHub.

DGX Spark: Hello World

2025-12-31T00:00:00+00:00

What Better Way to End 2025?

So here's how I'm closing out the year: playing with an NVIDIA DGX Spark. Yes, that DGX Spark - the "personal AI supercomputer" that makes my wallet cry but my inner tech nerd do a happy dance.

I have already spent some time testing LibreChat and ComfyUI on it. The courses at stable-diffusion-art.com also helped me get started with image-generation workflows.

And what better way to ring in the new year than with 128GB of unified memory and a Blackwell GPU sitting on my desk? I mean, some people do fireworks. I do neural networks.

(Yes, I'm aware that's possibly the nerdiest New Year's joke ever.)

Let me walk you through my first-day adventures getting this beautiful beast up and running. Fair warning: there may have been moments of childlike excitement, some creative problem-solving (read: frantically searching for a USB-C keyboard), and an unhealthy amount of "let's try this and see what happens."

The Unboxing

There's something special about unboxing new hardware. But unboxing a DGX? That hits different.

The packaging screams premium - NVIDIA clearly understands that when you're dropping serious money on a personal AI supercomputer, presentation matters. Opening the box felt like a tech ritual. Inside, nestled in protective foam, sat this compact powerhouse that somehow packs a Blackwell GPU and 128GB of unified memory into a form factor that actually fits on a desk.

The unit itself is surprisingly compact. I expected something massive and loud, but NVIDIA engineered this thing to be almost civilized. Almost. We'll see how that holds up once I start pushing it with larger models. Everything was included - power cables, documentation, and that unmistakable feeling of "I'm about to have way too much fun with this."

Alright, enough admiring the hardware. Time to make it do things.

The Setup Experience

I went with the local installation method - straightforward enough. Well, mostly. Here's a fun discovery: do you own a keyboard with USB Type-C? No? Neither did I. Fortunately, a laptop docking station saved the day. Crisis averted.

Once the initial setup was complete, first things first - let's give this machine a proper identity:

sudo hostnamectl set-hostname spark-1
sudo reboot

Why spark-1? Because who knows if there'll be a spark-2 someday. Better to be prepared. Future me will thank present me for this foresight. Or curse me for the temptation.

Installing Ollama

After updating the system, I started with something familiar. Ollama has become my go-to for local LLM deployment - it's absurdly simple to set up:

curl -fsSL https://ollama.com/install.sh | sh

Now, I know what you're thinking - "But what about vLLM? What about llama.cpp? What about those fancy self-compiled versions optimized for Blackwell's SM120 architecture?"

Yes, I've seen those posts. Yes, I'll explore them. But that's a future adventure. For now, let's start with the classics and make sure everything actually works before we go down the optimization rabbit hole.

With Ollama ready, time to pull a model:

ollama pull gpt-oss:20b

Could I run the massive 120B parameter models? Absolutely - that's kind of the whole point of having this hardware. But let's walk before we run. Download a smaller model to verify everything works, then let the big ones download overnight while I sleep. Strategy.

Setting Up LibreChat

Running models from the CLI is fine for testing, but I wanted a web interface. I previously used Open WebUI for my self-hosted LLM setup; this time I chose LibreChat, an open-source chat UI that supports local models.

Docker was pre-installed on the DGX Spark (nice touch, NVIDIA). Though my user wasn't in the docker group - but I'll assume you can figure that one out.

mkdir -p ~/workspaces
cd ~/workspaces/
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat/
cp .env.example .env

After some experimentation, I settled on these configuration changes:

Environment Configuration

In .env, the key change:

ENDPOINTS=custom

Docker Compose Override

Create a docker-compose.override.yml for your custom settings, and a librechat.yaml for the LibreChat-specific configuration.

docker-compose.override.yml

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

librechat.yaml

---
version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://host.docker.internal:11434/v1/"
      models:
        default: [
          "gpt-oss:20b"
          ]
        fetch: true
      titleConvo: true
      titleModel: "current_model"
      summarize: false
      summaryModel: "current_model"
      forcePrompt: false
      modelDisplayLabel: "Ollama"

And that's... almost it.

The Reverse Proxy Dance

Here's where it gets slightly more involved. LibreChat enforces secure cookies by default - great for security, annoying when you're hitting F5 every five seconds during development and don't want to re-authenticate each time.

The solution? Set up a reverse proxy with HTTPS. I use Caddy in my home infrastructure because life's too short to manage SSL certificates manually.

chat.int.domain.tld {
    @lan remote_ip 172.16.29.0/24
    handle {
        reverse_proxy @lan http://172.16.2.123:3080
    }
    handle {
        templates
        respond "Access denied, {{.RemoteIP}}" 403
    }
}

This configuration does a few things:

Only allows access from my local network (the 172.16.29.0/24 range)
Proxies requests to the DGX Spark running LibreChat on port 3080
Returns a 403 for anyone trying to access from outside

It's not always open from outside but when it is (to refresh certificates) this is a great and easy way to deal with this.

I've also configured a custom DNS zone in my router to make chat.int.domain.tld resolve correctly, but that's infrastructure stuff for another post.

First Impressions

And just like that - we're live. Quick setup, everything working, ready to chat with local models running on actual Blackwell hardware. The response times are snappy, the interface is clean, and I can already tell this is going to be a fun playground.

Next Steps

Now that the basics are running, it's time to explore what this hardware can actually do. On my list:

Document Understanding: Feed it files and see how well it comprehends them
Voice integration: Testing spoken conversations with local models
Image generation with ComfyUI: Exploring image-generation workflows on the Blackwell GPU. The stable-diffusion-art.com courses have been a useful starting point.

These are just the fundamentals to get comfortable with the platform. But honestly? Between LibreChat's slick interface for chatting with local models and ComfyUI's node-based wizardry for image generation, I've already had more fun than should be legal.

It was a good way to end 2025: experimenting with new hardware and learning what it can do.

Here's to closing out the year with new adventures, and to many more in 2026! 🎉

I will share more results as I continue testing the DGX Spark.

AI Agents in .NET: Building Agentic RAG

2025-12-28T00:00:00+00:00

Welcome back. In the first post, we set up a basic conversational agent. It worked. It responded. It was... fine.

But let's be honest - an agent that can only chat is just a very expensive echo chamber. Today we're giving our agent actual knowledge. It will remember past conversations, search through its own message history, and - most importantly - decide when to use that knowledge.

This is going to be a long one. Grab coffee. Let's build the next piece of the puzzle.

What We're Building

By the end of this post, we'll have:

A PostgreSQL database for persisting messages and embeddings
A second agent (KnowledgeSearch) that searches conversation history
Tool calling so our main agent can invoke KnowledgeSearch when needed
Autonomous decision-making about when to retrieve information vs. just respond

That last point is the key difference between classic RAG and agentic RAG. We're not blindly stuffing context into every prompt. The agent chooses when retrieval helps.

A Quick Word on RAG

RAG - Retrieval-Augmented Generation - has been the go-to pattern for giving LLMs access to external knowledge. The classic approach:

User asks a question
System searches a knowledge base
Retrieved documents get stuffed into the prompt
LLM generates a response using that context

It works. But it's also... dumb? Every query triggers retrieval, whether needed or not. Ask "What's the capital of France?" and you're still embedding the question, searching vectors, retrieving documents. Wasteful.

Agentic RAG flips this. The agent has tools for retrieval and decides when to use them. Simple questions get simple answers. Complex questions trigger the agent to go digging. Much more elegant.

Heads up: There's a whole universe of RAG variations out there - hybrid RAG combining vector search with full-text search (FTS), reranking strategies, query expansion, and more. If you go down the rabbit hole, you'll find dozens of ways to improve retrieval quality. We're intentionally skipping all of that here to focus on the agentic part - how an agent decides when and how to retrieve. Once you grok that, feel free to explore the retrieval optimizations.

Enough theory. Let's write some code.

Database Foundation

Our agent needs a place to store things - messages, embeddings, knowledge. PostgreSQL with pgvector gives us a solid foundation.

The Schema

We're keeping it simple: messages for chat history, embeddings for semantic search.

%%{init: {
  "theme": "dark",
  "themeVariables": {
    "fontFamily": "Jetbrains Mono",
  },
  "themeCSS": [
    ".er.relationshipLine { stroke: #858585; }",
    ".er.relationshipLabel { fill: #bbbbbb; }",
    ".er.relationshipLabelBox { fill: transparent; }",
    ".er.entityBox { fill: #252526; stroke: #303031; }",
    "[id^=entity-messages] .er.entityBox { fill: #1e3a5f; stroke: #5abae0; }",
    "[id^=entity-embeddings] .er.entityBox { fill: #451a03; stroke: #f59e0b; }"
    ]
}}%%
erDiagram
    messages ||--o| embeddings : "has"
    messages {
        uuid id PK
        uuid conversation_id
        uuid embedding_id FK
        varchar role
        varchar author_name
        text content
        bigint sequence_number
        timestamp created_at
    }
    embeddings {
        uuid id PK
        varchar source_type
        uuid source_id
        text content
        vector vector_1536
        timestamp created_at
    }

A few notes:

conversation_id: Groups messages by conversation/session - indexed for fast retrieval
role: Maps to ChatRole.Value from Microsoft.Extensions.AI (user, assistant, system, tool)
sequence_number: Auto-assigned by a database trigger - ensures correct ordering
source_type: Polymorphic pattern - can reference Message or any future entity (e.g., DocumentChunk)
vector_1536: 1536-dimension embedding from OpenAI's text-embedding-3-small

The DbContext

Entity Framework Core handles the mapping. The key thing we need is pgvector support:

// KnowledgeDbContext.cs
modelBuilder.HasPostgresExtension("vector");

This single line enables the vector data type in PostgreSQL. Without it, EF Core won't know what to do with our embedding vectors.

For the Embedding entity, we tell EF Core the exact column type:

// KnowledgeDbContext.cs
entity.Property(e => e.Vector)
      .HasColumnType("vector(1536)");

The rest is standard EF Core configuration - indexes on ConversationId (our primary query pattern), composite index on ConversationId + SequenceNumber for ordered retrieval, and SourceType + SourceId on embeddings for fast lookups.

Don't skip the indexes. Without them, you're doing full table scans.

Wiring It Up

Database registration goes into our extension method. The important choice: AddDbContextFactory instead of AddDbContext.

// ServiceCollectionExtensions.cs
services.AddDbContextFactory<KnowledgeDbContext>(options =>
{
    options.UseNpgsql(connectionString, npgsqlOptions =>
    {
        npgsqlOptions.UseVector();  // Enable pgvector
    });
});

Why the factory? Our message store and agents live outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context.

Migration Time

EF Core migrations version our schema:

cd src/Knowledge

# Create the migration
dotnet ef migrations add InitialCreate --project ../Knowledge.Shared --output-dir Migrations

# Apply it
dotnet ef database update --project ../Knowledge.Shared

We also add a trigger migration for auto-incrementing sequence numbers:

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE OR REPLACE FUNCTION assign_message_sequence_number()
    RETURNS TRIGGER AS $$
    BEGIN
        SELECT COALESCE(MAX(sequence_number), 0) + 1
        INTO NEW.sequence_number
        FROM messages
        WHERE conversation_id = NEW.conversation_id;
        RETURN NEW;
    END;
    $$ LANGUAGE plpgsql;
    """);

migrationBuilder.Sql("""
    CREATE TRIGGER trg_messages_sequence_number
    BEFORE INSERT ON messages
    FOR EACH ROW
    WHEN (NEW.sequence_number = 0 OR NEW.sequence_number IS NULL)
    EXECUTE FUNCTION assign_message_sequence_number();
    """);

This assigns sequence numbers per conversation. The WHERE conversation_id = NEW.conversation_id ensures each conversation has its own sequence. For high-concurrency production use, consider using a proper sequence/identity instead of MAX().

The Conversation Workaround

Before we get to the message store, there's a wrinkle. The framework's DevUI doesn't pass AgentThread information to custom ChatMessageStore implementations. No thread ID means no way to group messages by conversation using the framework's intended abstractions.

We could give up on persistence entirely. Or we could be pragmatic.

The workaround is dead simple: generate a conversation ID once at startup.

// ConversationWorkaround.cs
public static class ConversationWorkaround
{
    public static Guid CurrentConversationId { get; } = Guid.NewGuid();
}

One GUID, initialized once when the application starts, shared for the lifetime of the process. Every message gets tagged with that ID. Restart the app? New ID, new conversation.

We add a corresponding ConversationId column to our Message entity - just a Guid property that gets persisted alongside the role, content, and sequence number.

The Message Store

With our workaround in place, the ChatMessageStore implementation becomes straightforward. The framework calls AddMessagesAsync after each exchange, and GetMessagesAsync when loading history.

The key insight: we use IDbContextFactory<KnowledgeDbContext> instead of injecting a DbContext directly. Why? The store lives outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context - no connection leaks, no stale entity tracking.

When adding messages, we tag each one with ConversationWorkaround.CurrentConversationId:

// KnowledgeChatMessageStore.cs
var message = new Message
{
    Id = Guid.TryParse(chatMessage.MessageId, out var id) ? id : Guid.NewGuid(),
    ConversationId = ConversationWorkaround.CurrentConversationId,
    Role = chatMessage.Role.Value,
    AuthorName = chatMessage.AuthorName,
    Content = chatMessage.Text ?? string.Empty,
    SequenceNumber = 0,  // Trigger auto-assigns
    CreatedAt = chatMessage.CreatedAt?.UtcDateTime ?? DateTime.UtcNow
};

When retrieving, we filter by that same ID:

// KnowledgeChatMessageStore.cs
var messages = await dbContext.Messages
    .Where(m => m.ConversationId == conversationId)
    .OrderBy(m => m.SequenceNumber)
    .ToListAsync(cancellationToken);

This keeps each app instance isolated. Messages from yesterday's debugging session don't pollute today's conversation.

Why This Workaround?

The ideal solution would use the framework's AgentThread abstraction - each thread gets its own conversation, the UI manages thread creation, everything Just Works™. But DevUI doesn't pass thread information to custom stores yet.

Good news: our ChatMessageStore does get called. Messages persist. The agent loads context on startup. The workaround gives us:

Per-instance conversations: Each app restart starts fresh
Persistent context: Within a session, the agent remembers everything
Future-proof schema: When DevUI supports threads, we swap ConversationWorkaround.CurrentConversationId for the real thread ID

We've opened issue #3000 to track proper thread support. For now, this gets the job done.

Embeddings

Before building the KnowledgeSearch agent, it helps to understand embeddings, which are the basis of semantic search. If you already know how they work, you can skip this section.

This section covers the theory, but we're not just hand-waving. As we go, we'll be building toward our second agent that can search through conversation history and return relevant context.

The Big Reveal

An embedding is just a list of numbers. That's it. That's the tweet.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> B["[0.021, -0.034, 0.089, 0.012, ..., -0.045]"]
    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#252526,stroke:#303031,color:#bbbbbb

When you feed text into an embedding model, it spits out a vector - 1536 floating-point numbers for OpenAI's text-embedding-3-small. These numbers encode the meaning of the text. Not the letters, not the spelling - the actual semantic content.

The magic? Similar meanings produce similar numbers.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> V1["[0.021, -0.034, 0.089, ...]"]
    B["🐈 kitten"] --> V2["[0.019, -0.031, 0.092, ...]"]
    C["🗳️ democracy"] --> V3["[-0.067, 0.142, -0.023, ...]"]

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style C fill:#451a03,stroke:#f59e0b,color:#fff
    style V1 fill:#252526,stroke:#303031,color:#bbbbbb
    style V2 fill:#252526,stroke:#303031,color:#bbbbbb
    style V3 fill:#252526,stroke:#303031,color:#bbbbbb

See how "cat" and "kitten" have similar-ish numbers, while "democracy" is completely different? That's semantic similarity, encoded as math.

The "magic" demystified: This is the whole secret behind AI "understanding" - it's just numbers. There's no mystical intelligence, no consciousness pondering the nature of cats. Just insanely clever linear algebra operating in 1536-dimensional space. Once you see it, you can't unsee it. Beautiful, really.

Where Things Live in Vector Space

Imagine plotting these vectors in space. The real vectors have 1,536 dimensions, but a three-dimensional sketch is enough to show the idea of clusters and similarity scores.

%%{init: {
  "theme": "dark"
}}%%
flowchart LR
    subgraph Pets[" "]
        A[cat]
        B[kitten]
    end
    subgraph Civics[" "]
        D[democracy]
        E[parliament]
    end

    A ---|"0.94"| B
    A -.-|"0.31"| D
    D ---|"0.89"| E

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style D fill:#451a03,stroke:#f59e0b,color:#fff
    style E fill:#451a03,stroke:#f59e0b,color:#fff

Similar concepts cluster together. Words about pets huddle in one corner, political terms in another. In the real 1536-dimensional space, these relationships become incredibly nuanced - the model captures categories, analogies, context, even vibes. The scores on the edges are cosine similarities: higher numbers mean those meanings live closer together.

This is why semantic search works. Ask "how do I create an agent?" and the system finds documents about "instantiating agents" and "agent initialization" - different words, same neighborhood in vector space.

How "Close" Are Two Vectors?

We use cosine similarity - basically measuring the angle between two arrows in space.

Similarity = 1: Identical meaning (same direction)
Similarity = 0: Unrelated (perpendicular)
Similarity = -1: Opposite meaning (opposite direction)

You don't need to understand the math. Just know: higher number = more similar meaning. When we search our knowledge base, we're finding the vectors that point in roughly the same direction as the query.

%%{init: {"theme": "dark"}}%%
flowchart LR
    subgraph Query
        Q["How do I build an agent?"]
    end
    subgraph Results["Top Matches (by similarity)"]
        R1["0.94 - Creating your first agent"]
        R2["0.91 - Agent initialization guide"]
        R3["0.87 - Setting up agent tools"]
        R4["0.34 - PostgreSQL connection strings"]
    end
    Q --> R1
    Q --> R2
    Q --> R3
    Q -.-> R4

    style Q fill:#1e3a5f,stroke:#5abae0,color:#fff
    style R1 fill:#064e3b,stroke:#10b981,color:#fff
    style R2 fill:#064e3b,stroke:#10b981,color:#fff
    style R3 fill:#064e3b,stroke:#10b981,color:#fff
    style R4 fill:#451a03,stroke:#f59e0b,color:#fff

The PostgreSQL doc isn't wrong, it's just pointing in a completely different direction. Low similarity score, doesn't make the cut.

The Model We'll Use

OpenAI offers several embedding models:

Model	Dimensions	Use Case
`text-embedding-3-small`	1536	Most applications
`text-embedding-3-large`	3072	When you need more context
`text-embedding-ada-002`	1536	Legacy

We'll use text-embedding-3-small. It's cheap, fast, and good enough for most use cases. The larger model is more accurate but costs more - classic tradeoff. Start small, upgrade if you need to.

Now the question becomes: where do we store 1536 floating-point numbers per piece of text, and how do we search them efficiently?

pgvector Setup

PostgreSQL with pgvector gives us a proper vector database without leaving our existing stack. No separate Pinecone or Weaviate instance to manage.

Enabling the Extension

First, we need pgvector enabled in our database. Connect to PostgreSQL and run:

CREATE EXTENSION IF NOT EXISTS vector;

This installs the vector data type and operators. You only need to do this once per database. If you're using my dev container template, this is already handled in the database initialization scripts.

Verify it worked:

SELECT * FROM pg_extension WHERE extname = 'vector';
-- Should return one row showing the vector extension

The Embedding Entity

We want a generic approach - store embeddings for any content type (messages, documents, whatever). The key property:

// Embedding.cs
public Vector Vector { get; set; } = null!;  // pgvector's native type

We use pgvector's native Vector type instead of float[]. The Pgvector.EntityFrameworkCore package handles the mapping between C# and PostgreSQL.

The entity also tracks what was embedded via SourceType + SourceId - a poor man's polymorphic association. Not elegant, but flexible. We can add new source types (documents, code snippets) without schema changes.

We also store the original Content alongside the vector. Why? When we retrieve matches, we need the actual text to show. And if embeddings get stale, we can re-generate from the stored content.

EF Core Configuration

We already covered the key line in Section 1 - HasColumnType("vector(1536)"). The dimension must match your embedding model. OpenAI's text-embedding-3-small produces 1536 dimensions, so that's what we use.

Indexing for Speed

Without an index, similarity search scans every row - fine for 1,000 embeddings, catastrophic for 1,000,000. HNSW (Hierarchical Navigable Small World) gives us logarithmic search time.

We create the index via a migration (we include this in our AddCustomTriggers migration):

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE INDEX IF NOT EXISTS ix_embeddings_vector_cosine
    ON embeddings
    USING hnsw (vector vector_cosine_ops);
    """);

Breaking this down:

hnsw: The index algorithm - builds a graph structure for fast nearest neighbor search
vector_cosine_ops: Use cosine distance (1 - cosine similarity) as the metric
Creation time: ~1-2 seconds per 10,000 vectors on my laptop

The tradeoff: HNSW uses more memory and takes longer to build, but queries are dramatically faster. For a RAG system, this is always worth it.

Embedding Messages

Time to give our agent some actual knowledge. Instead of indexing external documentation, we're embedding our own conversation history - every message becomes searchable.

Why Messages?

We need something to embed, and chat messages are already there - no external datasets, no document ingestion pipelines, no extra setup. It's demo content that generates itself as you use the agent.

Important distinction: This is not the same as Microsoft.Agents.AI.Memory.ChatHistoryMemoryProvider, which provides memorable context during agent invocation (think: short-term working memory for the current conversation). What we're building is long-term semantic search over historical content. Different problems, different solutions.

The Chunking Problem (Or Not)

For large documents, chunking is essential - split into smaller pieces, embed each one. But messages are already bite-sized. A typical chat message is well under our embedding model's context limit.

We'll embed messages as-is. No chunking needed. If you later want to add document indexing (PDFs, markdown files, whatever), you'd apply chunking:

Fixed size: Every chunk is N tokens. Simple but might split mid-sentence.
Paragraph-based: Split on natural boundaries. Preserves context but uneven sizes.
Semantic: Use the LLM to identify logical sections. Expensive but smart.

For documents, fixed size with overlap (500 tokens, 50 token overlap) is the standard. But for messages, we skip this entirely.

The Embedding Service

We wrap IEmbeddingGenerator<string, Embedding<float>> from Microsoft.Extensions.AI in a simple service. The key conversion:

// EmbeddingService.cs
var result = await _embeddingGenerator.GenerateAsync(text, cancellationToken);
return new Vector(result.Vector.ToArray());

Text goes in, pgvector Vector comes out. The service handles the conversion from the AI library's float array to pgvector's native type. Nothing fancy - just a thin wrapper to keep the embedding generation consistent across the app.

Background Processing

We could embed messages synchronously when they're saved, but that blocks the chat response. Instead, a background service picks up unprocessed messages every 10 seconds.

The trick is using Message.EmbeddingId as both a foreign key and a processing flag:

// EmbeddingBackgroundService.cs
var pendingMessages = await dbContext.Messages
    .Where(m => m.EmbeddingId == null)  // Not yet embedded
    .Where(m => !string.IsNullOrEmpty(m.Content))
    .OrderBy(m => m.SequenceNumber)
    .Take(10)
    .ToListAsync(cancellationToken);

For each message, we generate the embedding and link it back. Once EmbeddingId is set, that message won't be picked up again.

No chunking, no complexity. Message goes in, vector comes out, gets stored. The SourceType = "Message" links back to the original - we'll use this when searching.

The KnowledgeSearch Agent

Once the embeddings are generated, the KnowledgeSearch agent can use them to search the conversation history by meaning.

Why an Agent Instead of a Simple Tool?

You could just wire up a tool function. But wrapping it in an agent brings benefits:

Clear separation: Search logic lives in its own class, testable in isolation
Dependency injection: Proper lifetime management for database contexts and services
Composability: Later, we can add more specialized agents (DocSearch, WebSearch, etc.)

This is the "agentic" part of agentic RAG - agents with tools, each specialized for their task.

The Implementation

The flow is straightforward: embed the query, search pgvector, format results.

First, we embed the search query using the same model that embedded our messages:

// KnowledgeSearchAgent.cs
var queryVector = await _embeddingService.EmbedAsync(query);

The vector search uses pgvector:

// KnowledgeSearchAgent.cs
var results = await dbContext.Embeddings
    .Where(e => e.SourceType == "Message")
    .Select(e => new
    {
        Embedding = e,
        Distance = e.Vector.CosineDistance(queryVector)
    })
    .Where(x => x.Distance <= (1 - DefaultMinScore))  // DefaultMinScore = 0.40
    .OrderBy(x => x.Distance)
    .Take(DefaultTopK)  // DefaultTopK = 10
    .ToListAsync();

A few notes:

CosineDistance() returns distance (0 = identical, 2 = opposite), not similarity. Lower is better.
Threshold of (1 - 0.40) means we want at least 40% similarity. Tweak DefaultMinScore based on your use case.
IDbContextFactory gives us a fresh context per search - the agent is a singleton, but each query gets its own connection.

Finally, we fetch the actual messages and format them with timestamps. The timestamps matter - they help the LLM understand recency.

The pgvector Query

EF Core translates this LINQ query to:

SELECT e.*, e.vector <=> @queryVector AS distance
FROM embeddings e
WHERE e.source_type = 'Message'
  AND e.vector <=> @queryVector <= 0.6  -- 1 - DefaultMinScore
ORDER BY e.vector <=> @queryVector
LIMIT 10;

The <=> operator is pgvector's cosine distance. Lower distance = better match. The HNSW index we created earlier makes this logarithmic instead of linear - critical at scale.

Wiring It Up

Now we connect everything in AgentFactory and Program.cs.

The Agent Factory

Wiring the tool is the key step. We use AIFunctionFactory.Create() to turn our instance method into something the agent can call:

// AgentFactory.cs
var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

return chatClient.CreateAIAgent(new ChatClientAgentOptions
{
    Id = key,
    Name = key,
    ChatOptions = new ChatOptions
    {
        ConversationId = "global",
        Instructions = KnowledgeSearchSystemPrompt,
        Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync)],
        ToolMode = ChatToolMode.Auto
    }
});

The [Description] attributes on our method and parameters become the tool's schema - the LLM sees them and knows what the tool does and what arguments it needs.

ToolMode = ChatToolMode.Auto is important. It tells the model to decide when to use tools, rather than always using them or never using them.

The system prompt is equally crucial. We tell the LLM when to use the tool:

DECISION FRAMEWORK:
- For general knowledge (math, common facts): Answer directly without tools
- For recall questions ('did we discuss X?'): Use SearchConversationHistory
- When unsure if something was discussed: Search first rather than guessing

Without this guidance, models either never use tools or use them for everything. The prompt teaches restraint.

Registration in Program.cs

The key registration:

// Program.cs
builder.Services.AddSingleton<KnowledgeSearchAgent>();

Why singleton? The agent factory resolves from the root provider during startup. This is safe because KnowledgeSearchAgent only depends on singletons (IEmbeddingService, ILogger) and factories (IDbContextFactory) - no scoped services leaking through.

The rest follows the same pattern we established: AddAIAgent with factory delegates, AddHostedService for the background embedding processor.

Before and After

Let's see the difference:

Without RAG:

User: "What did we discuss about database indexes?" Agent: "I don't have memory of our past conversations..."

With KnowledgeSearch:

User: "What did we discuss about database indexes?" Agent: calls SearchConversationHistory("database indexes") Agent: "Based on our earlier conversation, we discussed adding indexes for ConversationId and the composite index for ordered retrieval..."

Night and day.

Summary

We've covered a lot of ground today, but we're still just scratching the surface.

We learned how to take abstract concepts like embeddings and store them in an actual database using pgvector. We saw how to consume that knowledge by building a specialized agent that can perform semantic searches over our own conversation history.

Along the way, we touched on the importance of database persistence, the nuances of tool calling with AIFunctionFactory, and how to manage agent lifetimes in a .NET application. We also explored chunking and more advanced RAG strategies like hybrid search and reranking - topics that are definitely worth exploring as you dive deeper into the world of AI.

The full code is on the part/01-agentic-rag branch. Clone it, run it, break it, and most importantly, make it your own.

Microsoft's official examples are also worth reading. The framework implements some features, including search, with higher-level abstractions such as TextSearchProvider. I used the lower-level approach here to make each step visible.

Here are some examples worth checking in the Microsoft Agent Framework repository:

Getting Started on GitHub

Agent_Step03_UsingFunctionTools/Program.cs
Agent_Step06_PersistedConversations/Program.cs
Agent_Step07_3rdPartyThreadStorage/Program.cs
Agent_Step12_AsFunctionTool/Program.cs
AgentWithRAG/*

Next Steps

We now have an agent that can remember and retrieve earlier conversations.

The next step is the Agent Loop. Instead of a single request and response, the agent can act, observe the result, and adjust its next step until the task is complete. This pattern is the basis for more autonomous coding assistants.

As these agents become more autonomous, we also need to know exactly what they're thinking. That's why we'll be diving into Observability and tracing so we can peek inside the "black box" and see every tool call, every reasoning step, and every decision the agent makes in real-time.

We're moving from "chatbots" to "collaborators." I'll see you in the next one as we start closing the loop. 🚀

AI Agents in .NET: Let's Build Something Smart

2025-12-21T00:00:00+00:00

Welcome to a new blog series about building AI agents in .NET.

Yes, you read that right - I just said .NET. Not Python. C#. Curly braces. Strong typing. With drums and trumpets.

Over the coming posts, we'll explore the Microsoft Agent Framework, build actual agentic systems, and - most importantly - have some fun doing it. This first post sets the stage: why I'm doing this, what we're building, and how to get started with the companion repository.

Here is how to get started.

Why, You Ask?

Honestly? I got a little restless. Every AI agent tutorial out there follows the same well-worn path:

"Build a weather agent!" - Revolutionary stuff. Though I hear windows also exist.
"Spam detection with AI!" - Gmail's been doing this since 2004.
"Customer service chatbot!" - Oh good, we definitely need more of those.

These examples are useful for learning the basics, but I wanted to build something closer to a real application.

This series is about building agents that are genuinely smart, genuinely fun, or ideally both. No boring examples. No wrapping API calls in agent clothing and calling it intelligent.

As for the language choice - I've always been a C-family person. Python is lovely for what it does, but give me curly braces and strong typing any day. When Microsoft released the Agent Framework for .NET? Yeah, that got me genuinely excited. First-class AI agents in C#. Native support, proper tooling, the whole package.

The Microsoft Agent Framework

So what exactly are we working with? The framework comes with everything you need to build proper agentic systems:

Native C# support (obviously)
A beautiful DevUI for testing and debugging your agents - still in preview and missing some Python-side features, but it gets the job done
Built-in patterns for common agentic scenarios (the fun stuff)
Integration with the broader .NET ecosystem (finally!)

And that's what this blog series is all about.

About DevUI

Speaking of DevUI - if you head over to Microsoft's documentation and switch to the C# tab, you're greeted with this gem:

"DevUI documentation for C# is coming soon. Please check back later or refer to the Python documentation for conceptual guidance."

Ah yes, the classic "refer to Python" move. You know, the language we specifically chose not to use for this series? The irony isn't lost on me. But hey, I'm not bitter - I'm just impressed they managed to ship a working DevUI before the documentation. That's actually kind of bold.

The DevUI is a useful web interface for chatting with agents and inspecting their behavior during development. It does not replace proper tracing with tools such as OpenTelemetry and Jaeger, but it works well for quick iteration and debugging. I will cover observability separately in a later post.

The Knowledge Repository

To support this series, I've created a companion repository called Knowledge. I briefly considered "AI-Stuff-I-Throw-Together-At-2AM" but that didn't seem like a good fit. So I thought about it - I'm deepening my own knowledge about AI as I create this series, and hopefully you'll gain some knowledge along the way too. Yeah, let's face it: Knowledge is simple. Sometimes simple works.

The repository is structured as a progressive learning path. Each branch builds on the previous one, taking you from zero to building sophisticated agentic systems. Here's what we're working with:

Branch	Topic	What You'll Learn	Codespace
`main`	Repository & Hello World Agent	Project setup, DevUI, your first conversational agent

More branches will be added as the series progresses. And honestly? That Codespaces button is kind of magical - click it, grab a coffee, and come back to a fully configured dev environment. No setup, no dependencies, just ready to go. I still find that ridiculously cool.

Star the repo if you want to follow along!

Development Environment

You've got two options here - pick whichever fits your workflow.

Dev Container Setup

First things first: reproducible development environments. The repository includes a .devcontainer configuration with:

.NET 10
PostgreSQL with pgvector for when we get into embeddings and semantic search
All the tooling pre-configured

Just open the repo in VS Code, click "Reopen in Container," and you're ready to go. The classic "works on my machine" problem? Solved.

You can also open it in a Codespace and work entirely in the browser without a local setup.

Classic

And for those of you rolling your eyes at all this container and cloud stuff - fair enough. Install the .NET 10 SDK, fire up VS Code or Visual Studio, clone the repo, and just go. Sometimes the old ways are the best ways. That said, you'll want to get PostgreSQL with pgvector set up sooner rather than later - we'll need it for embeddings and semantic search in upcoming posts.

What's on the Main Branch?

Let me walk you through what you'll find when you clone the repo. The main branch sets up everything you need to hit the ground running with AI agent development.

Project Structure

The solution is organized into two projects:

Knowledge - The main web application that hosts our agents and the DevUI
Knowledge.Shared - Shared configuration, extensions, and utilities

This separation keeps things clean as we add more complexity in future posts.

Configuration Done Right

One thing I'm particular about is handling configuration properly. In Knowledge.Shared, we have a KnowledgeSettings class that gives us strongly-typed access to our config values.

The important bits are these two properties:

public string ApiKey { get; set; } = string.Empty;

public string ApiEndpoint { get; set; } = string.Empty;

ApiKey is where your OpenAI (or compatible) API key goes. ApiEndpoint is optional - leave it empty and we'll hit OpenAI's default endpoint, or set it to point at Azure OpenAI, a local model, whatever you need.

Now, you definitely don't want to hardcode API keys in your source code. That's how keys end up on GitHub and suddenly you're funding a stranger's LLM experiments. Instead, we use .NET User Secrets:

cd src/Knowledge
dotnet user-secrets set "Knowledge:ApiKey" "your-api-key-here"

Your key stays on your machine, outside of source control. Sleep well at night.

Wiring Up the Agent

The following sections walk through Program.cs piece by piece.

First, the imports - nothing too surprising here:

using System.ClientModel;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.DevUI;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

We're pulling in the Agent Framework (Microsoft.Agents.AI.*), Microsoft's AI abstractions (Microsoft.Extensions.AI), and the official OpenAI client. Standard .NET web app stuff otherwise.

Next, we create our builder and call into our configuration extension:

var builder = WebApplication.CreateBuilder(args);

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ...
});

ConfigureKnowledgeDefaults is a helper method in our shared project. It handles loading appsettings.json, binding it to our KnowledgeSettings type, and then gives us a callback where we can access both the settings and a logger. This keeps Program.cs clean while still giving us full control.

Inside that callback, we set up OpenAI. First, a sanity check:

if (string.IsNullOrWhiteSpace(settings.ApiKey))
{
    logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets.");
}

Better to warn loudly than fail silently.

Then we create the OpenAI client options. If a custom endpoint is configured, we use it:

var options = new OpenAIClientOptions();

if (!string.IsNullOrEmpty(settings.ApiEndpoint))
{
    options.Endpoint = new Uri(settings.ApiEndpoint);
}

This is what lets you swap between OpenAI, Azure OpenAI, or even a local model running through something like Ollama with an OpenAI-compatible API.

Now we create the actual client and register it with dependency injection:

var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);

builder.Services.AddChatClient(client.GetChatClient("gpt-4.1").AsIChatClient());

GetChatClient("gpt-4.1") gets us a chat client for that specific model. .AsIChatClient() wraps it in Microsoft's IChatClient abstraction, which is what the Agent Framework expects. Using this abstraction means we could swap out OpenAI for any other provider without changing our agent code.

And finally - the actual agent registration:

builder.AddAIAgent("Knowledge", "You are a helpful agent named Knowledge.");

That's it. One line. We give it a name and a system prompt, and the framework handles the rest. We'll make this more sophisticated in future posts, but for a "hello world" agent, this is all you need.

Finishing the Pipeline

After our configuration callback, we register a few more services:

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

These set up the Agent Framework's handlers for OpenAI's responses and conversations API patterns.

Then we build the app and configure the HTTP pipeline:

var app = builder.Build();

app.ConfigureKnowledgePipeline();

ConfigureKnowledgePipeline is another shared helper - it sets up logging, error handling, and other middleware that we'll want across all our experiments.

Finally, we map our endpoints:

app.MapOpenAIResponses();
app.MapOpenAIConversations();
app.MapDevUI();

app.MapGet("/", () => Results.Redirect("/devui/"));

app.Run();

MapOpenAIResponses() and MapOpenAIConversations() expose endpoints that follow OpenAI's API patterns. MapDevUI() enables the Agent Framework's built-in developer interface.

That last MapGet just redirects the root URL to the DevUI. Because when you're developing agents, that's where you want to be.

Running the Application

Once configured, getting started is simple:

dotnet run --project src/Knowledge

Navigate to http://localhost:5000/devui and you'll see the DevUI - a beautiful interface for interacting with your agents, inspecting their reasoning, and debugging when things inevitably go sideways.

Summary

We've covered a lot of ground in this introductory post. You now have:

A companion repository with a reproducible dev container setup
A working "hello world" agent using the Microsoft Agent Framework
Proper configuration with user secrets (no API keys in source control!)
The DevUI for testing and debugging your agents

The foundation is solid. Now comes the fun part.

Next Steps

We've got the foundation in place - a working agent, DevUI, proper configuration. But let's be real: a "hello world" agent isn't going to impress anyone, least of all ourselves.

Next, I will add tools so the agent can perform actions, explore multi-agent scenarios, and use PostgreSQL with pgvector for embeddings and semantic search. A later post will also add proper observability.

But first things first. Step by step.

If you're a .NET developer who's been watching the AI agent space from the sidelines, wondering when C# would get some love - welcome. If you're just someone who's bored of the same old tutorials and wants to see something different - also welcome.

Clone the repo, star it if you're feeling generous, and let's build something that's actually worth building.

See you in the next post. 🚀

How to: Use Docker Remote Contexts with SSH

2025-10-10T00:00:00+00:00

The Problem: When Your Laptop Becomes a Jet Engine

Working on resource-intensive Docker projects often turns laptops into jet engines. The fans spin up, the CPU overheats, and performance degrades significantly. This is especially problematic when working with limited resources - lightweight laptops, VDI sessions, or simply wanting to preserve your hardware.

An SSH-based Docker context keeps the development tools on your local machine while running Docker workloads on a more capable remote host. Your laptop stays responsive and the remote system handles the heavier work.

Step 1: Prerequisites

Before we start, ensure you have:

SSH access configured to your remote Docker host with a proper SSH config entry like:

# ~/.ssh/config
Host docker-remote
  HostName 10.10.10.10
  IdentityFile ~/.ssh/id_rsa
  User ubuntu

Your user is in the docker group on the remote host:

sudo usermod -aG docker $USER

That's all the setup needed! Now let's create the Docker context.

Step 2: Create the SSH-Based Docker Context

Creating the Docker context is incredibly simple when you have SSH properly configured.

Create Your SSH-Based Remote Context

Create a new context using your SSH config host:

docker context create docker-remote --docker host=ssh://docker-remote

That's it! Docker will use your existing SSH configuration, including the hostname, user, and identity file you've already set up.

The beauty of this approach: No daemon.json changes, no TCP configuration, no port forwarding, no firewall rules, no TLS certificate generation - just leverage your existing SSH security infrastructure. Simple and elegant!

Check Your Current Contexts

First, let's see what contexts you currently have:

docker context ls

You'll probably see something like:

NAME              DESCRIPTION                               DOCKER ENDPOINT
default *         Current DOCKER_HOST based configuration   npipe:////./pipe/docker_engine
desktop-linux     Docker Desktop                            npipe:////./pipe/dockerDesktopLinuxEngine
desktop-windows   Docker Desktop                            npipe:////./pipe/dockerDesktopWindowsEngine
docker-remote                                               ssh://docker-remote

Test the Connection

Let's verify everything works:

docker --context docker-remote container ls

If you see your remote containers listed (or an empty list if none are running), congratulations! You're successfully connected to your remote Docker host via SSH.

Step 3: Make It Your Default (Optional)

If you want to use the remote context by default, you can switch to it:

docker context use docker-remote

Now all your docker commands will automatically use the remote host:

docker container ls
# This now runs on your remote host!

Environment Variable Override

For more granular control, you can also use the DOCKER_CONTEXT environment variable:

# Windows PowerShell
$env:DOCKER_CONTEXT = "docker-remote"

# Linux/macOS
export DOCKER_CONTEXT=docker-remote

This approach is particularly useful in CI/CD scenarios or when you want different shells to use different contexts.

Why SSH is Better

Using SSH for Docker remote contexts offers several advantages over TCP:

Security: All communication is encrypted by default
Authentication: Leverages existing SSH keys and authentication methods
No daemon configuration: No need to modify Docker daemon settings on the remote host
Firewall friendly: Uses standard SSH port (22)
Audit trail: SSH logging provides better security monitoring

Switching Between Contexts

Need to switch back to local Docker for something? Easy:

# List available contexts
docker context ls

# Switch to local Docker
docker context use default

# Or use a specific context for one command
docker --context default container ls

Bonus: PowerShell Function for Quick Context Switching

Here's a handy PowerShell function to make switching contexts even easier. Add this to your PowerShell profile for instant remote Docker activation:

Edit Your PowerShell Profile

First, open your PowerShell profile for editing:

notepad $PROFILE

If the file doesn't exist yet, PowerShell will ask if you want to create it - say yes.

Add the Function

Add this function to your profile:

function docker-remote-activate {
    $env:DOCKER_CONTEXT = "docker-remote"
    Write-Host "Docker context switched to remote host"
}

Replace "docker-remote" with whatever you named your remote context.

Save and Reload

Save the file and reload your PowerShell profile:

. $PROFILE

Usage

Now you can instantly activate remote Docker in any PowerShell session:

# Activate remote Docker for this session only
docker-remote-activate

# Now all Docker commands run remotely
docker ps
docker images
docker build .

The beauty of this approach is that it only affects the current PowerShell session - open a new terminal window and you're back to local Docker by default!

Global vs Terminal-Specific Context Switching

You have two ways to switch between local and remote Docker contexts:

Global Context Switching

Affects all terminals system-wide:

# Switch globally to remote
docker context use docker-remote

# Switch back to local
docker context use default

Terminal-Specific Context

Affects only the current terminal session:

# Terminal 1: Remote context
docker-remote-activate
docker ps  # runs remotely

# Terminal 2: Still local context  
docker ps  # runs locally

Whether you prefer global context switching or terminal-specific control, Docker remote contexts give you the flexibility to work exactly how you want.

Summary

Using SSH-based Docker remote contexts provides a secure, simple solution for offloading resource-intensive Docker operations to remote hosts. With just a single command and proper SSH configuration, you can transform your development workflow without compromising security.

The SSH approach eliminates the complexity of daemon configuration while providing enterprise-grade security through encrypted communication and existing authentication infrastructure.

Key Benefits:

Secure by default (encrypted communication)
No daemon configuration required
Uses standard SSH authentication
Works with existing SSH infrastructure
Simple one-command setup

References:

How to extend GitHub Copilot with prompt files

2025-09-10T00:00:00+00:00

Why, You Ask?

Remember when I went absolutely euphoric about vibe coding? Well, that honeymoon phase taught me one crucial lesson: context matters, and you really need to spend time writing good prompts.

At first, I was frantically scribbling prompts in my notes app like some kind of digital hoarder. Then I graduated to GitHub Copilot instruction files, adding rules like "when asked for review, do this and that." But constantly switching between apps and copy-pasting prompts? I'm tired of it.

GitHub Copilot's prompt files solve this by keeping reusable instructions in the repository.

Using `.prompt.md` Files

Prompt files turn your best prompts into reusable slash commands. VS Code gives you two flavors:

Workspace prompts (.github/prompts/): Travel with your repository, perfect for team-shared helpers
User prompts: Stored in your VS Code profile, available everywhere for personal tools

Both become accessible as /my-prompt directly in VS Code chat. Instead of hunting through notes for that brilliant review prompt, you just type /svnscha-blog-review and boom, there it is.

Note: Prompt files are currently in public preview and may change in future releases.

Real-World Example: Blog Review Prompt

Let me show you what this looks like in practice. I use project prefixes for workspace prompts and /my-... for personal ones.

For this blog, I created /svnscha-blog-review - a specialized prompt that understands my writing style:

---
mode: "agent"
description: "Review blog posts for svnscha.github.io with focus on style, grammar, and technical accuracy"
---

# Blog Post Review for svnscha.github.io

You are an expert editor reviewing a blog post for svnscha's technical blog.

Focus on:

## Writing Style & Tone

- Consider using "Why, You Ask?" openings when it makes sense for the topic (not mandatory for all posts)
- Keep the direct, slightly sarcastic but helpful voice
- Ensure smooth transitions between sections
- End posts with a short summary or practical next steps when they add value

## Technical Accuracy

- Verify code examples are correct and practical
- Check that technical explanations are clear and accurate
- Ensure all file paths and commands are properly formatted

## Grammar & Spelling

- Fix any grammatical errors or typos
- Improve sentence structure where needed
- Maintain consistency in technical terminology

## Content Structure

- Ensure headings flow logically
- Verify examples support the main points
- Suggest a brief summary or actionable next steps when appropriate
- Check that the conclusion ties back to the opening

Provide specific, actionable feedback that maintains the author's voice while improving clarity and correctness.

This becomes available as /svnscha-blog-review in VS Code, giving me instant access to a specialized editor that knows my style.

Smart Naming & Location Strategy

The naming convention is simple: project prefixes for workspace prompts, /my-... for personal ones. So /svnscha-blog-review is specific to this blog, while /my-commit works everywhere.

Choose your location based on scope:

Workspace prompts: Team-shared, project-specific helpers
User prompts: Personal tools that follow you across all projects

Dynamic Prompts with Variables

Make your prompts adapt to context with VS Code variables:

# Code Review Prompt

Review the following code in ${file}:

${selection}

Focus on:
- Security vulnerabilities in ${fileBasename}
- Performance implications 
- Code style consistency with ${workspaceFolderBasename} standards

The most useful variables include:

Workspace: ${workspaceFolder}, ${workspaceFolderBasename}
File context: ${file}, ${fileBasename}, ${fileDirname}
Selection: ${selection}, ${selectedText}

For the full list of available variables and advanced features, check out the VS Code prompt files documentation.

Setting Up Your Prompt Arsenal

Getting started is simple:

Workspace Prompts

Create .github/prompts/ in your repository
Add your .prompt.md files
Commit and push - your team now has access

User Prompts

Open Command Palette (Ctrl+Shift+P)
Run "Chat: New Prompt File"
Choose "User profile" for location
Author and save your prompt

Both methods make prompts available with /prompt-name in GitHub Copilot chat. Workspace prompts travel with your repository, while user prompts sync across devices with Settings Sync.

For examples and community contributions, check out the Awesome GitHub Copilot prompts collection.

Summary

Prompt files transform good prompting from an exclusive skill into a shared superpower. Your team gets expert-level guidance, your hotfix deployments get proper review, and your collective wisdom becomes instantly accessible with slash commands.

Next Steps

Start small - Convert your three most-used prompts to .prompt.md files
Choose scope wisely - Workspace prompts for teams, user prompts for personal tools
Use variables - Make prompts dynamic with ${selection}, ${file}, and ${input:variableName}
Follow naming conventions - Project prefixes for workspace, /my-... for user prompts
Explore the community - Check out Awesome GitHub Copilot prompts
Read the docs - VS Code prompt files documentation has the latest features

The main benefit is simple: useful instructions live with the project and can be reused without copying them into every chat.

Get Started with uberAgent for Linux: Enterprise Observability Made Simple

2025-08-26T00:00:00+00:00

uberAgent for Linux Has Arrived

After years of Windows getting all the monitoring love, uberAgent for Linux Technology Preview 1 has arrived - and it's everything we have been waiting for.

I run a multi-site setup with MikroTik routers and WireGuard tunnels connecting my home, coworking space, and cloud infrastructure. Systems such as sso-1, drive-1, and splunk-1 communicate over an internal network through a gateway server. I wanted better visibility into these server workloads: Docker hosts, reverse proxies, service communication, and resource use across the environment.

Having uberAgent finally extend from Windows to my entire Linux infrastructure fills a gap I've been dealing with for years.

Why Linux Infrastructure Monitoring Just Got Interesting

You've got a beautiful Linux infrastructure running critical workloads, but your monitoring looks like Dr. Frankenstein's laboratory. A little Prometheus here, some custom scripts there, maybe some Grafana dashboards that kinda-sorta show you what's happening. You're stitching together metrics from five different tools just to answer simple questions like "Why is this service slow?" or "Which application is hammering my database?"

Meanwhile, your Windows colleagues are living it up with comprehensive uberAgent dashboards that actually make sense.

Not anymore.

Getting Started: Ubuntu Installation

Currently, uberAgent for Linux ships as .deb packages, making Ubuntu (and Debian-based) installations straightforward. Here's how to get it running on your systems.

Prerequisites

Please check the official documentation for the latest instructions.

So, before diving in, ensure your systems have the basics:

sudo apt update
sudo apt install wget unzip

Manual Installation Process

First, extract the uberAgent package from the distribution ZIP:

# Create working directory
mkdir /tmp/uberagent && cd /tmp/uberagent

# Extract the ZIP (assuming you've downloaded it)
unzip uberAgent-Linux-TP1.zip

# Find and install the .deb package
find . -name "*uberagent*amd64*.deb" -exec sudo dpkg -i {} \;

# Fix any dependency issues
sudo apt-get install -f

Configuration Directory Structure

Once installed, uberAgent requires its configuration structure at /etc/uberAgent/. The key files you'll work with:

/etc/uberAgent/uberAgent.conf - Main configuration file
/etc/uberAgent/ - Additional configuration files
/var/log/uberAgent/ - Log files location

Basic Configuration Setup

Download the standard configuration bundle:

# Download the latest config bundle
wget -O /tmp/uberAgent.uAConfig \
  https://github.com/vastlimits/uberAgent-config/raw/refs/heads/version/7.4/config-dist/uberAgent.uAConfig

# Extract to config directory
sudo unzip -o /tmp/uberAgent.uAConfig -d /etc/uberAgent/

Splunk Integration

Edit /etc/uberAgent/uberAgent.conf to configure your Splunk HEC endpoint:

[Receiver]
Name = Splunk
Type = Splunk
Protocol = HTTP
Servers = https://your-splunk-hec-url:8088
RESTToken = your-hec-token-here

Service Management

Start and enable the service:

sudo systemctl enable uberAgent
sudo systemctl start uberAgent

# Check status
sudo systemctl status uberAgent

# View logs
sudo journalctl -u uberAgent -f

Scaling with Ansible: Key Automation Snippets

For larger deployments, Ansible makes this process repeatable across your infrastructure. Here are the essential patterns I use:

Package Installation Task

- name: Install uberAgent from ZIP
  block:
    - name: Transfer and extract ZIP
      copy:
        src: "{{ uberagent_local_zip }}"
        dest: "/tmp/uberagent.zip"
      
    - name: Unarchive ZIP on target
      unarchive:
        src: "/tmp/uberagent.zip"
        dest: "/tmp/uberagent"
        remote_src: yes
        
    - name: Find .deb package
      find:
        paths: "/tmp/uberagent"
        patterns: "*uberagent*amd64*.deb"
        recurse: yes
      register: deb_search
      
    - name: Install via dpkg
      command: dpkg -i {{ (deb_search.files | map(attribute='path') | list)[0] }}
      register: dpkg_install
      changed_when: dpkg_install.rc == 0
      failed_when: dpkg_install.rc not in [0,1]
      
    - name: Fix dependencies if needed
      apt:
        state: present
        update_cache: yes
        name: "*"
      when: dpkg_install.rc == 1

Configuration Deployment

- name: Deploy uberAgent configuration
  block:
    - name: Download config bundle
      get_url:
        url: "{{ uberagent_config_bundle_url }}"
        dest: "/tmp/uberAgent.uAConfig"
        mode: "0644"
        
    - name: Extract configuration bundle
      unarchive:
        src: "/tmp/uberAgent.uAConfig"
        dest: "/etc/uberAgent/"
        remote_src: yes
        extra_opts: ["-o", "-q"]

Splunk Receiver Configuration

- name: Configure Splunk receiver
  block:
    - name: Define Splunk receiver block
      set_fact:
        uberagent_receiver_block: |-
          [Receiver]
          Name = {{ uberagent_receiver_name }}
          Type = Splunk
          Protocol = HTTP
          Servers = {{ uberagent_splunk_hec_url }}
          RESTToken = {{ uberagent_splunk_hec_token }}
    
    - name: Replace existing receiver configuration
      replace:
        path: "/etc/uberAgent/uberAgent.conf"
        regexp: '(?ms)^\[Receiver\]\nName *=.*?\nType *=.*?\nProtocol *=.*?\nServers *=.*?\nRESTToken *=.*?\n'
        replace: "{{ uberagent_receiver_block | regex_replace('\\n', '\n') }}\n"
      register: receiver_replace
      notify: restart uberAgent
      
    - name: Add receiver block if none existed
      blockinfile:
        path: "/etc/uberAgent/uberAgent.conf"
        marker: ";; {mark} ANSIBLE MANAGED RECEIVER BLOCK"
        block: "{{ uberagent_receiver_block }}"
        insertafter: EOF
      when: not receiver_replace.changed
      notify: restart uberAgent

These Ansible snippets give you the foundation - adapt the variables and structure to match your environment and deployment needs.

Performance Impact Analysis

Let's start with the most important question: what does uberAgent actually cost your infrastructure? This analysis shows uberAgent's resource consumption across multiple hosts over a full week of monitoring.

The results are impressive: uberAgent delivers comprehensive monitoring with minimal overhead. You're looking at resource consumption so low that you'll question whether it's actually collecting all that data.

CPU impact: Consistently under 1% across all monitored systems
Memory footprint: Typically 20-50MB per agent - less than a single browser tab

This is monitoring software that enhances your visibility without becoming a performance bottleneck.

Infrastructure Discovery

Your complete infrastructure topology emerges automatically as agents come online. Having a machine inventory I can rely on, next to my Ansible inventory is great. I really like this one.

Network Flow Visualization

Understanding inter-service communication becomes trivial when you can see exactly which services talk to each other and how much traffic flows between them.

Application-Level Troubleshooting

When applications start misbehaving, you get immediate visibility into network-related issues that traditional monitoring tools miss entirely.

Summary

This is it - uberAgent for Linux doesn't just add another platform; it completes the entire monitoring ecosystem.

Think about what this means: your existing Windows and macOS monitoring now gets perfectly extended with comprehensive Linux coverage. We're talking about Linux VDAs running in your Citrix environments, non-VDA Linux desktops handling critical workloads, Linux thin clients connecting to your Citrix infrastructure - suddenly every endpoint in your environment speaks the same monitoring language!

The part I am most interested in is server workloads.

Docker hosts, Kubernetes clusters, database servers, message queues, reverse proxies, microservices, and load balancers can now use the same uberAgent monitoring approach as Windows systems. That makes it possible to view Citrix infrastructure, bare-metal servers, and cloud-native workloads in one place.

This is infrastructure observability done right: one agent, one data format, one set of dashboards covering your entire technology stack from end-user experience down to kernel-level performance metrics. Citrix environments, non-Citrix infrastructure, hybrid cloud setups, on-premises data centers - it's all there, all visible, all making sense together.

The deployment stays effortless (thanks to Ansible automation), performance impact remains minimal, and the insights now span absolutely everything. No more tool sprawl, no more monitoring blind spots, no more wondering if that user complaint is related to the application, the network, or the underlying infrastructure.

Ready to achieve monitoring enlightenment? Deploy this Technology Preview and watch your entire infrastructure transform from a collection of mysterious black boxes into a completely transparent, interconnected system where every component tells its story.

Next Steps

After deploying uberAgent across my infrastructure, I quickly noticed one challenge: data volume. While the insights are invaluable, my home lab generates monitoring data at a pace that exceeds typical residential environments.

With Splunk's free licensing constraints (500MB/day), I am implementing Event Data Filters as a solution and add a optimized data volume configuration. However, I'm already contemplating the next evolution - developing a custom backend infrastructure with purpose-built visualization dashboards specifically optimized for my environment.

This technical challenge would be particularly engaging - balancing comprehensive visibility with resource efficiency. For now, though, the filters keep things manageable while I plan the next iteration of my monitoring architecture.

Disclosure Note: I am a Citrix employee. However, this post represents my personal enthusiasm and experience with the product, not an official company perspective. I wrote this entirely of my own volition because I'm genuinely excited about these capabilities.

A Git feature I should've met sooner!

2025-04-04T00:00:00+00:00

Why, You Ask?

Because I thought I knew Git. Like really. Branches? Merged. Rebased. Cherry-picked. Heck, I've even force-pushed into production (don't judge me). I've danced the git stash tango more times than I care to admit, and I've rage-quit after realizing I checked out the wrong branch with uncommitted changes.

But then-then-I discovered git worktree.

And everything changed.

The Problem With the "Normal" Way™

Let's say you're working on a feature. You're knee-deep in uncommitted changes, and suddenly you need to switch to another branch to hotfix or review something. What do you do?

git stash
git checkout other-branch
Try to remember what you were doing in your branch later.
Forget what you stashed and why.
Cry

This is the standard Git workflow we all just kind of accept. It's chaotic good at best.

Enter: `git worktree`

What if I told you... you could just check out multiple branches at the same time? Each in its own separate folder. No stash. No backflips. No existential dread.

git worktree is a built-in Git feature that lets you:

Check out multiple branches at once
Work on each one in its own directory
Keep your mental state and filesystem intact

Examples

Create a new worktree for a feature branch

git worktree add ../feature-x origin/feature-x

This checks out the feature-x branch (fetched from origin) into a new directory ../feature-x.

If it's a new feature you start locally, do this:

git worktree add ../feature-x -b feature-x

This creates a new local branch feature-x from your current HEAD (usually main) and checks it out into ../feature-x.

Wow. 🥳 No more "wait lemme stash real quick."

Now you can commit your fix, push it, and go back to your mess later. Like a civilized developer.

List all worktrees

git worktree list

Because you will forget what you spun up after the third coffee.

What's the Catch?

Honestly? Not much. A few things to keep in mind:

You can't check out the same branch twice. Git will yell at you. That's fair.

Deleting a worktree is easy: just git worktree remove ../feature-x (the directory) and that's it.

Why You Need This in Your Life

If you're working on multiple features, doing code reviews locally, fixing stuff mid-feature, or just trying to keep your brain from melting-git worktree is the gift you didn't know Git included.

No more stash juggling.
No more "which terminal had which branch again?"
No more "accidentally committed to main" horror stories.

Just clean, parallel workspaces from a single clone.

Use it. Love it. Regret not learning it sooner. I know I did.

Windows: Install integrated OpenSSH Server

2025-04-03T00:00:00+00:00

Tired of everyone SSHing into Linux? Flip the script: SSH into Windows from your Linux box. Works great with VSCode Remote too. Here's how to enable the built-in OpenSSH server on Windows.

Step 1: Check Installed OpenSSH Components

First, open a PowerShell window with administrator privileges. Let's see what's already installed:

Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'

You might see output indicating that the client is installed but not the server:

Name  : OpenSSH.Client~~~~0.0.1.0
State : Installed

Name  : OpenSSH.Server~~~~0.0.1.0
State : NotPresent

Step 2: Install the OpenSSH Server

If the server isn't present, let's bring it on board. Run:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

Step 3: Start and Enable the SSH Server

Now, let's get the sshd service up and running:

Start-Service sshd

And ensure it starts automatically with Windows:

Set-Service -Name sshd -StartupType 'Automatic'

That's it.

C++: How to measure code coverage with lcov and GTest

2025-03-25T00:00:00+00:00

Why, You Ask?

Because you want to know which parts of your C++ code are actually being tested – not just assumed to be. Code coverage isn't about perfection, but about confidence. And with the right setup, you can easily visualize what's being tested and what's quietly collecting dust.

In this guide, we'll walk through:

Setting up lcov and GTest
Writing effective coverage-focused tests
Running the tests and generating reports
Interpreting results and achieving real insight
Automating it all via GitHub Actions

📦 Try It Yourself

Check out the working example repository here:

👉 github.com/svnscha/cpp-coverage-example

It contains:

A minimal MyQueue class
Unit tests using GTest
Full lcov and genhtml integration
A GitHub Actions workflow for automated code coverage with a threshold

1. Install Required Tools

Make sure your environment has:

lcov
A C++ compiler (GCC or Clang)
cmake, ninja
GTest (or install libgtest-dev on Ubuntu)

2. Build with Coverage Instrumentation

To generate coverage data, compile your code with:

--coverage: Coverage instrumentation
-g: Debug information
-O0: No optimization (to avoid inlining, etc.)

🛠 Minimal CMake Snippet

option(ENABLE_COVERAGE "Enable code coverage reporting" OFF)

function(enable_coverage target)
    if(ENABLE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
        target_compile_options(${target} PRIVATE --coverage -O0 -g)
        target_link_options(${target} PRIVATE --coverage)
    endif()
endfunction()

enable_testing()

add_library(MyLibrary ...)
add_executable(MyTests ...)
target_link_libraries(MyTests PRIVATE MyLibrary GTest::gtest_main)

include(GTest)
gtest_discover_tests(MyTests)

enable_coverage(MyLibrary)
enable_coverage(MyTests)

3. Write Tests That Actually Trigger All Code Paths

Here’s a small utility class as an example:

class MyQueue
{
public:
    void Push(int val)
    { 
        _q.push(val); 
    }

    void Pop() 
    {
        if (_q.empty())
            return;
        _q.pop();
    }

    bool IsEmpty() const { return _q.empty(); }

private:
    std::queue<int> _q;
};

Now test both normal and edge cases:

TEST(MyQueueTest, PopWhenEmpty) {
    MyQueue q;
    q.Pop(); // Hit the early return
    EXPECT_TRUE(q.IsEmpty());
}

TEST(MyQueueTest, PushAndPop) {
    MyQueue q;
    q.Push(42);
    EXPECT_FALSE(q.IsEmpty());
    q.Pop();
    EXPECT_TRUE(q.IsEmpty());
}

4. Run Tests and Generate Coverage Report

cmake -B build -DENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build
cd build
ctest --output-on-failure

Then generate the coverage report:

lcov --directory . --capture --output-file coverage.info --rc geninfo_auto_base=1 --ignore-errors mismatch
lcov --remove coverage.info '/usr/*' '*/tests/*' --output-file coverage.filtered.info
genhtml coverage.filtered.info --output-directory coverage-report

Open this in your browser:

build/coverage-report/index.html

Your browser does not support the video tag.

5. Automation

Now, having the coverage report in place is a great start. But it's not enough to just have the coverage report. You need to automate it so that every time you run your tests, you get a detailed report of what was covered and what wasn't.

To get started, you can setup a GitHub workflow with threshold tests, upload the reports or do post-processing on the report.

Either way, the key is to have a way to run tests and generate reports. Here's an example workflow:

Summary

Step	What You Did
1. Install	Set up `lcov`, gtest, gcc, and cmake
2. Build	Compiled with --coverage and no optimizations
3. Test	Hit both happy paths and edge cases
4. Report	Generated detailed HTML coverage report

Conclusion

Code coverage doesn't guarantee perfect tests, but it gives you visibility. When paired with thoughtful test cases (especially edge cases), it helps ensure your code behaves correctly - even when things go sideways.

Even small utility classes deserve this level of care.

And with lcov, you can turn "I think I tested this" into "Yes, this line has been executed 12 times during CI."

Exploring AI: Self Hosted LLM

2025-03-17T00:00:00+00:00

Why, You Ask?

So, I decided to self-host an LLM. Why? Every time you use an online AI model, you're handing over your data to some company. Whether it's casual conversations, coding snippets, or business-related queries, everything you type is potentially being logged, analyzed, or even used to train future models. No thanks.

Instead, I prefer to keep things local. Also, I have an RTX ADA 4000 with 20GB of memory sitting here, so why not put it to good use?

Ollama makes it easy to run LLMs locally. I combine it with Open WebUI for the user interface and Nginx for remote access.

Here is the setup.

Step 1: Install Ollama

Ollama makes deploying LLMs locally ridiculously simple. Here's how to install it:

curl -fsSL https://ollama.com/install.sh | sh

This will install Ollama and set up everything you need to start running models locally. Want to make sure it's working? Just run:

ollama run codellama:13b

If you see an interactive prompt, congrats - you've got a local LLM running!

Step 2: Install Open WebUI

Ollama is great, but a web interface makes it even better. That's where Open WebUI comes in. It gives you a sleek, chat-like interface to interact with your models.

To install Open WebUI manually without Docker, follow these steps:

1. Create a Virtual Environment

python3 -m venv ~/openwebui-venv
source ~/openwebui-venv/bin/activate

2. Install Open WebUI

pip install open-webui

3. Create a Systemd Service

To make sure Open WebUI runs on startup, create a systemd service file:

sudo nano /etc/systemd/system/openwebui.service

Paste the following content:

[Unit]
Description=Open WebUI Service
After=network.target

[Service]
User=$USER
Group=$USER
WorkingDirectory=/home/$USER/openwebui-venv
ExecStart=/home/$USER/openwebui-venv/bin/open-webui
Restart=always

[Install]
WantedBy=multi-user.target

Save and exit, then reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable openwebui.service
sudo systemctl start openwebui.service

Step 3: Reverse Proxy with Nginx

Now, let's make accessing our LLM easier by setting up an Nginx reverse proxy. This way, we can reach Open WebUI without exposing it directly.

Here's a basic Nginx config:

server {
    listen 443 ssl;
    server_name chat.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Reload Nginx with:

sudo systemctl restart nginx

Now, you can access your self-hosted LLM via https://chat.example.com. Fancy.

You Own Your Data Now

One of the biggest advantages of self-hosting an LLM? Your data stays with you.

No sending queries to an external API, no third-party tracking what you're asking, no potential leaks of sensitive information. It's all running on your hardware, fully under your control. Whether you're experimenting with code, processing confidential documents, or just having fun chatting with AI, everything stays local.

Model Sizes & Performance

Of course, different models come with different memory requirements. Here's what I'm running on my RTX ADA 4000 and how much VRAM they use:

NAME             ID              SIZE      PROCESSOR    UNTIL              
codellama:7b     8fdf8f752f6e    9.4 GB    100% GPU     2 minutes from now    
codellama:13b    9f438cb9cd58    15 GB     100% GPU     4 minutes from now    
gemma3:12b       6fd036cefda5    13 GB     100% GPU     4 minutes from now

This means I can comfortably run mid-sized models like codellama:13b while keeping things snappy.

Choosing the Right GPU

Picking the right GPU is all about balancing performance, VRAM, and cost - because, let's be honest, unless you're running an AI research lab, you're not dropping $30,000 on an H100.

Here's a quick breakdown of solid options:

NVIDIA RTX 3090 - Powerful, with 24 GB of VRAM, but it's last-gen. ($$)
NVIDIA RTX 4090 - Even more powerful, with 24 GB of VRAM and better efficiency. ($$$)
NVIDIA RTX 5090 - Even more and more powerful, with 24 GB of VRAM and better efficiency. ($$$$)
NVIDIA RTX 4000 ADA Generation - Less powerful, but 20 GB of VRAM, and a low-profile card. ($)

Now, why the ADA 4000? While the RTX 5090 is the fastest in raw compute power, VRAM is king for training AI models. The ADA 4000's 20 GB VRAM gives you enough room for Stable Diffusion training, larger batch sizes, and AI experiments, without hitting the limits of other consumer GPUs such as 3080 (10 GB).

Performance-wise, the 4090 and 5090 has more horsepower, but for training workloads where memory matters more than raw speed, the ADA 4000 is the more practical and cost-efficient choice. Plus, lower power consumption makes it a better long-term option if you're running AI workloads frequently. Also, the physical size - I mean it's a low profile card. Small, fits perfectly into any case.

For my needs, the RTX 4000 Ada offered a useful balance of VRAM, price, power use, and size.

Example

Asking codellama:13b

Prompt: implement fibonacci in python and also some unit tests using pytest

Your browser does not support the video tag.

Asking gemma3:12b

Prompt: implement fibonacci in python and also some unit tests using pytest

Your browser does not support the video tag.

Summary

With an RTX ADA 4000, Ollama, Open WebUI, and an Nginx reverse proxy, I now have an AI-powered assistant running entirely on my own hardware. No subscriptions, no cloud dependencies, just raw, local AI power. If you're serious about AI and privacy, setting this up is a no-brainer. Give it a try, and let your GPU do some work.

Moving to Fedora: Automating Discord Updates with Ansible

2024-11-15T00:00:00+00:00

Why, You Ask?

So, you've found yourself running Fedora and decided to install Discord, huh? Great choice - Fedora is fantastic. But then you realize Discord's tarball updates are a hassle. Every week, it's the same story: download, extract, and pray you didn't miss a step. Tedious, right?

I use the following Ansible playbook to install and update Discord on Fedora. It handles the repetitive steps and makes the setup easy to reuse on another machine.

Step 1: Understanding the Process

Discord on Linux isn't as straightforward as we'd like. Flatpak is an option, but it can be slow with updates or cause compatibility issues. For those of us who prefer the direct tarball approach, we need a way to automate the mess. With Ansible, we can ensure Discord is always up-to-date with just one command. No more hunting for the latest download link or worrying about cleaning up old versions.

Step 2: The Playbook

Here's an Ansible playbook to make your life easier. It handles everything - downloading the tarball, extracting it to the proper location, and cleaning up afterward.

---
- name: Install and Update Discord on Fedora 41 using Ansible
  hosts: localhost
  become: true
  tasks:
    - name: Ensure /usr/share/discord is removed if it exists
      file:
        path: /usr/share/discord
        state: absent

    - name: Download Discord tarball
      get_url:
        url: "https://discord.com/api/download/stable?platform=linux&format=tar.gz"
        dest: "/tmp/discord.tar.gz"
        mode: "0644"

    - name: Create /usr/share/discord directory
      file:
        path: /usr/share/discord
        state: directory
        mode: "0755"

    - name: Extract Discord tarball to /usr/share/discord
      unarchive:
        src: "/tmp/discord.tar.gz"
        dest: "/usr/share/discord/"
        remote_src: true
        extra_opts: ["--strip-components=1"]
      args:
        creates: "/usr/share/discord/discord"

    - name: Clean up temporary files
      file:
        path: "/tmp/discord.tar.gz"
        state: absent

Step 3: What This Playbook Does

Step 1: If Discord is already installed, it removes the existing files to prevent conflicts.
Step 2: It downloads the latest stable Discord tarball directly from the official API.
Step 3: Creates the required directory at /usr/share/discord.
Step 4: Extracts the tarball into /usr/share/discord, stripping unnecessary folder components.
Step 5: Cleans up temporary files, leaving your system tidy.

A Note About Bash Aliases

If you're like me and love shortcuts, consider adding a bash alias to streamline running the playbook. This way, updating Discord becomes as simple as typing a single command. Here's how you can set it up:

cat ~/.bashrc.d/alias.sh
alias ansible-venv=". ~/repos/ansible/.venv/bin/activate"
alias update-discord="ansible-venv && ansible-playbook ~/repos/ansible/update-discord.yml --connection=local -K"

With this in place:

ansible-venv activates your virtual environment for Ansible.
update-discord runs the playbook with local connection and prompts for sudo permissions when needed.

Now, keeping Discord updated is literally a one-liner. Perfect, right?

Summary

The same playbook handles both the first installation and later updates, so keeping Discord current only takes one command.

So, go ahead - run it, relax, and enjoy Fedora without the hassle. Because let's face it: managing updates manually is so last year.

Moving to Fedora: Automating PowerShell Installation with Ansible

2024-11-15T00:00:00+00:00

Why, You Ask?

I use PowerShell on Fedora for scripting and automation. Installing it manually is fine once, but it becomes repetitive across workstations, VMs, dev containers, and servers.

This Ansible playbook automates the installation and keeps the setup consistent across those environments.

Step 1: The Problem

Installing PowerShell on Fedora involves downloading Microsoft's repository package, registering it, updating the package index, and then installing the actual PowerShell package. It's fine if you're doing it once, but if you have to repeat the process on multiple systems, it quickly becomes a chore.

The solution? Use Ansible to do it for you. Write the playbook once, and it works everywhere - no matter how many machines you're dealing with.

Step 2: The Playbook

Here's the Ansible playbook that automates PowerShell installation on Fedora:

---
- name: Install PowerShell on Fedora 41 using Ansible
  hosts: localhost
  become: yes
  gather_facts: true

  tasks:
    - name: Download Microsoft repository package
      ansible.builtin.get_url:
        url: https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm
        dest: /tmp/packages-microsoft-prod.rpm

    - name: Register Microsoft repository
      ansible.builtin.command:
        cmd: rpm -i /tmp/packages-microsoft-prod.rpm
      args:
        creates: /etc/yum.repos.d/microsoft-prod.repo

    - name: Remove repository package after registration
      ansible.builtin.file:
        path: /tmp/packages-microsoft-prod.rpm
        state: absent

    - name: Update package index
      ansible.builtin.dnf:
        update_cache: yes
        state: latest

    - name: Install PowerShell
      ansible.builtin.dnf:
        name: powershell
        state: present

    - name: Verify PowerShell installation
      ansible.builtin.command:
        cmd: pwsh --version
      register: pwsh_version_output

    - name: Display PowerShell version
      ansible.builtin.debug:
        msg: "Installed PowerShell version: {{ pwsh_version_output.stdout }}"

Step 3: Usage

Running this playbook is straightforward. If you're working with a virtual environment for Ansible, make sure it's activated. Then, execute the playbook locally with the following command:

ansible-playbook /path/to/install-powershell.yml --connection=local -K

Here's a quick breakdown:

ansible-playbook: Runs the playbook.
/path/to/install-powershell.yml: Path to the playbook file.
--connection=local: Executes the playbook on the local machine instead of a remote host.
-K: Prompts for sudo privileges to perform the installation.

With this command, you can easily install PowerShell on your Fedora system without worrying about missing steps.

Summary

With this playbook, installing PowerShell on a new Fedora system takes one command and produces the same setup each time.

So, the next time you're staring down the prospect of yet another manual PowerShell install, let Ansible take care of it. Because honestly, you've got better things to do.

Simplify SSH

2024-10-03T00:00:00+00:00

Why, You Ask?

I was tired of entering my SSH key passphrase every time I connected to a server. The setup below lets ssh-agent remember it for the current terminal session and also keeps host settings in one place.

It's time-consuming and frustrating. I'm tired of it.

Getting Started

So, you've got your shiny new SSH key and every time you want to connect to a server, you're greeted with that ever-familiar password prompt. Sure, typing your SSH key passphrase every time is good for security, but, come on - who wants to do that? I mean, I don't know about you, but I've got enough passwords to remember without constantly dealing with this nonsense.

Let's save ourselves some time and effort by getting the SSH agent to remember our keys for us. That way, you can just run your commands like the seasoned developer you are without worrying about the whole "password entering" thing every single time.

Step 1: Start the SSH Agent

First things first - let's get the SSH agent up and running. It's like your personal SSH butler, here to remember your key so you don't have to.

Open up your terminal and type:

eval $(ssh-agent -s)

Boom! Now the agent is running in the background, ready to hold your keys like the responsible little daemon it is.

Step 2: Add your key to the SSH Agent

Now that the agent is up, let's give it your key. You only need to do this once per session, and the agent will keep it ready for you.

ssh-add ~/.ssh/your_key

Replace your_key with the name of your private key file. Enter the passphrase once and ssh-agent will remember it for the rest of the terminal session.

Step 3: Configure your SSH setup to be even lazier (I mean efficient)

Okay, we've got the agent running and the key added, but we can take it one step further. Why not tell SSH exactly what key to use for which server, so you never have to worry about it picking the wrong one?

To do this, we're going to set up a ~/.ssh/config file. If you don't have this file yet, don't worry - it's as easy as creating it:

touch ~/.ssh/config

Now, crack open that file with your favorite text editor and set things up like this:

Host your-server-alias
    HostName your.server.com
    User your-username
    IdentityFile ~/.ssh/your_key
    IdentitiesOnly yes

Breaking it down

Host: You can use any alias here that makes sense to you. This is what you'll type when you want to connect to this server.
HostName: The actual domain or IP address of the server.
User: Your username on that server, so you do not have to specify it each time.
IdentityFile: The path to your SSH private key.
IdentitiesOnly yes: Tells SSH to use only this key, rather than trying every key it can find in the agent (which is how you avoid that annoying "user mismatch" issue).

Step 4: Create a wrapper script for SSH Agent control

Alright, you want control over when your SSH agent starts up - totally understandable! Instead of running the agent automatically on login (which might feel a bit too autonomous), we'll create a neat little wrapper script. You can trigger it whenever you feel like starting the agent and adding your SSH key for the session.

Here's how to set that up.

Create the wrapper script

Let's create a script that starts the SSH agent, adds your key, and gives you control over when it runs. We'll call this script init-ssh, and we'll stick it somewhere like /usr/local/bin so it's available from anywhere in your terminal.

Create the script: Open your terminal and create the init-ssh script:
```
sudo nano /usr/local/bin/init-ssh
```

Add the script content: Paste the following content into the file:

#!/bin/bash

# Start the SSH agent
eval $(ssh-agent -s)

# Add the key to the agent
ssh-add ~/.ssh/your_key

# Optional: Display agent status for peace of mind
ssh-add -l

Make the script executable: Give the script executable permissions:
```
sudo chmod +x /usr/local/bin/init-ssh
```

How to use the script

Whenever you want to start your SSH agent for a session, just run:

. init-ssh

This will start the agent, add your key, and show you a list of the keys currently loaded in the agent. You've got full control - start the agent when you want, stop it when you're done, and enjoy a password-free SSH experience for the duration of that session.

Optional: Stopping the SSH Agent

If you want to stop the SSH agent after you're done with it, you can either let it die when you close your terminal or manually kill it with:

eval $(ssh-agent -k)

That way, you get all the convenience of an SSH agent when you need it, without it running indefinitely in the background. You're now in complete control of your SSH setup, and you can keep things secure and efficient, exactly the way you like it.

Happy SSH'ing!

Simplify Elasticsearch and Kibana Installation

2024-04-24T00:00:00+00:00

Why, You Ask?

Setting up Elasticsearch and Kibana involves the same steps each time: update the system, configure repositories, install packages, and apply the initial configuration. I wrote a script to automate that work and make the setup reusable.

It's time-consuming and frustrating. I'm tired of it.

Automating the Setup

This Bash script installs Elasticsearch and Kibana as a single-node cluster. I use it when I need a small, repeatable setup without adding another configuration tool.

Why Choose a Bash Script?

I chose Bash instead of Ansible because the script also works well with cloud-init and inside Docker environments. It has no extra tooling requirements and is easy to copy to a new machine.

Building the Script: A Step-by-Step Guide

Let's walk through the crafting of the script that automates setting up Elasticsearch and Kibana. Here's how I pieced it together, one step at a time:

Checking for Superuser Privileges The script needs administrative access, so it starts by checking for root privileges.

if [ "$(id -u)" != "0" ]; then
   echo "This script must be run as root" 1>&2
   exit 1
fi

Updating the System and Installing Essential Packages Updating the system first helps avoid installation problems caused by outdated packages.

apt update
apt install -y apt-transport-https gnupg curl jq

Adding the Elasticsearch Repository Getting this right is like picking the perfect ingredients for a master chef recipe - it ensures the rest of the meal turns out just right.
Installing Elasticsearch and Kibana Next, the script installs Elasticsearch and Kibana.
Configuring and Starting Services The plot thickens! Setting up the services and getting them running is like reaching the climax of our story - where all elements come together to unveil the full potential of our setup.

Rather than churn out another cookie-cutter guide on setting up Elasticsearch and Kibana, you can view the complete script here. However, I do want to emphasize the initial configuration process involving enrollment tokens and security settings. I've automated these aspects because, let's face it, I've read too many guides that suggest just turning off security for the sake of simplicity. That's not my style - I'd rather keep things secure automatically. It's not rocket science, but it sure is critical. Why simplify by compromising security when you can automate it effectively, right?

This approach ensures you get the functionality you need without the hassle of manual setup or the risks of disabled security.

Perfecting the Automation: Securing and Finalizing the Setup

The final part configures security and leaves both services ready to use.

Broadcasting the Good News First things first, let's make sure any user logging into the system knows what's been accomplished:

echo -e "=== init-vm.sh: Initial ===" >> /etc/motd
echo -e "[> Elasticsearch 'elastic' password: $ELASTIC_PASSWORD" >> /etc/motd
echo -e "[> Test instance with 'curl -k -X GET https://elastic:$ELASTIC_PASSWORD@localhost:9200'" >> /etc/motd
echo -e "=== init-vm.sh: Get started ===" >> /etc/motd
echo -e "[> Reset 'elastic' password with '/usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic'." >> /etc/motd

Here, we're updating the message of the day (MOTD) file to ensure anyone who logs in is immediately informed about how to interact with Elasticsearch and what steps to take next. It's like leaving a note on the fridge - impossible to ignore and incredibly helpful.

Decoding the Secrets Automation isn't just about doing things without human intervention; it's also about doing them securely and wisely:

# Because who likes doing setup manually, right?
decoded_token=$(echo $KIBANA_ENROLLMENT_TOKEN | base64 --decode)
address=$(echo $decoded_token | jq -r '.adr[0]')
fingerprint=$(echo $decoded_token | jq -r '.fgr')
api_key=$(echo $decoded_token | jq -r '.key')

Decoding the enrollment token reveals the essential elements needed to securely configure Kibana: the address, fingerprint, and API key.

Harnessing Version and Build Information Knowing exactly which version and build of Kibana you're working with is required for the API, so let's get that:

ver=$(jq -r '.version' /usr/share/kibana/package.json)
build=$(jq -r '.build.number' /usr/share/kibana/package.json)

Re-encoding and Verification Secrecy is paramount, and so is verification. Here's how we handle both:

encoded_api_key=$(echo -n $api_key | base64)
output=$(sudo /usr/share/kibana/bin/kibana-verification-code)
verification_code=$(echo $output | awk -F": " '{print $2}' | sed 's/ //g')

The API key needs to be re-encoded to maintain security, and we also extract a verification code necessary for the next step - enrolling Kibana.

The Final Act: Enrolling Kibana

And now, the final piece of our automation puzzle:

curl -k -v -X POST "http://localhost:5601/internal/interactive_setup/enroll" \
     -H "Accept: */*" \
     -H "Content-Type: application/json" \
     -H "Host: localhost:5601" \
     -H "Origin: http://localhost:5601" \
     -H "Referer: http://localhost:5601/" \
     -H "kbn-build-number: $build" \
     -H "kbn-version: $ver" \
     -H "x-elastic-internal-origin: Kibana" \
     -H "x-kbn-context: %7B%22type%22%3A%22application%22%2C%22name%22%3A%22interactiveSetup%22%2C%22url%22%3A%22%2F%22%7D" \
     -d '{"hosts":["https://'$address'"],"apiKey":"'$encoded_api_key'","caFingerprint":"'$fingerprint'","code":"'$verification_code'"}'

This curl command not only sends all the needed parameters to Kibana for configuration but also uses the verification code to ensure that the setup is both authorized and secure. It's akin to dotting the i's and crossing the t's in our setup script.

Summary

The script turns a fresh system into a secured, working Elasticsearch and Kibana installation. Feel free to adapt it to your own environment.

Check out the complete script here:

init-elastic-search-kibana-vm.sh

Happy automating, and here's to many insightful data explorations!

P.S.: This script is tailored for automating development environments. Remember, a single-node cluster isn’t suited for production use, and storing passwords in the message of the day (MOTD) file? That’s a no-go for serious deployments. 😏

Simplify Visual Studio Installation

2024-02-12T00:00:00+00:00

Why, You Ask?

Every year, like clockwork, I find myself setting up my local dev environment from scratch. And every time, it's the same old song and dance: downloading, installing, configuring.

It's time-consuming and frustrating. I'm tired of it.

Can It Be Easier?

What if setting up a new machine, rolling it back, or tweaking it could be as simple as running a build on a server? What if I told you we could apply the same principles of automation to our local setups?

Let's Find A Solution

Creating a new development environment shouldn't be a chore. It should be quick, painless, and even a little bit fun. To turn this dream into reality, I need two things: the right software and the perfect setup. That's where winget and .vsconfig come in.

With a list of essential software and some PowerShell tricks, I began to make boring tasks automatic. I picked each program, from 7Zip to Visual Studio, for its important use. But the adventure of automating everything is a story for another time.

Streamlining Visual Studio Installation

My main event? Automating Visual Studio installation. Using winget, I can install Visual Studio with just a line:

winget install -e --id Microsoft.VisualStudio.2022.Enterprise --silent

But I didn't stop there. With the --override flag, I tailored the installation to include specific workloads, like this:

winget install -e --id Microsoft.VisualStudio.2022.Enterprise --silent --override "--wait --quiet --addProductLang En-us --config C:\vs2022.vsconfig"

This method sets up Visual Studio with the workload I need without having to manually select each package.

What's `.vsconfig`?

.vsconfig helps me easily replicate my development environment wherever I am. It's a JSON file that, with just a few clicks in the Visual Studio Installer, allows me to compress my environment workloads into a neat package. This approach is not only perfect for keeping build servers and personal development environments in sync with identical workloads, but it also simplifies sharing updates and changes with teammates.

Example: vs2022.vsconfig

{
  "version": "1.0",
  "components": [
    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
    "Microsoft.Component.MSBuild",
    "Microsoft.VisualStudio.Component.Roslyn.LanguageServices",
    "Microsoft.VisualStudio.Component.SQL.LocalDB.Runtime",
    "Microsoft.VisualStudio.Component.CoreEditor",
    "Microsoft.VisualStudio.Workload.CoreEditor",
    "Microsoft.VisualStudio.Component.TypeScript.TSServer",
    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions",
    "Microsoft.VisualStudio.Component.JavaScript.TypeScript",
    "Microsoft.VisualStudio.Component.TextTemplating",
    "Microsoft.VisualStudio.Component.NuGet",
    "Microsoft.VisualStudio.Component.IntelliTrace.FrontEnd",
    "Microsoft.VisualStudio.Component.Debugger.JustInTime",
    "Component.Microsoft.VisualStudio.LiveShare.2022",
    "Microsoft.VisualStudio.Component.IntelliCode",
    "Microsoft.VisualStudio.Component.ClassDesigner",
    "Microsoft.VisualStudio.Component.GraphDocument",
    "Microsoft.VisualStudio.Component.CodeMap",
    "Microsoft.VisualStudio.Component.VC.CoreIde",
    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
    "Microsoft.VisualStudio.Component.Graphics.Tools",
    "Microsoft.VisualStudio.Component.VC.DiagnosticTools",
    "Microsoft.VisualStudio.Component.Windows11SDK.22621",
    "Microsoft.VisualStudio.Component.VC.ATL",
    "Microsoft.VisualStudio.Component.SecurityIssueAnalysis",
    "Microsoft.VisualStudio.ComponentGroup.ArchitectureTools.Native",
    "Microsoft.VisualStudio.Component.VC.Redist.14.Latest",
    "Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core",
    "Microsoft.VisualStudio.Component.Windows11Sdk.WindowsPerformanceToolkit",
    "Microsoft.VisualStudio.Component.CppBuildInsights",
    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
    "Microsoft.VisualStudio.Component.VC.CMake.Project",
    "Microsoft.VisualStudio.Component.VC.TestAdapterForBoostTest",
    "Microsoft.VisualStudio.Component.VC.TestAdapterForGoogleTest",
    "Microsoft.VisualStudio.Component.VC.ASAN",
    "Microsoft.VisualStudio.Component.Vcpkg",
    "Microsoft.VisualStudio.Component.VC.Tools.ARM64EC",
    "Microsoft.VisualStudio.Workload.NativeDesktop",
    "Microsoft.VisualStudio.Component.VC.Runtimes.ARM64EC.Spectre"
  ]
}

You can create a .vsconfig file with these easy steps:

Launch the Visual Studio Installer and choose to modify your setup.
Hit More and then select the option to Export your settings into a .vsconfig file.

That's it!

Why Bother With All This?

I'm all about making life easier, not harder. Thanks to winget and Visual Studio's .vsconfig, what used to eat up a lot of time now takes no time at all.

Setting up a fresh development environment is now a piece of cake - and I mean the kind of delicious cake you can buy ready-made but tastes as good as anything you'd bake yourself. So here's to spending less time on setup and more on the fun stuff: coding.