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.
- 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.
| 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. |
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.
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.
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.
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.exeis available by default on Windows systems. The current user token must belong to localAdministratorsorHyper-V Administrators. - WSL interop: When running inside WSL, WSL interop discovers
powershell.exein 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 localAdministratorsorHyper-V Administrators.
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. |
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.
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.
Go 1.26 or newer is required.
go test ./...
go build ./cmd/...
go run ./cmd/amc --versionThe public API and command surface are not stable before v0.1.0.
- Architecture decision
- Language and toolchain decision
- Public versus local data boundary
- Threat model
- Development guide
- Quality system
- Testing strategy
- Automatic local amcd bootstrap
- Autonomous and parallel agent workflow
- Recommended repository settings
- Open-source baseline research
- Roadmap
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.