Skip to main content

​
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: 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.
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.

​
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:
1

Open Runtime settings

Go to Settings → Headmaster’s Library → Runtime → Restart.
2

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.
Restarting does not lose your data. Sessions and memory live in the user data folder, not in the runtime process.

​
Where data lives

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

​
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:
1

Open log level settings

Go to Settings → Headmaster’s Library → Advanced → Log level.
2

Pick a level

  • DEBUG — verbose detail, useful when debugging.
  • INFO — normal use (default).
  • WARN — warnings only.
  • ERROR — errors only.
3

Restart the runtime

The change takes effect after a runtime restart.
When reporting a bug, attach the most recent log file from <data folder>/logs/.

​
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.
Do not edit the config file while the runtime is running — it may overwrite your changes on exit. Quit Headmaster first, edit, then relaunch.

Troubleshooting

Fixes for runtime not connecting, crash loops, and 401 errors.

Runtime Settings

Full reference for all runtime configuration options.