Viaduct

Open-source control plane for virtualization migration assessment, planning, and controlled operator execution.

Viaduct helps operators discover mixed virtualization estates, map dependencies, build migration plans, and manage controlled migration work from one shared backend model. The repository combines a Go backend, REST API, CLI, React dashboard, and standalone public site around the same persisted inventory, workspace, planning, and reporting surfaces.

Current Focus

Viaduct is built for operators who need:

• mixed-estate discovery and inventory normalization
• dependency-aware migration assessment
• readiness and planning discipline before cutover work starts
• controlled, reviewable operator workflows with exported evidence

The default first-run experience is the WebUI-first workspace flow: start Viaduct, create a workspace, discover, inspect, simulate, save a plan, and export a report. The local lab remains the fastest path from fresh clone to a working dashboard and API.

Why Viaduct

Many teams do not need more abstract migration talk. They need to know what exists, what depends on what, what should move first, and what evidence is good enough to approve a pilot. Viaduct is aimed at that planning and handoff gap.

It is strongest when operators need:

• one normalized inventory across mixed platforms
• dependency context before sequencing migration work
• a persisted assessment record instead of disconnected notes and screenshots
• a CLI, API, and dashboard that reflect the same state

What You Can Evaluate Today

• Discovery: normalize inventory from VMware, Proxmox, Hyper-V, KVM, Nutanix, and Veeam-related backup systems into the shared model.
• Dependency mapping: build workload, network, storage, and backup graph context before execution.
• Pilot workspace workflow: persist source connections, snapshots, graph outputs, target assumptions, readiness results, saved plans, approvals, notes, and exported reports in one operator record.
• Migration planning: use declarative specs, preflight checks, saved dry-run plans, execution windows, approval requirements, checkpoints, resume support, and rollback state.
• Lifecycle analysis: review drift, policy, cost, remediation guidance, and backup portability inputs in the same control plane.
• Multi-tenancy and extensibility: use tenant-scoped APIs, service accounts, PostgreSQL-backed state, and the community plugin host.

Platform Coverage

Platform / Integration	Status	Notes
VMware vSphere	Implemented	vCenter discovery with VM and infrastructure metadata.
Proxmox VE	Implemented	REST-based discovery and a common target in current pilot examples.
Microsoft Hyper-V	Implemented	WinRM and PowerShell-backed inventory collection.
KVM / libvirt	Implemented	XML-backed fallback works out of the box; live libvirt support is available behind the libvirt build tag.
Nutanix AHV	Implemented	Prism Central v3 inventory collection.
Veeam Backup & Replication	Implemented	Backup discovery, restore-point correlation, and portability planning support.
Community plugins	Supported	gRPC plugin host with manifest and compatibility checks.

First Run

The cleanest path is the local lab in examples/lab.

make build
make web-build
./bin/viaduct version
./bin/viaduct start

On a fresh source checkout, viaduct start:

• creates ~/.viaduct/config.yaml automatically when it is missing
• points that config at the shipped examples/lab/kvm fixtures
• serves the built dashboard and API together at http://127.0.0.1:8080
• opens the WebUI automatically on interactive local runs when practical

For the default local lab path, the dashboard can use the built-in single-user fallback and does not require a pasted browser key. Tenant keys and service-account keys remain supported for multi-tenant, packaged, and pilot environments.

Use these companion commands when you need them:

./bin/viaduct status --runtime
./bin/viaduct doctor
./bin/viaduct stop

viaduct serve-api remains the lower-level API command for container, service, and intentionally headless deployments. It still serves the built dashboard automatically when assets are present in web/dist, a packaged web/ directory, or an installed share/viaduct/web layout. If you prefer the Vite development server while changing frontend code, that flow still lives in web/README.md.

If you serve the dashboard from a different browser origin, configure VIADUCT_ALLOWED_ORIGINS on the API so tenant-protected routes can be reached safely. The default same-origin local path on http://127.0.0.1:8080 does not need that override.

Use these entrypoints next:

• Quickstart: QUICKSTART.md
• Detailed quickstart: docs/getting-started/quickstart.md
• Pilot workspace guide: docs/operations/pilot-workspace-flow.md

Repository Surfaces

• cmd/viaduct/: CLI entrypoints.
• internal/: discovery, dependency mapping, migration orchestration, lifecycle analysis, API server, and state store packages.
• web/: React dashboard for operator workflows.
• site/: separate static public site for GitHub Pages.
• examples/: lab, deployment, and plugin evaluation assets.
• docs/: deeper reference, operations, and product-scope documentation.

Verification

make release-gate is the canonical verification path. It keeps backend checks, web build validation, coverage enforcement, packaging, and the lab-oriented smoke flow aligned in one command.

Other high-signal commands:

make build
make certification-test
make soak-test
make contract-check
make package-release-matrix

Documentation

• Overview and status: README.md
• Install: INSTALL.md
• Quickstart: QUICKSTART.md
• Upgrade: UPGRADE.md
• Release process: RELEASE.md
• Release notes: docs/releases/README.md
• Support: SUPPORT.md
• Security: SECURITY.md
• Documentation index: docs/README.md
• API contract: docs/reference/openapi.yaml
• Support matrix: docs/reference/support-matrix.md

Contributing

Contributions are welcome. Keep docs, examples, and public-facing assets aligned with operator-visible behavior. See CONTRIBUTING.md for workflow and verification expectations.

Support And Security

• Usage, evaluation, and troubleshooting: SUPPORT.md
• Security reporting: SECURITY.md
• Project change history: CHANGELOG.md
• Community expectations: CODE_OF_CONDUCT.md

License

Viaduct is licensed under the Apache License 2.0.