MonumentalSystems.LXD 0.1.1

MonumentalSystems.LXD

A .NET client library for LXD container management. Provides a REST API client over Unix domain sockets, WebSocket-based exec sessions, and Semantic Kernel plugin functions for AI agent integration.

Features

• Unix Socket Communication - Native HTTP-over-Unix-socket transport for secure local LXD access
• Container Lifecycle Management - Create, start, stop, restart, and delete containers
• Command Execution - Run commands in containers with stdout/stderr capture
• WebSocket Exec Sessions - Persistent interactive and non-interactive shell sessions with real-time I/O streaming
• Semantic Kernel Plugin - 16 KernelFunction-decorated methods for seamless AI agent tool calling
• Automatic Versioning - MinVer-based semantic versioning from git tags

Installation

dotnet add package MonumentalSystems.LXD

Quick Start

Direct API Client

using MonumentalSystems.LXD;
using MonumentalSystems.LXD.Config;
using Microsoft.Extensions.Logging;

var config = new LxdConfig(); // Auto-detects LXD socket path
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
using var client = new LxdClient(config, loggerFactory.CreateLogger<LxdClient>());

// List containers
var containers = await client.ListContainersAsync();

// Execute a command
var (operation, stdout, stderr) = await client.ExecCommandAsync(
    "my-container",
    new[] { "/bin/sh", "-c", "uname -a" });

Console.WriteLine(stdout);

Semantic Kernel Plugin

using MonumentalSystems.LXD;
using MonumentalSystems.LXD.Config;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;

var config = new LxdConfig();
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
var client = new LxdClient(config, loggerFactory.CreateLogger<LxdClient>());

var plugin = new LxdPlugin(client, loggerFactory.CreateLogger<LxdPlugin>());

// Register with Semantic Kernel
var kernel = Kernel.CreateBuilder()
    .Build();
kernel.Plugins.AddFromObject(plugin, "lxd");

// The plugin exposes functions like:
// - list_containers
// - get_container / get_container_state
// - create_container / start_container / stop_container / delete_container
// - exec_command
// - start_exec_session / close_exec_session / list_exec_sessions
// - exec_stream_stdout / exec_stream_stderr
// - exec_write_stdin
// - exec_get_stdout_history / exec_get_stderr_history

Architecture

MonumentalSystems.LXD/
├── Config/LxdConfig.cs              # Socket path auto-resolution
├── Internal/
│   ├── LxdExecSession.cs            # Persistent WebSocket exec session with circular buffers
│   ├── SlidingBuffer.cs             # Thread-safe circular byte buffer
│   ├── ToolResult.cs                # Centralized result formatting
│   └── UnixSocketHttpHandler.cs     # Unix domain socket HTTP handler
├── Models/                          # LXD API data models
├── LxdClient.cs                     # Low-level REST API client
├── LxdException.cs                  # Custom exception type
└── LxdPlugin.cs                     # 16 KernelFunctions for container management

Building

dotnet build

Testing

# Unit tests
dotnet test --filter "Category!=Integration&Category!=Skipped"

# Unit tests with code coverage
dotnet test --filter "Category!=Integration&Category!=Skipped" \
  --collect:"XPlat Code Coverage" \
  --settings coverlet.runsettings

# Integration tests (require LXD socket + running test-container)
dotnet test --filter "Category=Integration" --verbosity normal

Versioning

This project uses MinVer for automatic semantic versioning from git tags. Push a tag like v1.0.0 to trigger a NuGet publish.

# Pack NuGet locally
dotnet pack MonumentalSystems.LXD/MonumentalSystems.LXD.csproj --configuration Release

License

MIT