Configuration
FabrCore 2.0 · Release and package availability
These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes
FabrCore:Memory; GraphRAG ingestion tuning remains under top-level GraphRag:Ingestion.For cloud settings, named code rules and per-process application status, see runtime configuration. Preview a complete candidate without applying it, and distinguish catalog values from observed consumer state.
Configuration
FabrCore uses fabrcore.json for LLM provider settings and AgentConfiguration objects to define agents programmatically or via REST API.
fabrcore.json
ModelConfigurations
An array of model definitions. Each entry defines a named model that agents can reference.
| Property | Type | Description |
|---|---|---|
Name | string | Unique name for this model config (e.g., "default", "embeddings") |
Provider | string | "OpenAI", "Azure", "OpenRouter", "Grok", or "Gemini" |
Uri | string | Endpoint URL (required for Azure; optional for OpenAI-compatible endpoints) |
Model | string | Model deployment name (e.g., "gpt-4o", "text-embedding-ada-002") |
ApiKeyAlias | string | References an alias in the ApiKeys array |
TimeoutSeconds | int | Request timeout (default: 60 seconds) |
ReasoningEffort | string | Provider-supported reasoning level, such as low, medium, or high |
MaxOutputTokens | int | Optional maximum response size, sent with every request. When set, it also reserves output capacity during context budgeting; when unset, no cap is sent and the reserve is derived from the context window |
ContextWindowTokens | int | Total model context window. Required for context compaction; use the input limit when the provider publishes one separately |
ContextCompactionEnabled | bool | Enables in-memory tool-result eviction and truncation during a run |
ContextEvictThreshold | double | Usage ratio that starts evicting older tool results (default 0.50) |
ContextTruncateThreshold | double | Usage ratio that starts truncating remaining oversized tool results (default 0.80) |
CompactionEnabled | bool | Enables persisted history summarization |
CompactionKeepLastN | int | Recent history entries retained verbatim after summarization |
CompactionThreshold | double | Usage ratio that triggers history compaction (70% of usable input working set; 75% fallback) |
CompactionStaleAfterMinutes | int | Legacy preflight switch: positive enables threshold checks before turns; zero/negative disables them (default 60). It is not a lease age. |
PerTurnMaxInputTokens | int | Optional input-token budget for a single turn |
MaxPromptInputTokens | int | Optional hard ceiling for a constructed prompt |
RunawayBudgetBehavior | string | Behavior when a run-safety budget is exhausted |
ApiKeys
An array of API key definitions. Supply keys through protected deployment configuration; do not commit live credentials.
| Property | Type | Description |
|---|---|---|
Alias | string | Name referenced by ApiKeyAlias in model configs |
Value | string | The API key value |
Full Example: Azure OpenAI
{
"ModelConfigurations": [
{
"Name": "default",
"Provider": "Azure",
"Uri": "https://your-resource.openai.azure.com/",
"Model": "gpt-4o",
"ApiKeyAlias": "azure-key",
"TimeoutSeconds": 120,
"ReasoningEffort": "medium",
"MaxOutputTokens": 16384,
"ContextWindowTokens": 128000,
"ContextCompactionEnabled": true,
"ContextEvictThreshold": 0.50,
"ContextTruncateThreshold": 0.80,
"ContextWorkingSetTokens": 64000
},
{
"Name": "embeddings",
"Provider": "Azure",
"Uri": "https://your-resource.openai.azure.com/",
"Model": "text-embedding-ada-002",
"ApiKeyAlias": "azure-key"
}
],
"ApiKeys": [
{ "Alias": "azure-key", "Value": "your-api-key-here" }
]
}
Full Example: OpenAI
{
"ModelConfigurations": [
{
"Name": "default",
"Provider": "OpenAI",
"Model": "gpt-4o",
"ApiKeyAlias": "openai-key",
"TimeoutSeconds": 120,
"MaxOutputTokens": 16384,
"ContextWindowTokens": 128000,
"Uri": ""
}
],
"ApiKeys": [
{
"Alias": "openai-key",
"Value": "sk-your-api-key-here"
}
]
}
Full Example: Grok
{
"ModelConfigurations": [
{
"Name": "default",
"Provider": "Grok",
"Model": "grok-3",
"ApiKeyAlias": "grok-key",
"TimeoutSeconds": 120,
"MaxOutputTokens": 16384,
"ContextWindowTokens": 131072,
"Uri": ""
}
],
"ApiKeys": [
{
"Alias": "grok-key",
"Value": "xai-your-api-key-here"
}
]
}
The Grok provider connects to xAI Grok models. Set Uri to an empty string to use the default endpoint — FabrCore uses the default xAI endpoint automatically. Note that Grok does not support embeddings.
Full Example: Gemini
{
"ModelConfigurations": [
{
"Name": "default",
"Provider": "Gemini",
"Model": "gemini-2.5-pro",
"ApiKeyAlias": "gemini-key",
"TimeoutSeconds": 120,
"MaxOutputTokens": 8192,
"ContextWindowTokens": 1048576,
"Uri": ""
},
{
"Name": "embeddings",
"Provider": "Gemini",
"Model": "text-embedding-004",
"ApiKeyAlias": "gemini-key",
"Uri": ""
}
],
"ApiKeys": [
{
"Alias": "gemini-key",
"Value": "your-gemini-api-key-here"
}
]
}
The Gemini provider connects to Google Gemini models. Set Uri to an empty string to use the default endpoint. Gemini supports both chat completions and embeddings.
Supported Providers
| Provider | Custom endpoint required | Embeddings | Notes |
|---|---|---|---|
OpenAI | No | Yes | Uses default OpenAI endpoint |
Azure | Yes | Yes | Azure OpenAI resource URL |
OpenRouter | No | Yes | Uses OpenRouter endpoint |
Grok | No | No | xAI Grok models |
Gemini | No | Yes | Google Gemini models |
AgentConfiguration
Agents are created programmatically using AgentConfiguration objects passed via the REST API, SDK API client, or host services.
| Property | Type | Description |
|---|---|---|
Handle | string | Unique agent identifier |
AgentType | string | Agent type alias (from [AgentAlias]) |
Models | string | Model configuration name from fabrcore.json |
Streams | List<EventStreamSubscription> | Namespace/channel subscriptions for Orleans streams to subscribe to |
SystemPrompt | string | System-level instructions for the agent |
Args | Dictionary<string, string> | Additional configuration arguments |
Model Providers
Orleans Configuration
Configure Orleans clustering in appsettings.json:
{
"FabrCore": {
"Orleans": {
"ClusterId": "fabrcore-cluster",
"ServiceId": "fabrcore-service",
"ClusteringMode": "Localhost",
"ConnectionString": null
}
}
}
| ClusteringMode | NuGet Package | Description | Use Case |
|---|---|---|---|
Localhost | built into FabrCore.Host | In-memory clustering | Trusted standalone workspaces |
SqlServer | FabrCore.Host | SQL Server (ADO.NET) | Production with SQL Server |
AzureStorage | FabrCore.Host.AzureStorage | Azure Tables, Blobs, and Queues | Production with Azure |
SqlServer and AzureStorage modes live in their own NuGet packages and are discovered automatically — reference the package, set ClusteringMode, and provide a connection string. Both providers auto-provision their backing resources on startup (SQL Server: all Orleans tables; Azure Storage: tables, the grain-state blob container, and stream queues). The SQL database must already exist. Auto-initialization creates supported schemas; pre-provisioned or incompatible schemas need operator attention. See the server docs for details and tuning options.
Configuration Validation Checklist
Verify your fabrcore.json before running to avoid cryptic runtime errors:
- Valid JSON: No trailing commas, missing quotes, or unclosed braces
- At least one ModelConfiguration: Configure the model alias used by an LLM-backed agent before initializing it; a host running only non-model agents does not need a paid model
- ApiKeyAlias references resolve: Every
ApiKeyAliasvalue must match anAliasin theApiKeysarray - No placeholder values: Replace
"your-api-key-here"and"sk-..."with actual keys - Context window is set: Set
ContextWindowTokens(and, on 2.0.0 and 2.0.1,MaxOutputTokens) to enable the first layer of context compaction
The model-configuration HTTP endpoints are protected by the FabrCoreAdmin policy. SDK clients calling them remotely should provide FabrCore:AdminAuthentication:ApiKey. In-process server code resolves models directly from the active configuration store and does not make a loopback HTTP call.
File Storage
{
"FabrCore": {
"FileStorage": {
"StoragePath": "/tmp/fabrcorefiles",
"DefaultTtlSeconds": 300,
"CleanupIntervalMinutes": 1
}
}
}
The default StoragePath uses a Windows path format. On Linux, WSL, or macOS, you must configure this explicitly to a Unix-style path (e.g., /tmp/fabrcorefiles). Otherwise, a literal c:\temp\fabrcorefiles directory will be created in your working directory.
Cloud administration options
Under FabrCore:Administration, Model optionally overrides the target model alias for diagnostics and TimeoutSeconds defaults to 120 (1–600). Diagnostic sessions require durable user-scoped storage to survive process restart.
Under FabrCore:Monitoring, Provider=sql opts into buffered operational monitoring. Defaults: RetentionDays=7, QueueRecords=10000, QueueBytes=67108864, BatchSize=250, with one-second flushing. Preserve existing capture/redaction options. See cloud administration for authentication, source coverage and the additive SQL migration.
Connection credentials and key protection
FabrCore:DataProtection controls automatic or custom key protection. SQL requires a deployment certificate. Connection profiles contain credential references; resolve secrets or signing certificates from protected host configuration, not blueprint arguments. Read the integration guide.