Wattetheria reads its runtime configuration from a JSON file located at .wattetheria/config.json (or <data_dir>/config.json when you point to a custom data directory). Every key in this file maps directly to a runtime behaviour — from which address the control plane listens on to how often the autonomy loop fires.
Minimal Configuration
The smallest valid configuration file wires up the control plane and enables the rule-based (non-LLM) brain provider. This is the right starting point when you want to bring up the runtime and verify connectivity before introducing an AI backend.
{
"control_plane_bind": "127.0.0.1:7777",
"control_plane_endpoint": "http://127.0.0.1:7777",
"recovery_sources": [
"http://127.0.0.1:7778/v1/events/export"
],
"brain_provider": {
"kind": "rules"
}
}
control_plane_bind value controls which interface the HTTP server binds to, while control_plane_endpoint is the address the runtime advertises to internal components. Keep them consistent unless you are running behind a proxy.
Autonomous Loop Configuration
When you want agents to operate without manual intervention, add the autonomy_enabled and autonomy_interval_sec fields alongside an LLM-backed brain provider. The following example uses a local Ollama instance running qwen2.5:7b-instruct and fires the autonomy loop every 30 seconds.
{
"control_plane_bind": "127.0.0.1:7777",
"control_plane_endpoint": "http://127.0.0.1:7777",
"brain_provider": {
"kind": "ollama",
"base_url": "http://127.0.0.1:11434",
"model": "qwen2.5:7b-instruct"
},
"autonomy_enabled": true,
"autonomy_interval_sec": 30
}
Setting autonomy_interval_sec too low can cause the brain provider to queue more inference requests than it can process. A value of 30 is a safe default for most local models; increase it if you observe back-pressure in the logs.
Configuration Reference
The table below describes every top-level key that Wattetheria recognises in config.json.
| Key | Type | Description |
|---|
control_plane_bind | string | host:port the control-plane HTTP server binds to |
control_plane_endpoint | string | Publicly-reachable URL of the control plane |
recovery_sources | string[] | Event-export endpoints used for state recovery |
brain_provider | object | Brain provider configuration (see Brain Provider) |
autonomy_enabled | boolean | Enable the autonomous agent loop |
autonomy_interval_sec | integer | Seconds between autonomy loop ticks |
Environment Variables
When you deploy using npx wattetheria install, the CLI writes a .env file into the deploy directory. You can set the following variables there (or export them in your shell) to override configuration without editing config.json directly.
| Variable | Description |
|---|
WATTETHERIA_HOST_STATE_DIR | Absolute path on the host that is bind-mounted as the state directory inside containers |
WATTETHERIA_GATEWAY_URLS | Comma-separated list of gateway URLs the runtime connects to |
WATTETHERIA_WATTSWARM_UI_BASE_URL | Base URL used by the Wattswarm UI service |
| Variable | Description |
|---|
WATTETHERIA_BRAIN_PROVIDER_KIND | Brain provider type: rules, ollama, or openai-compatible |
WATTETHERIA_BRAIN_BASE_URL | Base URL of the brain provider API |
WATTETHERIA_BRAIN_MODEL | Model name to request from the brain provider |
WATTETHERIA_BRAIN_API_KEY | API key passed to the brain provider (for openai-compatible providers) |
The supervision console at http://127.0.0.1:7777/supervision exposes a UI card that lets you update brain provider settings and writes the result directly to the deploy .env — no manual file editing required.
Docker Networking
When the Wattetheria runtime runs inside Docker and your brain provider or AI gateway is a process on the host machine, localhost inside the container resolves to the container itself — not your workstation. Use Docker’s special hostname instead:
{
"brain_provider": {
"kind": "openai-compatible",
"base_url": "http://host.docker.internal:4000/v1",
"model": "my-model"
}
}
host.docker.internal is available on Docker Desktop (macOS and Windows) by default. On Linux, you may need to add --add-host=host.docker.internal:host-gateway to your Docker run flags, or set it via extra_hosts in your Compose file.
Applying Configuration Changes
After editing config.json or the deploy .env, restart the stack and run the diagnostics command to confirm that the new settings are picked up correctly.
npx wattetheria restart
npx wattetheria doctor --brain --connect
