# 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. When code-server is requested, Agent provisioning should install it, start it, verify it, and expose controls for later start/stop/restart operations.

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
- reconcile requested code-server state during dev provisioning and expose `/dev/codeserver/start`, `/dev/codeserver/stop`, and `/dev/codeserver/restart`

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