diff --git a/Codex/Agent/AGENT_OVERVIEW.md b/Codex/Agent/AGENT_OVERVIEW.md new file mode 100644 index 0000000..b7c8d82 --- /dev/null +++ b/Codex/Agent/AGENT_OVERVIEW.md @@ -0,0 +1,34 @@ +# Agent Overview + +The Agent is the software that runs inside a ZeroLagHub provisioned container and manages the workload on that machine. + +For game containers, the Agent is responsible for installing and running the game server, exposing operational controls, reporting status and readiness, supervising crashes, managing console access, and handling local app-aware recovery tasks such as Minecraft backups and restores. + +For dev containers, the Agent is responsible for preparing the runtime environment, workspace, user shell, and container-local developer tooling such as code-server. + +The Agent is intentionally container-local. It should make the workload inside the container reliable and observable, but it should not own platform-level orchestration, billing, portal UX, API product policy, or offsite disaster-recovery strategy. + +## Core Responsibilities + +- install and verify supported runtimes and game server files +- start, stop, restart, and supervise the managed workload +- expose workload status, readiness, and operation state +- serialize guarded mutating operations so conflicting actions do not overlap +- provide validated file and console operations where supported +- manage local Minecraft backup, restore, and checkpoint behavior +- support dev-container environment setup and local developer tooling + +## Current Backup Boundary + +Agent backup support is local and app-aware. It currently applies only to Minecraft game containers and stores backups under `/opt/zlh-agent/backups`. + +Minecraft restore creates a pre-restore checkpoint before destructive restore work begins. Remote/object storage and platform/offsite backups are separate concerns and should not be added to Agent unless that ownership decision changes. + +## What Agent Does Not Own + +- Portal UI or user-facing product workflows +- API-only response normalization unless it directly affects Agent integration +- provider billing or account management +- infrastructure-level orchestration outside the container +- PBS/platform disaster recovery or remote backup policy +- broad backup support for unsupported games or dev containers