Home / Docs / Configuration

Configuration

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.

PropertyTypeDescription
NamestringUnique name for this model config (e.g., "default", "embeddings")
Providerstring"OpenAI", "Azure", "OpenRouter", "Grok", or "Gemini"
UristringEndpoint URL (required for Azure, ignored for OpenAI)
ModelstringModel deployment name (e.g., "gpt-4o", "text-embedding-ada-002")
ApiKeyAliasstringReferences an alias in the ApiKeys array
TimeoutSecondsintRequest timeout (default: 120)
MaxOutputTokensintMaximum tokens in response
ContextWindowTokensintTotal context window size for the model. Used by chat history compaction

ApiKeys

An array of API key definitions. Keys are encrypted in memory at runtime.

PropertyTypeDescription
AliasstringName referenced by ApiKeyAlias in model configs
ValuestringThe 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,
      "MaxOutputTokens": 16384,
      "ContextWindowTokens": 128000
    },
    {
      "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

ProviderUri RequiredEmbeddingsNotes
OpenAINoYesUses default OpenAI endpoint
AzureYesYesAzure OpenAI resource URL
OpenRouterNoYesUses OpenRouter endpoint
GrokNoNoxAI Grok models
GeminiNoYesGoogle Gemini models

AgentConfiguration

Agents are created programmatically using AgentConfiguration objects passed via the REST API or ClientContext.

PropertyTypeDescription
HandlestringUnique agent identifier
AgentTypestringAgent type alias (from [AgentAlias])
ModelsstringModel configuration name from fabrcore.json
StreamsList<string>Orleans streams to subscribe to
SystemPromptstringSystem-level instructions for the agent
ArgsDictionary<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
  }
}
ClusteringModeDescriptionUse Case
LocalhostIn-memory clusteringDevelopment only
SqlServerSQL Server (ADO.NET)Production with SQL Server
AzureStorageAzure Table StorageProduction with Azure
SQL Server Auto-Provisioning

When using SqlServer clustering mode, FabrCore includes an OrleansSqlServerInitializer that automatically creates the required Orleans database tables on startup if they do not already exist. No manual SQL scripts or database preparation is needed — just provide a valid connection string and the initializer handles the rest.

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
  • ContextWindowTokens set: Required for chat history compaction

File Storage

appsettings.json 
{
  "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.

Documentation