# rjmad1/ai-runtime-manager architecture

> Architecture diagram of the GitHub repository rjmad1/ai-runtime-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rjmad1/ai-runtime-manager
- Repository: https://github.com/rjmad1/ai-runtime-manager

## Overview

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: [`core/manager.py`](https://github.com/rjmad1/ai-runtime-manager/blob/main/core/manager.py) (manager.py), [`install.ps1`](https://github.com/rjmad1/ai-runtime-manager/blob/main/install.ps1) (install.ps1), [`core/bootstrap.ps1`](https://github.com/rjmad1/ai-runtime-manager/blob/main/core/bootstrap.ps1) (bootstrap.ps1), [`Install.bat`](https://github.com/rjmad1/ai-runtime-manager/blob/main/Install.bat) (Install.bat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Windows entrypoints"]
  node_install_batch["Install.bat<br/>wrapper<br/>[Install.bat]"]
  node_manage_batch["Manage.bat<br/>wrapper<br/>[Manage.bat]"]
  node_diagnose_batch["Diagnose.bat<br/>wrapper<br/>[Diagnose.bat]"]
  node_repair_batch["Repair.bat<br/>wrapper<br/>[Repair.bat]"]
  node_upgrade_batch["Upgrade.bat<br/>wrapper<br/>[Upgrade.bat]"]
  node_uninstall_batch["Uninstall.bat<br/>wrapper<br/>[Uninstall.bat]"]
end

subgraph group_core["Core orchestration"]
  node_install_ps1["install.ps1<br/>bootstrap entrypoint<br/>[install.ps1]"]
  node_bootstrap_ps1["bootstrap.ps1<br/>provisioning<br/>[bootstrap.ps1]"]
  node_manager_py{{"manager.py<br/>lifecycle orchestrator<br/>[manager.py]"}}
  node_prompt_server_py["prompt_server.py<br/>interactive setup<br/>[prompt_server.py]"]
end

subgraph group_state["Config and state"]
  node_settings_yaml["settings.yaml<br/>deployment settings<br/>[settings.yaml]"]
  node_providers_yaml["providers.yaml<br/>provider config<br/>[providers.yaml]"]
  node_models_yaml["models.yaml<br/>routing config<br/>[models.yaml]"]
  node_generated_litellm["LiteLLM config<br/>generated artifact"]
  node_generated_openclaw["OpenClaw config<br/>generated artifact"]
end

subgraph group_runtime["Managed runtime"]
  node_litellm_proxy[("LiteLLM Proxy<br/>runtime service")]
  node_openclaw_gateway[("OpenClaw Gateway<br/>runtime service")]
end

subgraph group_external["External systems"]
  node_os_tools["Windows host<br/>platform deps"]
  node_provider_apis(("Provider APIs<br/>remote endpoints"))
end

node_install_batch -->|"launches"| node_install_ps1
node_manage_batch -->|"invokes"| node_manager_py
node_diagnose_batch -->|"invokes"| node_manager_py
node_repair_batch -->|"invokes"| node_manager_py
node_upgrade_batch -->|"invokes"| node_manager_py
node_uninstall_batch -->|"invokes"| node_manager_py
node_install_ps1 -->|"bootstraps"| node_bootstrap_ps1
node_bootstrap_ps1 -->|"checks"| node_os_tools
node_manager_py -->|"reads"| node_settings_yaml
node_manager_py -->|"reads"| node_providers_yaml
node_manager_py -->|"reads"| node_models_yaml
node_manager_py -->|"writes"| node_generated_litellm
node_manager_py -->|"writes"| node_generated_openclaw
node_prompt_server_py -.->|"supports"| node_manager_py
node_generated_litellm -->|"configures"| node_litellm_proxy
node_generated_openclaw -->|"configures"| node_openclaw_gateway
node_manager_py -->|"starts/monitors"| node_litellm_proxy
node_manager_py -->|"starts/monitors"| node_openclaw_gateway
node_litellm_proxy -->|"routes to"| node_provider_apis
node_openclaw_gateway -->|"uses"| node_provider_apis

click node_install_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Install.bat"
click node_manage_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Manage.bat"
click node_diagnose_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Diagnose.bat"
click node_repair_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Repair.bat"
click node_upgrade_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Upgrade.bat"
click node_uninstall_batch "https://github.com/rjmad1/ai-runtime-manager/blob/main/Uninstall.bat"
click node_install_ps1 "https://github.com/rjmad1/ai-runtime-manager/blob/main/install.ps1"
click node_bootstrap_ps1 "https://github.com/rjmad1/ai-runtime-manager/blob/main/core/bootstrap.ps1"
click node_manager_py "https://github.com/rjmad1/ai-runtime-manager/blob/main/core/manager.py"
click node_prompt_server_py "https://github.com/rjmad1/ai-runtime-manager/blob/main/core/prompt_server.py"
click node_settings_yaml "https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/settings.yaml"
click node_providers_yaml "https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/providers.yaml"
click node_models_yaml "https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/models.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_install_batch,node_manage_batch,node_diagnose_batch,node_repair_batch,node_upgrade_batch,node_uninstall_batch toneBlue
class node_install_ps1,node_bootstrap_ps1,node_manager_py,node_prompt_server_py toneAmber
class node_settings_yaml,node_providers_yaml,node_models_yaml,node_generated_litellm,node_generated_openclaw toneMint
class node_litellm_proxy,node_openclaw_gateway toneRose
class node_os_tools,node_provider_apis toneIndigo
```

## Components

### Windows entrypoints

Operator-facing batch and PowerShell entrypoints for install and maintenance flows.

- [Install.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Install.bat): wrapper · Windows install entrypoint that launches the bootstrap flow. · `Install.bat`
- [Manage.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Manage.bat): wrapper · Primary operator shell for lifecycle actions. · `Manage.bat`
- [Diagnose.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Diagnose.bat): wrapper · Windows troubleshooting entrypoint. · `Diagnose.bat`
- [Repair.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Repair.bat): wrapper · Windows repair entrypoint. · `Repair.bat`
- [Upgrade.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Upgrade.bat): wrapper · Windows upgrade entrypoint. · `Upgrade.bat`
- [Uninstall.bat](https://github.com/rjmad1/ai-runtime-manager/blob/main/Uninstall.bat): wrapper · Windows removal entrypoint. · `Uninstall.bat`

### Core orchestration

Python and PowerShell components that coordinate lifecycle, bootstrap, and interactive setup.

- [install.ps1](https://github.com/rjmad1/ai-runtime-manager/blob/main/install.ps1): bootstrap entrypoint · First-run bootstrap script that starts repository setup. · `install.ps1`
- [bootstrap.ps1](https://github.com/rjmad1/ai-runtime-manager/blob/main/core/bootstrap.ps1): provisioning · Checks prerequisites and prepares the local environment. · `core/bootstrap.ps1`
- [manager.py](https://github.com/rjmad1/ai-runtime-manager/blob/main/core/manager.py): lifecycle orchestrator · Central coordinator for start, stop, diagnose, backup, restore, repair, upgrade, and uninstall. · `core/manager.py`
- [prompt_server.py](https://github.com/rjmad1/ai-runtime-manager/blob/main/core/prompt_server.py): interactive setup · 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](https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/settings.yaml): deployment settings · Source-of-truth ports, logging, backup, and Ollama-related settings. · `OpenClawManager/settings.yaml`
- [providers.yaml](https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/providers.yaml): provider config · Enabled AI provider integrations and adapter selection. · `OpenClawManager/providers.yaml`
- [models.yaml](https://github.com/rjmad1/ai-runtime-manager/blob/main/OpenClawManager/models.yaml): routing config · Model routing, context limits, and fallback chains. · `OpenClawManager/models.yaml`
- **LiteLLM config**: generated artifact · Derived proxy configuration generated from manager inputs.
- **OpenClaw config**: generated artifact · Derived gateway configuration generated from manager inputs.

### Managed runtime

The local service stack that the manager installs, runs, and repairs.

- **LiteLLM Proxy**: runtime service · Background proxy service started and monitored by the manager.
- **OpenClaw Gateway**: runtime service · Foreground gateway process started after LiteLLM health passes.

### External systems

Operating system dependencies and remote provider endpoints used by the stack.

- **Windows host**: platform deps · Local dependencies such as Git, Python, Node.js, and uv.
- **Provider APIs**: remote endpoints · External model backends such as Gemini, Groq, SambaNova, Cerebras, OpenRouter, and optional Ollama.

## Connections

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