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

# Runtime Settings

> Configure the Headmaster runtime engine — connection mode, local vs. remote, session management, and schema-driven settings.

# Runtime Settings

**Path:** Headmaster's Library → Runtime (PIN-protected)

These settings configure the Hermes runtime engine — the background service that runs your agents. The runtime handles model inference, tool execution, memory storage, scheduled tasks, and MCP server connections.

***

## Connection mode

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

    What you see:

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

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

    <Steps>
      <Step title="Switch to Remote">
        Click **Connection mode → 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 the test passes, click **Save**. The desktop disconnects from the local runtime and connects to the remote one.
      </Step>
    </Steps>

    What you see:

    * **Host** — the hostname or IP of the remote machine.
    * **Port** — the port on the remote machine.
    * **Status** — Connected, Reconnecting, or Disconnected.
    * **Latency** — round-trip time to the remote runtime.
    * **Version** — the remote runtime version number.
  </Tab>
</Tabs>

***

## Restart

Click **Restart** to tear down the current runtime process and start a fresh one.

<Note>
  Restarting does not lose your data — sessions and memory live in the user data folder, not in the process. Use restart when:

  * The runtime is stuck or unresponsive.
  * You changed the config file manually and need to reload it.
  * After installing a new skill or integration that requires a runtime restart.
</Note>

***

## Sessions

Click **Sessions** to see the list of active sessions on the runtime. Each session shows:

| Field        | Description                           |
| ------------ | ------------------------------------- |
| Session ID   | Unique identifier                     |
| Profile name | Which profile this session belongs to |
| Model        | The model in use                      |
| Start time   | When the session started              |
| Status       | Active, idle, or stale                |

You can delete a stale session from this list. This clears the runtime's in-memory state for that session but does not delete the transcript file.

***

## Schema-driven settings

The runtime exposes a configuration schema at `/api/config/schema`. The Settings UI reads this schema and renders the appropriate controls — text fields, dropdowns, toggles, sliders — with descriptions, defaults, and validation.

This means when the runtime adds a new configuration option, the Settings UI picks it up automatically. You don't need a desktop app update to see new runtime settings.

***

<CardGroup cols={2}>
  <Card title="The Local Runtime" icon="server" href="/the-local-runtime">
    How the runtime works, where data lives, and log files.
  </Card>

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