Skip to content

About

Local-first Hyper-V VM control for humans and AI agents: Go CLI, daemon, MCP, and direct recovery paths. In development.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Agent Machine Control

Agent Machine Control is a local-first control plane for virtual machines that gives humans, CLI automation, and MCP-capable agents the same policy-enforced operations.

Warning

This project is pre-alpha. Discovery, privileged recovery mutations, daemon operations, MCP, and persistent SSH/PTTY sessions are implemented, but live Windows acceptance and the remaining release backlog are incomplete. Do not use unreleased development builds on production systems.

Design goals

  • One domain core shared by CLI and MCP, so behavior cannot drift between clients.
  • A direct CLI recovery path that remains usable when the daemon or MCP adapter is down.
  • Fast persistent terminal and desktop sessions without making a third-party sidecar the security boundary.
  • Capability-based hypervisor backends rather than hard-coded assumptions about one VM.
  • Server-side approvals, redacted receipts, least privilege, and explicit rollback boundaries.

Hyper-V is the first backend and Windows 10 LTSC is the first acceptance target. The design leaves room for libvirt, VMware, and VirtualBox backends without pretending that their capabilities are identical.

Available executables

Binary Purpose
amc Human- and agent-friendly CLI, including local --direct recovery mode.
amcd Authenticated operations, redacted receipts, audit, and persistent sessions.
amc-mcp Thin stdio and Streamable HTTP adapter over the shared application core.

Implemented commands

amc implements discovery and direct recovery commands for local Hyper-V management:

# Check Hyper-V and host readiness
amc doctor
amc doctor --json

# Discover candidates before an operator enrolls one local target
amc target candidates
amc target candidates --json

# After enrollment, ordinary reads expose only that target
amc machine list
amc machine list --json

# Inspect the enrolled target by default, exact alias, GUID, or canonical locator
amc machine inspect
amc machine inspect local --json

# Direct recovery mutations (in-process fallback when daemon is down)
amc --direct machine start <guid> --reason "recovering vm" --idempotency-key "k-1"
amc --direct machine stop <guid> --mode shutdown --reason "stopping vm" --idempotency-key "k-2"
amc --direct checkpoint list <guid>
amc --direct checkpoint create <guid> --name "pre-maintenance" --reason "snapshotting" --idempotency-key "k-3"
amc --direct checkpoint restore <guid> <checkpoint-guid> --reason "reverting vm" --idempotency-key "k-4"

Target enrollment and clearing are separate operator-only, approval-bound authority mutations. In normal mode they use amcd; --direct uses the same protected local store and coordinator:

amc target approve enroll <guid> --alias local --reason "select recovery target" \
  --idempotency-key "target-enroll-1" --valid-for 1m
amc target enroll <guid> --alias local --reason "select recovery target" \
  --idempotency-key "target-enroll-1" --approval-id <approval-id> --deadline <exact-deadline>

Daemon-backed CLI commands and the MCP adapter expose the same application service for managed operations, receipts, audit records, and persistent guest SSH/PTTY sessions. See Persistent SSH sessions for session setup, security boundaries, and the session open, read, write, control, wait, list, show, close, and operator-only session approve commands.

Guest window/UIA actions, cursor and clipboard access, application launch, bounded GIF recordings, and operator-enabled agent lab sessions are available through desktop_observe, desktop_act, and console_record. See Guest desktop control for the interaction loop and the capability matrix for acceptance boundaries.

Native Hyper-V screenshots and keyboard/pointer actions are available through amc console, console_screenshot, and console_input. See Native VM console for private PNG output, frame coordinates, exact approvals, and acceptance limits.

Privileged daemon machine/checkpoint mutations use a server-issued reference rather than a caller supplied approval object. An authenticated operator can prepare the exact current operation and then execute it with the returned ID and deadline:

amc operation approve machine.stop <guid> --mode turn-off \
  --reason "emergency power off" --idempotency-key "power-off-1" --valid-for 1m

amc machine stop <guid> --mode turn-off --reason "emergency power off" \
  --idempotency-key "power-off-1" --approval-id <approval-id> --deadline <exact-deadline>

Use --for-mcp during issuance to bind the grant to agent:mcp-local. The existing MCP mutation tools accept the same optional approval_id plus exact deadline; MCP exposes no issuance tool. Automatic daemon CLI retry after an approval_required result remains deferred to the target/CLI UX slice, so this release uses the explicit two-step flow above. Direct mode retains its independent local confirmation and server-owned approval store.

JSON mode

Every command supports --json for machine-readable automation. Output envelopes conform to schema version 1, emitting sorted arrays for capabilities, machines, network_adapters, and ip_addresses.

Enrolled-target references

Before enrollment, ordinary machine and checkpoint reads and mutations fail closed. After enrollment, they accept only the omitted/default target, the stored exact alias, the exact enrolled GUID, or its canonical local:<guid> locator. Display names and fuzzy matching never select a target.

Hyper-V and PowerShell prerequisites

Observation and recovery operations require powershell.exe in PATH, the Windows Hyper-V PowerShell module (Hyper-V), and a Windows security token with membership in the local Administrators (S-1-5-32-544) or Hyper-V Administrators (S-1-5-32-578) group.

  • Windows: powershell.exe is available by default on Windows systems. The current user token must belong to local Administrators or Hyper-V Administrators.
  • WSL interop: When running inside WSL, WSL interop discovers powershell.exe in the host Windows PATH (for example /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe) and queries the host Hyper-V instance. The host Windows security token must belong to local Administrators or Hyper-V Administrators.

Exit categories and codes

amc uses deterministic process exit codes:

Code Name Description
0 ExitSuccess Normal successful completion.
2 ExitUsage Incorrect command invocation, missing arguments, or invalid flags.
3 ExitNotFound The requested virtual machine GUID was not found.
4 ExitBackendUnavailable PowerShell, the Hyper-V module, or host management is unreachable or denied.
5 ExitMalformedProvider The provider returned corrupt, invalid, or oversized data.
6 ExitTimeout The operation exceeded its configured deadline.
7 ExitDenied Policy evaluation denied the operation, or interactive confirmation was rejected.
8 ExitConflict Concurrent lease conflict, fencing violation, or idempotency key collision.

Privileged-operation boundary

Observation and mutation operations are scope-gated. Mutations carry an actor, reason, deadline, and idempotency key and pass through server-owned policy, lease, audit, approval, and redacted receipt handling. amc --direct keeps an independent in-process recovery path while using the same application contracts and shared host coordination. Persistent SSH/PTTY sessions require amcd; they do not make guest sidecars authoritative for policy, identity, approval, or audit truth.

amcd bootstrap ensure|status|start|stop|remove manages the single current-user S4U Limited Scheduled Task that starts local WSL amcd automatically. It fingerprints the exact principal, logon trigger, settings, action, wrapper, metadata, binary, state directory, and process identity; drift is refused rather than repaired. See Automatic local amcd bootstrap.

Current release backlog

Hyper-V console framebuffer capture and synthetic input, the optional Windows UIA sidecar, the operator web/MCP App UI, signed packaging, and the cross-client Windows canary are not complete. The repository does not claim live Windows acceptance for these capabilities.

Build the bootstrap

Go 1.26 or newer is required.

go test ./...
go build ./cmd/...
go run ./cmd/amc --version

The public API and command surface are not stable before v0.1.0.

Documentation

Security and contributions

Machine-control software is privileged by nature. Read SECURITY.md before testing and never publish credentials, real guest data, private topology, memory dumps, or unredacted automation transcripts.

Contributions are welcome under the Apache License 2.0. Start with CONTRIBUTING.md and the Code of Conduct.

The repository includes an optional pinned code-review-graph MCP configuration. Its local graph, Kanban board, agent handoffs, and runtime evidence are ignored and never published by default.

About

Local-first Hyper-V VM control for humans and AI agents: Go CLI, daemon, MCP, and direct recovery paths. In development.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages