Home / Docs / Configuration

Configuration

Configuration

OpenCaddis uses two configuration files in the src/OpenCaddis directory:

fabr.json

LLM provider and model settings — what models to use and how to connect to them.

opencaddis.json

Agent definitions and plugin settings — what agents to create and how they behave.

fabr.json

ModelConfigurations

An array of model definitions. Each entry defines a named model that agents can reference.

Property Type Description
NamestringUnique name for this model config (e.g., "default", "embeddings")
Providerstring"Azure" or "OpenAI"
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 to determine when to summarize
Required Model Names

You must define at least a "default" model (main LLM for chat) and an "embeddings" model (text-embedding-ada-002 for the memory system).

ApiKeys

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

Property Type Description
AliasstringName referenced by ApiKeyAlias in model configs
ValuestringThe API key value

Full Example: Azure OpenAI

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

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

opencaddis.json

Agents

An array of agent definitions. Each agent is a separate conversation in the UI.

Property Type Description
HandlestringDisplay name for the agent
AgentTypestring"assistant", "delegate", "workflow", or "eventlog" (see Agents)
Modelsstring[]Model config names to use (e.g., ["default"])
SystemPromptstringSystem prompt that defines the agent's persona and behavior
Pluginsstring[]List of plugins to enable (see Plugins)
Toolsstring[]Optional: restrict to specific tools within enabled plugins
ArgsobjectPlugin-specific configuration overrides

Plugin Args Reference

Override default plugin behavior per-agent using the Args object:

Plugin Arg Key Default Description
WebBrowserWebBrowser:TimeoutMs30000Page load timeout (ms)
WebBrowserWebBrowser:MaxContentLength50000Max markdown output chars
WebBrowserWebBrowser:ScreenshotPath—Screenshot save directory
WebBrowserWebBrowser:HeadlesstrueRun browser headless
PowerShellPowerShell:WorkingDirectory—Default working directory
PowerShellPowerShell:TimeoutSeconds30Command timeout
PowerShellPowerShell:MaxOutputLength10000Max output chars
FileSystemFileSystem:RootPathtemp dirBase directory for file ops
TaskManagerTaskManager:RootPath—Task file directory
TaskManagerTaskManager:FileNametasks.jsonTask file name
DockerDocker:TimeoutSeconds60Command timeout
DockerDocker:MaxOutputLength10000Max output chars
DockerDocker:Shell/bin/bashShell to use
Microsoft365EmailMicrosoft365Email:MaxResults25Default email query count
Microsoft365EmailMicrosoft365Email:MaxBodyLength10000Max email body chars
MemoryMemory:MaxResults5Default search results
CompactionCompactionEnabledtrueEnable or disable chat history compaction
CompactionCompactionKeepLastN20Number of recent messages to always preserve
CompactionCompactionMaxContextTokensfrom modelOverride context window size for this agent
CompactionCompactionThreshold0.75Trigger compaction at this ratio of context window
DelegateManagedAgentsall agentsComma-separated list of agent names to route to
DelegateDelegationTimeoutSeconds180Max seconds to wait for delegated agent response
WorkflowManagedAgentsall agentsComma-separated list of agent names to delegate to
WorkflowMaxTaskAttempts3Max retry attempts per task

Microsoft365 Section

Top-level config for Microsoft 365 integration (see Microsoft 365 Setup):

Property Description
ClientIdAzure App Registration Application (client) ID
EncryptedTokensAuto-populated after authentication — do not edit manually
UserDisplayNameAuto-populated after authentication
UserEmailAuto-populated after authentication

Full Example

opencaddis.json 
{
  "Agents": [
    {
      "Handle": "General Assistant",
      "AgentType": "assistant",
      "Models": ["default"],
      "SystemPrompt": "You are a helpful assistant.",
      "Plugins": ["WebBrowser", "Memory", "TaskManager"],
      "Args": {
        "WebBrowser:Headless": true,
        "Memory:MaxResults": 10
      }
    },
    {
      "Handle": "Project Lead",
      "AgentType": "workflow",
      "Models": ["default"],
      "SystemPrompt": "You are a project coordinator. Plan and delegate work.",
      "Args": {
        "ManagedAgents": "General Assistant",
        "MaxTaskAttempts": 3
      }
    }
  ],
  "Microsoft365": {
    "ClientId": "your-app-id-here"
  }
}
Documentation