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

For 2.0, configure the feature connection and mode using Standalone and SQL Modes. Host reads Memory tuning under FabrCore:Memory; GraphRAG ingestion tuning remains under top-level GraphRag:Ingestion.

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	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 (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

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,
      "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

fabrcore.json

{
  "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

fabrcore.json

{
  "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"
    }
  ]
}

Grok Provider

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

fabrcore.json

{
  "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"
    }
  ]
}

Gemini Provider

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:

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

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). 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 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.

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.