Server

Server

The FabrCore server hosts your agents on an Orleans cluster. It provides REST and WebSocket APIs for client communication and background services for housekeeping.

Extension Methods

AddFabrCoreServer

Configures FabrCore server infrastructure including Orleans, services, streaming, and automatic discovery of the entry assembly plus referenced FabrCore dependencies.

var builder = WebApplication.CreateBuilder(args);

// Basic setup
builder.AddFabrCoreServer();

// Only needed for a runtime-loaded assembly outside the dependency graph
builder.AddFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new List<Assembly>
    {
        typeof(MyCustomAgent).Assembly
    }
});

What it configures:

• Orleans silo with clustering, persistence, and reminders
• IFabrCoreRegistry (singleton) — Agent, plugin, and tool discovery
• IFabrCoreChatClientService (singleton) — Chat client factory
• IEmbeddings (singleton) — Embedding generation with cached client
• IFileStorageService (singleton) — File storage with TTL
• FileCleanupBackgroundService — Automatic file cleanup
• AgentRegistryCleanupService — Automatic agent registry cleanup

UseFabrCoreServer

Registers FabrCore middleware, including the WebSocket endpoint for real-time agent communication.

var app = builder.Build();

app.UseFabrCoreServer();

Complete Startup Example

var builder = WebApplication.CreateBuilder(args);

builder.AddFabrCoreServer();

builder.Services.AddControllers();

var app = builder.Build();

app.UseFabrCoreServer();
app.MapControllers();

await app.RunAsync();

Cloud Server Configuration

A host normally reads its model configurations and API keys from a local fabrcore.json. With the Cloud Server feature enabled it pulls that same payload from a remote server instead and reports periodic heartbeats — useful when a fleet of silos should share one source of configuration rather than each shipping its own secrets file.

The feature is disabled by default and existing hosts are unaffected. It is configured entirely through appsettings.json; no fabrcore.json is required.

{
  "FabrCore": {
    "HostUrl": "https://agents.example.com",
    "CloudServer": {
      "Enabled": true,
      "Url": "https://forge.vulcan365.ai",
      "ApiKey": "<per-cluster API key>",
      "ClusterId": null,
      "Environment": null
    },
    "RemoteAdministration": {
      "Enabled": true,
      "PollWait": "00:00:20"
    }
  }
}

Remote administration

Remote administration lets the cloud server dispatch administrative calls into the host. It is disabled by default and requires CloudServer:Enabled to be true — a host cannot enable remote administration without also enabling its cloud connection. It reuses FabrCore:CloudServer:ApiKey; there is no separate credential.

FabrCore:HostUrl is the only remote-administration target. It must be an absolute http(s) URL reachable from the host process, and requests outside /fabrcoreapi/ are rejected. The host logs a startup warning for a non-loopback URL, because the Cloud Server API key then travels the network.

FabrCoreRegistry

FabrCoreRegistry discovers agents, plugins, tools, and provider registrations at startup by scanning the application entry assembly and referenced FabrCore dependency graph for alias attributes. No routine assembly list is required — decorate your classes and reference their projects or packages.

Discovery Scope and Dynamic Assemblies

In v1.7.1, referenced agent and plugin projects are found automatically. Use AdditionalAssemblies only for assemblies loaded dynamically or otherwise outside the application's dependency graph:

builder.AddFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new List<Assembly>
    {
        typeof(MyCustomAgent).Assembly,
        typeof(MyPluginLibrary).Assembly
    }
});

How Discovery Works

All attributes support AllowMultiple = true, so a single component can have multiple aliases:

[AgentAlias("assistant")]
[AgentAlias("my-assistant")]
public class AssistantAgent : FabrCoreAgentProxy
{
    // Reachable via either alias
}

Registry API

Discovery REST Endpoint

The registry is exposed via a built-in REST endpoint, allowing clients to discover available agents, plugins, and tools at runtime:

{
  "agents": [
    { "typeName": "MyApp.AssistantAgent", "aliases": ["assistant", "my-assistant"] }
  ],
  "plugins": [
    { "typeName": "MyApp.WeatherPlugin", "aliases": ["weather"] }
  ],
  "tools": [
    { "typeName": "MyApp.MathTools.Add", "aliases": ["add-numbers"] }
  ]
}

REST API

All endpoints are prefixed with /fabrcoreapi.

Agent API

All Agent API endpoints require the x-user-handle header to identify the caller principal. For an idempotent, application-owned way to provision a standard agent set, see Blueprints.

POST /fabrcoreapi/Agent/create
x-user-handle: principal123

[{
  "handle": "my-agent",
  "agentType": "MyAgent",
  "models": "default",
  "systemPrompt": "You are a helpful assistant."
}]

Diagnostics API

File & Embeddings API

Batch Embeddings

The batch endpoint accepts a list of items, each with a caller-provided id and text:

{
  "items": [
    { "id": "item-1", "text": "First document to embed" },
    { "id": "item-2", "text": "Second document to embed" },
    { "id": "item-3", "text": "Third document to embed" }
  ]
}

{
  "results": [
    { "id": "item-1", "vector": [0.0123, -0.0456, ...], "dimensions": 1536 },
    { "id": "item-2", "vector": [0.0789, -0.0321, ...], "dimensions": 1536 },
    { "id": "item-3", "vector": [0.0654, -0.0987, ...], "dimensions": 1536 }
  ]
}

Validation Rules

Chat Completions API

FabrCore exposes an OpenAI-compatible chat completions endpoint via the ChatCompletionController, allowing external systems to interact with configured LLM models using standard OpenAI client libraries.

Endpoint

The endpoint uses IFabrCoreChatClientService to resolve the model by name from fabrcore.json. It is designed for single-turn completions — no streaming or tool calling.

Request Format

{
  "Messages": [
    { "Role": "user", "Content": "Extract entities from this text..." }
  ],
  "Options": {
    "Model": "gpt-4o-mini",
    "MaxOutputTokens": 2048,
    "Temperature": 0.2
  }
}

Options is optional. Supported options: Model (defaults to "default"), MaxOutputTokens, Temperature, TopP, TopK, StopSequences, FrequencyPenalty, PresencePenalty.

Response Format

{
  "Text": "The extracted response text...",
  "Model": "gpt-4o-mini",
  "Usage": { "InputTokens": 150, "OutputTokens": 80 }
}

WebSocket API

WebSocket v2 provides authenticated real-time messaging at /ws. Browser clients first obtain a 30-second, single-use ticket from POST /fabrcoreapi/ws/ticket, then connect with the fabrcore.v2 and fabrcore.ticket.<token> subprotocols. Native clients can use the same ticket flow through FabrCore.Client.WebSocket.

See the WebSocket v2 guide for the handshake, typed client, operation catalog, delivery guarantees, and migration checklist.

Orleans Streaming

FabrCore uses Orleans streams for agent communication:

Background Services

Orleans Provider Packages & Auto-Provisioning

FabrCore.Host ships with in-memory Localhost mode built in. Production backends live in dedicated provider packages that are discovered automatically — reference the package, set Orleans:ClusteringMode, and provide a connection string. No registration code is required (explicit options.UseSqlServer() / options.UseAzureStorage() calls are also available).

Both provider packages auto-provision their backing resources at startup (controlled by Orleans:AutoInitDatabase, default true) and fail fast with a clear error when the connection string is invalid. Custom backends can implement IFabrCoreOrleansProvider and register via options.UseOrleansProvider(...).

SQL Server: Automatic Table Deployment

The initializer runs embedded SQL scripts that create tables for all four Orleans subsystems under a dedicated orlns schema:

The SQL scripts are embedded resources within the FabrCore.Host.SqlServer package. The initializer checks whether the schema and tables already exist before running, making it safe for repeated startups.

// appsettings.json — tables are auto-provisioned on first startup
{
  "Orleans": {
    "ClusterId": "prod",
    "ServiceId": "fabrcore",
    "ClusteringMode": "SqlServer",
    "ConnectionString": "Server=localhost;Database=FabrCore;Trusted_Connection=True;"
  }
}

Azure Storage: Tables, Blobs, and Queues

With the FabrCore.Host.AzureStorage package, the host runs entirely on an Azure Storage account: tables for clustering, reminders, and stream pub/sub state; blobs for grain state; queues for streams. At startup the provider creates the tables, the grain-state blob container, and the stream queues if they do not exist.

// Resources are auto-provisioned on first startup.
// For local development, run Azurite and use "UseDevelopmentStorage=true".
{
  "Orleans": {
    "ClusterId": "prod",
    "ServiceId": "fabrcore",
    "ClusteringMode": "AzureStorage",
    "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...",
    "AzureStorage": {
      "GrainStorage": "Blob",
      "ContainerName": "fabrcore-grainstate",
      "Streams": "AzureQueue",
      "StreamQueueCount": 8
    }
  }
}