Application configuration
Crystal Lattice configuration combines providers, agents, plugin packages, reusable mixins, model-selected variants, placeholders, and application settings in one JSON file.
Configuration layers
The main layers are:
- top-level settings and plugin package specs;
- reusable
mixins; - named
providers; - named
agents; - session/request overrides stored with a session.
Provider settings are merged into the selected agent. Mixins are expanded before that provider-to-agent merge. Model-selected variants are evaluated after the effective model override is known, and explicit session/request overrides apply last.
Guides
- Plugin configuration: package specs, loading layers, enablement, installation policy, Node tools, and Bash tools.
- Placeholders: environment variables, file loading, derived paths, and literal values.
- Configuration mixins: reusable fragments, precedence, recursion, and shallow/deep merge behavior.
- Configuration variants: model-selected settings, exact and regex conditions, nested variants, and merge policies.
- System-message templates: file-backed templates, runtime helpers, dynamic sections, and UI contributions.
- Terminal configuration: terminal presentation and application-owned UI settings.
Minimal example
{
"plugins": [
"path:${env:BUILTIN_PLUGINS}/openrouter"
],
"providers": {
"openrouter": {
"provider": "openrouter",
"api_key": "${env:OPENROUTER_API_KEY}",
"base_url": "https://openrouter.ai/api/v1"
}
},
"agents": {
"default": {
"display": {
"title": "Default agent",
"description": "General-purpose model profile.",
"order": 10
},
"provider": "openrouter",
"model": "openai/gpt-5-mini"
}
}
}
Agent display metadata
An agent's stable object key remains its ID for requests, sessions, switching,
and persisted metadata. An optional display object supplies client-facing
presentation without entering the provider request configuration:
{
"agents": {
"codex-openai": {
"display": {
"title": "Codex · OpenAI",
"description": "Codex-style tools with automatic OpenAI authentication.",
"order": 10
},
"provider": "openai",
"model": "gpt-5.4-mini"
}
}
}
titledefaults to the stable agent ID.descriptiondefaults to an empty string.orderis a finite number. Missing order falls back to configuration declaration order.
GET /agents retains its agents: string[] compatibility list and also
returns agent_descriptors, ordered by display order:
{
"agents": ["codex-openai"],
"agent_descriptors": [
{
"id": "codex-openai",
"title": "Codex · OpenAI",
"description": "Codex-style tools with automatic OpenAI authentication.",
"order": 10
}
]
}
Clients must submit id, not the display title, when creating or switching a
session.
Agent default plugin preview
GET /agents/{agent_id}/plugins returns the selected agent's effective
default plugin projection without creating or saving a session:
{
"plugins": [
{
"id": "apply_patch",
"kind": "tools",
"class_path": "codex_tools.apply_patch_tool.ApplyPatchTool",
"class_name": "ApplyPatchTool",
"name": "apply_patch",
"enabled": true,
"active": true,
"source": "implicit"
}
]
}
The endpoint is read-only. It exposes plugin identity, kind, class metadata, default-enabled state, effective active state, and whether enablement is implicit or agent-configured. It does not return provider settings, credentials, environment values, request options, system-message content, or other configuration values.
Unknown agent IDs return HTTP 404.
The command searches for configuration in:
./.crystal/config.json~/.crystal/config.json
Use --config for an explicit file or --config-local to create and use
./.crystal/config.json.
Credentials and startup
The CLI can create and start the default config without provider API keys. Missing credentials do not prevent the server, terminal, local configuration, or agent listing from starting.
Put keys for API-backed providers and tools in a .env file rather than
exporting them before every launch. For a project-local config:
# .crystal/.env
OPENAI_API_KEY=...
OPENROUTER_API_KEY=...
ANTHROPIC_API_KEY=...
The CLI reads these values for config resolution without adding them to the process environment. A request to a credentialed API still requires the real key for that provider or tool. See configuration placeholders for the complete lookup order and precedence.
Bridge runtime settings
Bridge registration is explicitly enabled with --enable-bridge or
--bridge-url. application.bridge_url supplies a reusable URL but does not
enable registration by itself. URL precedence is:
--bridge-url;.crystal/profile.json;~/.crystal/projects.json;application.bridge_url.
Advanced bridge-client transport settings live under application.bridge:
{
"application": {
"bridge_url": "wss://bridge.example/ws/websocket",
"bridge": {
"ws_max_size_bytes": 16777216,
"http_timeout_seconds": 120.0,
"http_chunk_size_bytes": 921600,
"http_chunk_threshold_bytes": 262144,
"http_max_body_bytes": 10485760,
"debug": false
}
}
}
| Key | Type | Default | Meaning |
|---|---|---|---|
ws_max_size_bytes |
positive integer or null |
16777216 (16 MiB) |
Maximum WebSocket message accepted by the Python bridge client. null disables the WebSocket library's message-size limit. |
http_timeout_seconds |
positive finite number | 120.0 |
Timeout used by bridge HTTP download/upload operations. |
http_chunk_size_bytes |
positive integer | 921600 (900 KiB) |
Payload target for legacy chunked bridge responses, with protocol-envelope headroom applied by the adapter. |
http_chunk_threshold_bytes |
positive integer | 262144 (256 KiB) |
Response size above which the legacy adapter uses chunked response events. |
http_max_body_bytes |
positive integer | 10485760 (10 MiB) |
Maximum request body buffered by the Python legacy bridge adapter. |
debug |
boolean | false |
Enables bridge-client debug output. |
Wrong JSON types, zero or negative sizes/timeouts, and non-finite timeouts stop server startup with a field-specific error. These settings are read when the process starts. Application reload does not reconnect the bridge or restart Bonjour, so changing them requires restarting Crystal Lattice.
Bridge and Bonjour do not implicitly read specially named environment
variables. Use the documented CLI/profile/application settings. Embedders that
run agent_terminal_app.server:app directly configure
ServerIntegrationRuntimeConfig before FastAPI startup.
The ordinary placeholder system remains available when a configuration author deliberately places a placeholder in one of these fields; that is explicit configuration, not an automatic bridge environment contract.
Session-list loading
The current local session-list implementation persists complete derived summaries so a new runtime does not reopen every unchanged session file. Session files are still authoritative; deleting the derived cache only causes summaries to be rebuilt.
The service enumerates session filenames and attributes first. It then resolves new or changed sessions from newest to oldest. Full resolution waits for up to 10 seconds by default. If files remain unresolved, the response still contains every discovered session: complete summaries appear first and unresolved sessions use empty preview and metadata values with the standard fallback title. Resolution continues inside the server for later list requests.
This behavior can be tuned through the current implementation's own application section:
{
"application": {
"cached_background_session_list": {
"foreground_timeout_seconds": 10.0,
"worker_count": 1,
"persistent_cache_enabled": true,
"local_cache_directory": "~/.crystal/cache/session-list"
}
}
}
foreground_timeout_secondsis a non-negative finite number.0returns cached and metadata-only summaries without waiting for content resolution.worker_countis an integer from 1 through 8.persistent_cache_enableddisables cross-runtime reuse when set tofalse; background resolution remains active.local_cache_directoryoverrides the directory for private derived summary databases.
These settings belong to the current local implementation. Other session-list-service implementations may ignore them or use different settings.
By default, the cache is under ~/.crystal/cache/session-list. When session
files are inside an on-demand cloud folder, keep
local_cache_directory outside that folder so the derived summaries remain
locally available.
Diagnostics
Configuration errors are available programmatically:
from agent_app import AgentApplication
app = AgentApplication("config.json", "./sessions")
for error in app.get_config_errors():
print(error.get("type"), error.get("path"), error.get("detail"))
Invalid plugin package, mixin, merge-policy, and variant configuration prevents
application startup. An unresolved environment placeholder is reported
separately as an env_missing warning, and that warning is not itself fatal.
The empty resolved value can still cause an independent fatal validation error
when it is used in a structural setting such as a plugin path. Optional
credential placeholders in the generated default config do not prevent
startup; the selected API-backed functionality still needs its configured
credentials.