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

# The Local Runtime

> How the Headmaster agent engine works — the background service that handles model calls, tool execution, and session persistence.

# The Local Runtime

Headmaster Desktop runs two things side by side: the app you see, and a **local runtime** — a small background service that does the actual work of talking to model providers, running tools, and persisting sessions.

The runtime runs on your machine. It is not a cloud service. Your conversations, your files, and your provider credentials all stay local.

***

## Why the runtime exists

Splitting the agent into a background service keeps the desktop app responsive. Long-running tool calls, file operations, and provider requests happen in the service, not in the chat window.

If you close the chat window, the runtime keeps going. If you restart the app, the runtime comes back up automatically. This also means the agent can work while you're not looking — scheduled tasks, background downloads, and long-running tool calls continue even if the desktop window is minimized or closed.

***

## Runtime status indicator

You can see the runtime's state at any time from the **status indicator in the sidebar footer**:

| Status           | Meaning                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| **Connected**    | Both the REST API and the live event stream (WebSocket) are responding. Chat works normally.     |
| **Reconnecting** | The runtime is restarting, usually after an update or a crash. Chat is paused for a few seconds. |
| **Disconnected** | The runtime is not responding. Open **Settings → Headmaster's Library → Runtime** to see why.    |

Hover the indicator for a tooltip with the current port number and the last error (if any).

***

## Local vs. remote mode

By default, the desktop talks to a runtime on the same machine. You can point it at a runtime on a different machine — a more powerful desktop, a home server, or a Mac you use from a Windows laptop.

<Tabs>
  <Tab title="Local mode (default)">
    The runtime runs on the same machine as the desktop app. No network configuration needed.

    What you see in the Runtime tab:

    * **Status** — Connected, Reconnecting, or Disconnected.
    * **Port** — the local port the runtime listens on.
    * **PID** — the runtime process ID.
    * **Uptime** — how long the runtime has been running.
    * **Version** — the runtime version number.
  </Tab>

  <Tab title="Remote mode">
    The runtime runs on a different machine. The desktop app on your laptop is a thin client — it renders the UI and forwards input.

    In remote mode:

    * Conversations, memory, and files live on the **machine running the runtime**.
    * Provider credentials are stored on the **runtime machine**, not the laptop.

    <Steps>
      <Step title="Open Runtime settings">
        Go to **Settings → Headmaster's Library → Runtime**.
      </Step>

      <Step title="Switch to Remote">
        Set **Connection mode** to **Remote**.
      </Step>

      <Step title="Enter host and port">
        Enter the hostname or IP and port of the remote machine's runtime.
      </Step>

      <Step title="Test and save">
        Click **Test connection**. If it passes, click **Save**.
      </Step>
    </Steps>

    <Warning>
      In remote mode, make sure the runtime machine is one you control. Your messages, conversation history, and provider keys are stored on that machine.
    </Warning>
  </Tab>
</Tabs>

***

## Restarting the runtime

The runtime is started and managed by the desktop app. You don't usually need to restart it. If it gets stuck:

<Steps>
  <Step title="Open Runtime settings">
    Go to **Settings → Headmaster's Library → Runtime → Restart**.
  </Step>

  <Step title="Wait for reconnect">
    The runtime process is torn down and a fresh one starts. The status indicator flips back to **Connected** within a few seconds.
  </Step>
</Steps>

<Note>
  Restarting does not lose your data. Sessions and memory live in the user data folder, not in the runtime process.
</Note>

***

## Where data lives

The runtime stores its data in a folder owned by your user account:

| Platform    | Data folder                                |
| ----------- | ------------------------------------------ |
| **Windows** | `%APPDATA%\Headmaster`                     |
| **macOS**   | `~/Library/Application Support/Headmaster` |
| **Linux**   | `~/.config/Headmaster`                     |

Inside that folder:

| Subfolder     | What's in it                                  |
| ------------- | --------------------------------------------- |
| `logs/`       | Daily log files: `YYYY-MM-DD.log`             |
| `sessions/`   | Conversation transcripts and session metadata |
| `memory/`     | Agent memory store                            |
| `config/`     | Runtime configuration (`config.yaml`)         |
| `skills/`     | Installed skill packages                      |
| `extensions/` | Installed specialist extensions               |
| `cache/`      | Temporary caches (previews, downloads)        |

***

## Log files

Logs are at `<data folder>/logs/YYYY-MM-DD.log`. Each line has a timestamp, a log level (`INFO`, `WARN`, `ERROR`), and a message.

To change the log level:

<Steps>
  <Step title="Open log level settings">
    Go to **Settings → Headmaster's Library → Advanced → Log level**.
  </Step>

  <Step title="Pick a level">
    * `DEBUG` — verbose detail, useful when debugging.
    * `INFO` — normal use (default).
    * `WARN` — warnings only.
    * `ERROR` — errors only.
  </Step>

  <Step title="Restart the runtime">
    The change takes effect after a runtime restart.
  </Step>
</Steps>

<Tip>
  When reporting a bug, attach the most recent log file from `<data folder>/logs/`.
</Tip>

***

## Runtime configuration file

The runtime reads its configuration from `config.yaml` in the data folder. You normally don't edit this directly — the Settings UI writes it for you. But if you need to make a change the UI doesn't cover, you can edit it directly and restart the runtime.

```yaml theme={null}
# Model defaults
model:
  default: "claude-sonnet-4"
  fallback: "gpt-4o"

# Provider keys (also settable via the UI)
providers:
  anthropic:
    api_keys:
      - "sk-ant-..."
  openai:
    api_keys:
      - "sk-..."

# Memory
memory:
  retention_days: 90
  max_context_tokens: 50000

# Logging
log_level: "INFO"
```

<Warning>
  Do not edit the config file while the runtime is running — it may overwrite your changes on exit. Quit Headmaster first, edit, then relaunch.
</Warning>

***

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Fixes for runtime not connecting, crash loops, and 401 errors.
  </Card>

  <Card title="Runtime Settings" icon="gear" href="/runtime-settings">
    Full reference for all runtime configuration options.
  </Card>
</CardGroup>