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: 120)
`ReasoningEffort`	string	Provider-supported reasoning level, such as `low`, `medium`, or `high`
`MaxOutputTokens`	int	Maximum response size; also reserves output capacity during context budgeting
`ContextWindowTokens`	int	Total model context window. Required with `MaxOutputTokens` for context compaction
`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 (default `0.87`)
`CompactionStaleAfterMinutes`	int	Age after which an in-progress compaction lease may be treated as stale
`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. Keys are encrypted in memory at runtime.

Property	Type	Description
`Alias`	string	Name referenced by `ApiKeyAlias` in model configs
`Value`	string	The API key value

Full Example: Azure OpenAI

fabrcore.json

{
  "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,
      "CompactionThreshold": 0.87
    },
    {
      "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

fabrcore.json

{
  "ModelConfigurations": [
    {
      "Name": "default",
      "Provider": "OpenAI",
      "Model": "gpt-4o",
      "ApiKeyAlias": "openai-key",
      "TimeoutSeconds": 120,
      "MaxOutputTokens": 16384,
      "ContextWindowTokens": 128000
    }
  ],
  "ApiKeys": [
    { "Alias": "openai-key", "Value": "sk-your-api-key-here" }
  ]
}

Full Example: Grok

fabrcore.json

{
  "ModelConfigurations": [
    {
      "Name": "default",
      "Provider": "Grok",
      "Model": "grok-3",
      "ApiKeyAlias": "grok-key",
      "TimeoutSeconds": 120,
      "MaxOutputTokens": 16384,
      "ContextWindowTokens": 131072
    }
  ],
  "ApiKeys": [
    { "Alias": "grok-key", "Value": "xai-your-api-key-here" }
  ]
}

Grok Provider

The Grok provider connects to xAI Grok models. No Uri is required — FabrCore uses the default xAI endpoint automatically. Note that Grok does not support embeddings.

Full Example: Gemini

fabrcore.json

{
  "ModelConfigurations": [
    {
      "Name": "default",
      "Provider": "Gemini",
      "Model": "gemini-2.5-pro",
      "ApiKeyAlias": "gemini-key",
      "TimeoutSeconds": 120,
      "MaxOutputTokens": 8192,
      "ContextWindowTokens": 1048576
    },
    {
      "Name": "embeddings",
      "Provider": "Gemini",
      "Model": "text-embedding-004",
      "ApiKeyAlias": "gemini-key"
    }
  ],
  "ApiKeys": [
    { "Alias": "gemini-key", "Value": "your-gemini-api-key-here" }
  ]
}

Gemini Provider

The Gemini provider connects to Google Gemini models. No Uri is required. Gemini supports both chat completions and embeddings.

Supported Providers

Provider	Uri 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<string>	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:

appsettings.json

{
  "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	Development only
`SqlServer`	`FabrCore.Host.SqlServer`	SQL Server (ADO.NET)	Production with SQL Server
`AzureStorage`	`FabrCore.Host.AzureStorage`	Azure Tables, Blobs, and Queues	Production with Azure

Provider Packages & Auto-Provisioning

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). No manual scripts or preparation is needed. 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: The ModelConfigurations array must not be empty
ApiKeyAlias references resolve: Every ApiKeyAlias value must match an Alias in the ApiKeys array
No placeholder values: Replace "your-api-key-here" and "sk-..." with actual keys
Context budget is complete: Set both ContextWindowTokens and MaxOutputTokens to enable the first layer of context compaction

Remote model configuration

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

appsettings.json

{
  "FabrCore": {
    "FileStorage": {
      "StoragePath": "/tmp/fabrcorefiles",
      "DefaultTtlSeconds": 300,
      "CleanupIntervalMinutes": 1
    }
  }
}

Cross-Platform Note

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.

Configuration

Configuration

fabrcore.json

ModelConfigurations

ApiKeys

Full Example: Azure OpenAI

Full Example: OpenAI

Full Example: Grok

Full Example: Gemini

Supported Providers

AgentConfiguration

Model Providers

Orleans Configuration

Configuration Validation Checklist

File Storage

Documentation