ovc-agent (Hyper-V)

Hyper-V agent for the Open vCenter. Runs as a Windows service and communicates exclusively via RabbitMQ with ovc-backend. Build for Windows only.

The queue protocol (<hostid>.*) and the request/response and inventory payloads are hypervisor-agnostic - in the future other agents (libvirt/KVM) will implement the same contract.

Architecture

cmd/agent/main.go            entrypoint, service registration, consume loop, schedulers
internal/
├── config/                  reads config.ini + config.backend.ini (next to the binary)
├── preflight/               validates the Hyper-V role at startup
├── protocol/                AgentRequest / AgentResponse / *Payload (mirrors protocol.py)
├── rabbitmq/                connection (reconnect), consumer (<hostid>.request), publisher
├── jobstore/                persistent job queue in SQLite (modernc.org/sqlite)
├── jobqueue/                job dispatcher/monitor/scheduler/retention/classifier
├── worker/                  runs a single job in a subprocess (`ovc-agent.exe job <id>`)
├── tasks/                   dispatcher by `function` + handlers (vm_management, host_management, inventories)
├── download/               binary download + checksum on upgrade
├── upgrade/                 binary swap / drain mode
├── hyperv/                  PowerShell execution
├── hostinfo/               ISO, disk and uptime scanning (native Go)
└── service/                integration with the Windows Service Manager

Configuration

The agent has no fixed installation folder: the folder where the binary lives is the "default" folder. config.ini, agent.log, jobs.db and the upgrade binaries all sit next to ovc-agent.exe.

Configuration is read from config.ini (no registry, no environment variables), then from config.backend.ini next to it. The agent writes that second file with the settings the backend pushes (today metrics_interval), and its values win over config.ini. Don't edit it by hand.

config.ini (next to the binary)

[agent]
host_id = <id generated by the backend when the host is registered>
rabbitmq_url = amqp://user:pass@rabbitmq-server:5672/
log_level = info
; log_file is optional - defaults to agent.log next to the binary
task_timeout = 60
refresh_interval_vms = 180
refresh_interval_host = 600
; host settings (power plan, core isolation, page file, live migration...); 0 = off
refresh_interval_settings = 1800
; liveness heartbeat (agent_status); independent of refresh_interval_host,
; must stay below the backend's agent_offline_after_seconds (120s). Optional.
heartbeat_interval = 60
; metrics collection window; replaced by the backend's setting
metrics_interval = 300
template_path = D:\HyperV\TEMPLATES
local_iso_path = D:\HyperV\ISOS
aditional_vm_storage = E:\HyperV
max_concurrent_jobs = 4

Build

./build.sh          # macOS / Linux / WSL  -> ./ovc-agent.exe
.\build.ps1         # Windows (PowerShell) -> .\ovc-agent.exe

Both wrap GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o ovc-agent.exe ./cmd/agent and print the version from internal/tasks/agent_status.go (AgentVersion). Pass an output path as the first arg to build elsewhere.

Installation and management

ovc-agent.exe install     # installs the Windows service
ovc-agent.exe start
ovc-agent.exe stop
ovc-agent.exe uninstall
ovc-agent.exe version

sc start ovc-agent / sc stop ovc-agent also work.

RabbitMQ queues (per host)

Queue	Direction	Notes
<hostid>.request	backend → agent	JSON requests (AgentRequest)
<hostid>.response	agent → backend	task responses (AgentResponse)
<hostid>.agent_status	agent → backend	last-value; version, intervals, hypervisor
<hostid>.vm_inventory	agent → backend	last-value
<hostid>.host_inventory	agent → backend	last-value; hardware
<hostid>.template_inventory	agent → backend	last-value
<hostid>.iso_inventory	agent → backend	last-value

The last-value queues are declared with x-max-length=1 / x-overflow=drop-head.

Supported functions (AgentRequest.function)

• vm_management: vm_create, vm_edit, vm_start, vm_stop, vm_shutdown, vm_restart, vm_delete, vm_inventory (+ snapshot_*, vm_migrate, mount_dvd, eject_dvd, enable_ha, disable_ha, vm_export_template, vm_rename, vm_move, vm_clone, notes_edit, refresh_status, vm_batch_start, vm_batch_stop)
• host_management: host_hwinventory, host_update_agent (agent upgrade), host_restart_agent (+ cluster: suspend, suspend_drain, resume, resume_fallback, restart)
• periodic inventories: agent_status, vm_inventory, host_hwinventory, template_inventory, iso_inventory

Startup

At startup the agent validates that the Hyper-V role is installed. If it is not, it writes agent_failed.log (next to the binary) with the reason and exits.

Requirements

• Windows Server 2016+ with the Hyper-V role
• Go 1.25+ (for building)
• RabbitMQ reachable on the network
• Administrator permissions

Disclaimer

Open vCenter is an independent, community-driven open source project. It is not affiliated with, endorsed by, sponsored by or supported by Microsoft, VMware, Broadcom or any other vendor whose products it works with or is compared to.

Microsoft, Windows, Windows Server and Hyper-V are trademarks of the Microsoft group of companies. VMware, ESXi, vSphere, vCenter and vMotion are trademarks of Broadcom Inc. and/or its subsidiaries. All other trademarks belong to their respective owners.

The "vCenter" in the project's name refers to the general idea of a virtualization management center, not to VMware's product.

The software is provided "as is", without warranty of any kind - see LICENSE. Use it at your own risk, and try it on machines you can afford to lose before trusting it with the ones you cannot.