Configuration
Configure models in OpenCaddis.App
The app owns two independent FabrCore configuration documents: one for the runtime Server and one for Server Builder. Each must contain at least one valid model configuration and one referenced API key before its host can start.
Configuration documents and generated cloud-authentication keys are stored as plaintext in the app-data CloudServer directory. This is intentionally simple local development storage, not a secrets vault. Use development credentials and protect access to the machine.
Where configuration lives
- Open Server in OpenCaddis.App.
- Select Cloud configuration.
- Choose Server or Server Builder.
- Edit the JSON document and select Save configuration.
The app normalizes and validates the document before saving it. Separate files are persisted as server.fabrcore.json and server-builder.fabrcore.json. The generated credential for the selected mode is also used internally to authorize protected Agent Skill administration; it is not displayed in the App.
Required document shape
| Field | Required | Purpose |
|---|---|---|
modelConfigurations | At least one | Names the provider, model identifier, optional endpoint, and API-key alias. |
apiKeys | At least one | Maps an alias to a non-empty credential value. |
name | Yes | Unique model name used by agents. Builder agents use default unless configured otherwise. |
provider | Yes | A FabrCore-supported model provider name. |
uri | Provider dependent | Custom or hosted endpoint URL when the provider requires one. |
model | Yes | Provider model or deployment identifier. |
apiKeyAlias | Yes | Must match an alias present in apiKeys. |
Example
{
"modelConfigurations": [
{
"name": "default",
"provider": "OpenAI",
"uri": "",
"model": "your-model-id",
"apiKeyAlias": "openai"
}
],
"apiKeys": [
{
"alias": "openai",
"value": "your-development-api-key"
}
]
}OpenCaddis validates the common document structure. For current provider names and provider-specific options, use the FabrCore documentation.
How hosts receive configuration
OpenCaddis.App starts a loopback-only configuration service at http://localhost:5082/. It generates a separate bearer key and cluster ID for each target:
| Target | Cluster ID | Configuration file |
|---|---|---|
| OpenCaddis Server | opencaddis-server | server.fabrcore.json |
| OpenCaddis Server Builder | opencaddis-server-builder | server-builder.fabrcore.json |
The active host downloads its configuration through the FabrCore Cloud Server protocol, checks for updates every five seconds, and sends a local heartbeat every ten seconds. The same per-mode key authenticates OpenCaddis.App when it publishes Builder Agent Skills through FabrCore's protected administration API. The service is designed only for the OpenCaddis.App loopback workflow.
Validation rules
- Model names must be unique without regard to case.
- API-key aliases must be unique without regard to case.
- Every model must name a provider, model identifier, and API-key alias.
- Every referenced API-key alias must exist.
- Both alias and credential value must be non-empty.