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

# Wattetheria Brain Provider Setup and Configuration

> Choose and configure the brain provider for Wattetheria agents. Supports deterministic rules, local Ollama models, and any OpenAI-compatible API endpoint.

The brain provider is the reasoning backend that Wattetheria's autonomous loop consults when deciding what actions agents should take next. You select a provider by setting the `kind` field inside the `brain_provider` object in your `config.json`. Three providers are available out of the box, covering everything from fully deterministic operation to cloud-scale LLM inference.

## Provider Overview

<Tabs>
  <Tab title="rules">
    The `rules` provider uses a built-in, deterministic decision engine — no LLM is required. It is the fastest way to get the runtime running and is well-suited for environments where you want predictable, auditable behaviour without any external model dependency.

    ```json theme={null}
    {
      "brain_provider": {
        "kind": "rules"
      }
    }
    ```

    <Note>
      Because `rules` makes no network calls, it works fully offline and requires no additional credentials or services.
    </Note>
  </Tab>

  <Tab title="ollama">
    The `ollama` provider connects to a locally-running [Ollama](https://ollama.com) instance. This is the recommended choice for developers who want full local inference without sending data to a third-party API.

    The `base_url` and `model` fields are both required alongside `kind`.

    ```json theme={null}
    {
      "brain_provider": {
        "kind": "ollama",
        "base_url": "http://127.0.0.1:11434",
        "model": "qwen2.5:7b-instruct"
      }
    }
    ```

    <Tip>
      `qwen2.5:7b-instruct` offers a strong balance of reasoning quality and inference speed on consumer hardware. Pull it with `ollama pull qwen2.5:7b-instruct` before starting the runtime.
    </Tip>
  </Tab>

  <Tab title="openai-compatible">
    The `openai-compatible` provider works with any API that exposes an OpenAI-style `/v1` surface — including LiteLLM, vLLM, OpenRouter, and direct OpenAI or Anthropic proxies.

    The `base_url` and `model` fields are required. The optional `api_key_env` field names the **environment variable** that holds your API key (the key value itself is never written to `config.json`).

    ```json theme={null}
    {
      "brain_provider": {
        "kind": "openai-compatible",
        "base_url": "http://127.0.0.1:4000/v1",
        "model": "gpt-4o-mini",
        "api_key_env": "WATTETHERIA_BRAIN_API_KEY"
      },
      "autonomy_enabled": true,
      "autonomy_interval_sec": 30
    }
    ```

    Set the corresponding environment variable before starting the stack:

    ```bash theme={null}
    export WATTETHERIA_BRAIN_API_KEY="sk-..."
    ```
  </Tab>
</Tabs>

## Configuration Schema

All brain provider configurations share a common shape. The table below lists every supported field.

| Field         | Required for                  | Type     | Description                                              |
| ------------- | ----------------------------- | -------- | -------------------------------------------------------- |
| `kind`        | all                           | `string` | Provider type: `rules`, `ollama`, or `openai-compatible` |
| `base_url`    | `ollama`, `openai-compatible` | `string` | Base URL of the inference API                            |
| `model`       | `ollama`, `openai-compatible` | `string` | Model identifier to request                              |
| `api_key_env` | `openai-compatible`           | `string` | Name of the env var that holds the API key               |

<Warning>
  Do not place your actual API key value inside `config.json`. Use `api_key_env` to reference an environment variable name instead. This keeps credentials out of version control and out of the state directory.
</Warning>

## Using a Docker-Hosted Brain Provider

When the Wattetheria stack runs inside Docker and your AI gateway or Ollama instance is a process on the host machine, you must use Docker's special hostname in place of `localhost` or `127.0.0.1`:

<CodeGroup>
  ```json Ollama on Host theme={null}
  {
    "brain_provider": {
      "kind": "ollama",
      "base_url": "http://host.docker.internal:11434",
      "model": "qwen2.5:7b-instruct"
    }
  }
  ```

  ```json OpenAI-Compatible Gateway on Host theme={null}
  {
    "brain_provider": {
      "kind": "openai-compatible",
      "base_url": "http://host.docker.internal:4000/v1",
      "model": "gpt-4o-mini",
      "api_key_env": "WATTETHERIA_BRAIN_API_KEY"
    }
  }
  ```
</CodeGroup>

<Note>
  `host.docker.internal` resolves automatically on Docker Desktop (macOS and Windows). On Linux, add `extra_hosts: ["host.docker.internal:host-gateway"]` to the relevant service in your Compose file.
</Note>

## Using the Supervision Console

You do not have to edit `config.json` by hand to change the brain provider. The supervision console at `http://127.0.0.1:7777/supervision` includes a dedicated UI card for this purpose. Changes made through the console are written directly to the deploy `.env` file and take effect on the next restart — no file editing required.

## Validating the Brain Provider

After any change to the brain provider — whether via `config.json`, the `.env`, or the supervision console — run the diagnostics command to confirm that the runtime can reach the model and that agent attach status is current:

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

## CLI Brain Commands

The `wattetheria brain` sub-command lets you invoke the brain provider directly from the command line for testing and introspection. Both commands operate against the runtime state directory.

Use `propose-actions` to ask the brain to generate a set of candidate agent actions based on current runtime state:

```bash theme={null}
npx wattetheria brain --data-dir ./data/wattetheria propose-actions
```

Use `humanize-night-shift` to produce a human-readable summary of agent activity over a given time window (in hours):

```bash theme={null}
npx wattetheria brain --data-dir ./data/wattetheria humanize-night-shift --hours 24
```

<Tip>
  Run `humanize-night-shift` after leaving the autonomous loop running overnight to get a plain-language digest of what your agents did while you were away.
</Tip>