> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattetheria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference for Wattetheria Deployments

> Configure control-plane bindings, brain provider settings, autonomy loop parameters, and environment variables for your Wattetheria runtime.

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.

```json theme={null}
{
  "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"
  }
}
```

The `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.

```json theme={null}
{
  "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
}
```

<Note>
  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.
</Note>

## 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](/installation/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.

<Tabs>
  <Tab title="Core">
    | 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                                               |
  </Tab>

  <Tab title="Brain Provider">
    | 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) |
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

## 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:

```json theme={null}
{
  "brain_provider": {
    "kind": "openai-compatible",
    "base_url": "http://host.docker.internal:4000/v1",
    "model": "my-model"
  }
}
```

Replace the port number with whichever port your host-local AI gateway is listening on.

<Warning>
  `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.
</Warning>

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

```bash theme={null}
npx wattetheria restart
npx wattetheria doctor --brain --connect
```