How rjmad1/ai-runtime-manager works
1. What this repo is
- This is a Windows-first lifecycle manager for two runtime products: LiteLLM and OpenClaw.
- Its job is not to host application logic itself, but to install, configure, run, repair, back up, and upgrade the workstation stack.
2. Primary control plane
- The main orchestration logic lives in core/manager.py.
- That Python layer is the central coordinator for lifecycle actions such as start/stop/status/configure/backup/restore/diagnose/repair/upgrade/uninstall.
- The batch scripts at the repo root are thin command wrappers around that core.
3. User-facing entrypoints
- Install.bat, Manage.bat, Diagnose.bat, Repair.bat, Upgrade.bat, Uninstall.bat are the operator interface.
- install.ps1 is the bootstrap entrypoint for first-time deployment, and the README’s one-line install command points here.
- These wrappers matter architecturally because they define the supported operational flows on Windows.
4. Bootstrap and environment provisioning
- core/bootstrap.ps1 and install.ps1 handle machine setup: fetching the repository, checking prerequisites, and preparing the runtime environment.
- The README indicates the bootstrap layer also installs or validates Git, Python 3.11+, Node.js LTS, and uv.
- This means the repo includes both provisioning logic and runtime orchestration, not just config generation.
5. Declarative configuration boundary
- The editable, source-of-truth inputs are the YAML files under OpenClawManager/:
- settings.yaml: ports, logging, backups, Ollama-related options.
- providers.yaml: enabled AI provider integrations.
- models.yaml: model routing, context limits, and fallback chains.
- Everything else is derived from these files, so the architecture centers on config compilation from declarative inputs.
6. Generated runtime artifacts
- The README states that the manager compiles and maintains generated configs such as LiteLLM config.yaml and OpenClaw openclaw.json automatically.
- This creates a clear boundary between:
- authoritative human-edited settings in OpenClawManager/
- machine-generated deployment artifacts consumed by LiteLLM/OpenClaw
- For an architecture diagram, treat the YAML inputs as the source layer and the runtime configs as derived outputs.
7. Service topology at runtime
- The operational flow is split between two services:
- LiteLLM Proxy runs in the background.
- OpenClaw Gateway starts in the foreground after LiteLLM health checks pass.
- The manager also monitors and scavenges ports, specifically 4000 and 18789 per the README.
- That suggests a two-process local stack with a dependency chain: proxy first, gateway second.
8. Provider and model integration layer
- The repo is built around connecting OpenClaw to multiple LLM providers, including those named in the README: Gemini, Groq, SambaNova, Cerebras, OpenRouter, plus optional Ollama integration.
- providers.yaml toggles which provider adapters are active.
- models.yaml defines routing and fallback behavior, so model selection is managed centrally rather than inside the applications.
9. Interactive setup/support tooling
- core/prompt_server.py appears to support a local interactive flow used during provisioning or key setup.
- The README describes a “Visual Browser Assistant” for securely configuring API keys on the local machine, so this file likely backs that experience.
- In the architecture, this is a support subsystem distinct from the main service runtime.
10. Operational maintenance flows
- The manager exposes dedicated maintenance paths:
- backup/restore for config and keys
- diagnose for latency and model connectivity checks
- repair for clearing stuck processes, freeing ports, and auditing schema/config issues
- upgrade for refreshing LiteLLM packages and OpenClaw versioning
- These flows indicate the repo is designed as a self-healing workstation manager, not just an installer.
11. Persistence and safety boundaries
- Backups are timestamped and restore is described as Zip Slip protected, which implies a deliberate security boundary around archive handling.
- The config workspace under OpenClawManager/ is the durable state layer; the Python core and scripts mostly act on that state and on process/runtime state.
12. Infrastructure assumptions
- The entire design assumes Windows, PowerShell, and batch script execution, with Python as the core automation runtime.
- External dependencies are mostly local tooling and remote model/provider APIs, rather than cloud infrastructure owned by this repo.
- If diagramming it, place the repo as a local workstation orchestrator between the operator, the Windows host, and external AI provider endpoints.
Main entry points: manager.py manager.py · install.ps1 install.ps1 · bootstrap.ps1 bootstrap.ps1 · Install.bat Install.bat
Components 19
Windows entrypoints
Operator-facing batch and PowerShell entrypoints for install and maintenance flows.
- Install.bat · Windows install entrypoint that launches the bootstrap flow.
Install.bat - Manage.bat · Primary operator shell for lifecycle actions.
Manage.bat - Diagnose.bat · Windows troubleshooting entrypoint.
Diagnose.bat - Repair.bat · Windows repair entrypoint.
Repair.bat - Upgrade.bat · Windows upgrade entrypoint.
Upgrade.bat - Uninstall.bat · Windows removal entrypoint.
Uninstall.bat
Core orchestration
Python and PowerShell components that coordinate lifecycle, bootstrap, and interactive setup.
- install.ps1 · First-run bootstrap script that starts repository setup.
install.ps1 - bootstrap.ps1 · Checks prerequisites and prepares the local environment.
core/bootstrap.ps1 - manager.py · Central coordinator for start, stop, diagnose, backup, restore, repair, upgrade, and uninstall.
core/manager.py - prompt_server.py · Local interactive helper for secure prompt and key setup flows.
core/prompt_server.py
Config and state
Declarative source inputs and generated runtime artifacts maintained by the manager.
- settings.yaml · Source-of-truth ports, logging, backup, and Ollama-related settings.
OpenClawManager/settings.yaml - providers.yaml · Enabled AI provider integrations and adapter selection.
OpenClawManager/providers.yaml - models.yaml · Model routing, context limits, and fallback chains.
OpenClawManager/models.yaml - LiteLLM config · Derived proxy configuration generated from manager inputs.
- OpenClaw config · Derived gateway configuration generated from manager inputs.
Managed runtime
The local service stack that the manager installs, runs, and repairs.
- LiteLLM Proxy · Background proxy service started and monitored by the manager.
- OpenClaw Gateway · Foreground gateway process started after LiteLLM health passes.
External systems
Operating system dependencies and remote provider endpoints used by the stack.
- Windows host · Local dependencies such as Git, Python, Node.js, and uv.
- Provider APIs · External model backends such as Gemini, Groq, SambaNova, Cerebras, OpenRouter, and optional Ollama.
Connections 20
- Install.bat → install.ps1: launches · Batch wrapper delegates first-time setup to the PowerShell bootstrap.
- Manage.bat → manager.py: invokes · Primary management wrapper calls the lifecycle orchestrator.
- Diagnose.bat → manager.py: invokes · Troubleshooting wrapper enters diagnostic flows.
- Repair.bat → manager.py: invokes · Repair wrapper enters recovery flows.
- Upgrade.bat → manager.py: invokes · Upgrade wrapper enters refresh flows.
- Uninstall.bat → manager.py: invokes · Removal wrapper enters uninstall flow.
- install.ps1 → bootstrap.ps1: bootstraps · Initial deployment hands off to the provisioning layer.
- bootstrap.ps1 → Windows host: checks · Bootstrap validates and prepares local prerequisites.
- manager.py → settings.yaml: reads · Manager consumes the authoritative settings workspace.
- manager.py → providers.yaml: reads · Manager reads provider enablement and adapter choices.
- manager.py → models.yaml: reads · Manager reads model routing and fallback rules.
- manager.py → LiteLLM config: writes · Manager compiles the proxy config artifact.
- manager.py → OpenClaw config: writes · Manager compiles the gateway config artifact.
- prompt_server.py → manager.py: supports · Interactive setup helper feeds the main orchestration.
- LiteLLM config → LiteLLM Proxy: configures · Derived proxy config drives the LiteLLM runtime.
- OpenClaw config → OpenClaw Gateway: configures · Derived gateway config drives the OpenClaw runtime.
- manager.py → LiteLLM Proxy: starts/monitors · Manager controls proxy lifecycle and health.
- manager.py → OpenClaw Gateway: starts/monitors · Manager starts gateway after proxy health checks.
- LiteLLM Proxy → Provider APIs: routes to · Proxy forwards requests to selected provider backends.
- OpenClaw Gateway → Provider APIs: uses · Gateway depends on the configured provider/model routing.