GuestKit

Page-by-page guides

Each guide follows: Purpose → When to use it → How to get there → What you can do → Related pages.

Every route is also listed in the complete page index.

Assurance

Export

Fix Plans

Fleet

Forensics

Guest Agent

Guest Files

Guides

Inspection

Integration

Interfaces

Onboarding

Profiles

Support

29 guides. Regenerate: node scripts/customer-docs/generate-guide-index.mjs.

Doctor

Purpose

Doctor — Assurance surface.

When to use it

• Operate Doctor when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: doctor
• Nav: Assurance → Doctor
• Primary interface: guestkit doctor IMAGE · TUI Assurance d · web Passport

Operate from CLI / TUI (UX)

1. guestkit doctor IMAGE · TUI Assurance d · web Passport.
2. guestkit doctor vm.qcow2 --target kvm|proxmox|kubevirt|aws….
3. --explain for root-cause.
4. -o json --fail-below 80 for CI.
5. TUI: Assurance or : doctor.
6. Fix blockers → re-run doctor.
7. Empty / fail: Low score + blockers until repaired; mount failures abort.
8. Success: Score 0–100; exit 0 if above --fail-below.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Migration Plan
• Repair
• Migration Assurance
• Getting Started
• Page index

Migration Plan

Purpose

Migration Plan — Assurance surface.

When to use it

• Operate Migration Plan when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: migrate-plan
• Nav: Assurance → Migration Plan
• Primary interface: guestkit migrate-plan IMAGE --target … · TUI e

Operate from CLI / TUI (UX)

1. guestkit migrate-plan IMAGE --target … · TUI e.
2. guestkit migrate-plan IMAGE --target proxmox.
3. --explain / -o json.
4. --export plan.yaml for FixPlan.
5. Optional --inject-agent.
6. Follow with migrate-assess / migrate-repair; TUI: t/p/e.
7. Empty / fail: Missing --target; Windows VirtIO gaps need GUESTKIT_VIRTIO_WIN.
8. Success: Migration score + checklist; YAML plan if exported.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Fix Plans
• VM Migration Guide
• Migration Assurance
• Getting Started
• Page index

Migration Assurance

Purpose

Migration Assurance — Assurance surface.

When to use it

• Operate Migration Assurance when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: migration-assurance
• Nav: Assurance → Migration Assurance
• Primary interface: doctor → plan → policy → passport → fleet

Operate from CLI / TUI (UX)

1. doctor → plan → policy → passport → fleet.
2. doctor --explain.
3. migrate-plan --export.
4. inspect --profile windows-migration if Windows.
5. policy check.
6. passport emit … -o passport.json then passport verify --fail-below 80.
7. Fleet: fleet analyze / wave-plan.
8. Empty / fail: Verify fails below threshold → repair then re-emit; BitLocker hard-block.
9. Success: Passport verify exit 0; doctor score acceptable for target.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Migration Plan
• Policy Gate
• Fleet
• VM Migration Guide
• Getting Started
• Page index

Policy Gate

Purpose

Policy Gate — Assurance surface.

When to use it

• Operate Policy Gate when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: policy
• Nav: Assurance → Policy Gate
• Primary interface: guestkit policy check IMAGE

Operate from CLI / TUI (UX)

1. guestkit policy check IMAGE.
2. policy check IMAGE --example-policy.
3. policy check IMAGE --policy FILE.yaml.
4. Or --benchmark cis.
5. -f json -o report.json.
6. Gate pipelines on non-zero / --strict; pair with passport verify.
7. Empty / fail: Missing policy file; expressions fail if evidence fields absent.
8. Success: Pass/fail per rule; JSON report written.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Migration Assurance
• Fleet
• Getting Started
• Page index

Export Formats

Purpose

Export Formats — Export surface.

When to use it

• Operate Export Formats when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: export-formats
• Nav: Export → Export Formats
• Primary interface: --output vs --export on inspect; plan export; passport JSON

Operate from CLI / TUI (UX)

1. --output vs --export on inspect; plan export; passport JSON.
2. Data: inspect -o json|yaml|csv.
3. Docs: --export html|markdown|pdf --export-output PATH.
4. Plans: plan export plan.yaml -f bash -o fix.sh.
5. Assurance: migrate-plan --export, passport emit -o.
6. TUI view export / web Passport download.
7. Empty / fail: Missing --export-output; PDF may need Chrome/wkhtmltopdf.
8. Success: File opens (HTML) or validates (JSON/YAML).

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Profiles
• Fix Plans
• Migration Assurance
• Getting Started
• Page index

Fix Plans

Purpose

Fix Plans — Fix Plans surface.

When to use it

• Operate Fix Plans when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: fix-plans
• Nav: Fix Plans → Fix Plans
• Primary interface: guestkit plan … · export from migrate-plan/repair

Operate from CLI / TUI (UX)

1. guestkit plan … · export from migrate-plan/repair.
2. plan generate IMAGE -p linux-ssh|windows-rdp|… -o plan.yaml.
3. plan preview plan.yaml (--diff).
4. plan validate plan.yaml --vm IMAGE.
5. plan apply plan.yaml --vm IMAGE --yes.
6. plan export to bash/ansible; plan rollback if needed.
7. Empty / fail: Apply refused without backup unless --skip-backup.
8. Success: Preview lists ops; apply reports success; doctor improves.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Repair
• Migration Plan
• Profiles
• Getting Started
• Page index

Repair

Purpose

Repair — Fix Plans surface.

When to use it

• Operate Repair when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: repair
• Nav: Fix Plans → Repair
• Primary interface: guestkit repair · rescue · migrate-repair

Operate from CLI / TUI (UX)

1. guestkit repair · rescue · migrate-repair.
2. repair IMAGE --fix boot --dry-run.
3. repair IMAGE --fix boot (apply + re-doctor).
4. Day-0: rescue IMAGE -o enable-ssh|fix-grub|reset-password….
5. Migration: migrate-repair IMAGE --target kvm [--apply --yes].
6. Prefer dry-run → backup → apply.
7. Empty / fail: Dry-run only = no disk change; NTFS dirty → ntfsfix first.
8. Success: Doctor score rises; rescue op applied.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Fix Plans
• Guest Agent
• Getting Started
• Page index

Fleet

Purpose

Fleet — Fleet surface.

When to use it

• Operate Fleet when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: fleet
• Nav: Fleet → Fleet
• Primary interface: guestkit fleet analyze|wave-plan|watch DIR · TUI --fleet DIR

Operate from CLI / TUI (UX)

1. guestkit fleet analyze|wave-plan|watch DIR · TUI --fleet DIR.
2. fleet analyze ./vms/ [--recursive -j 4].
3. fleet wave-plan ./vms/ -o json.
4. fleet watch ./vms/ (first run = baseline).
5. Later: watch --fail-on-drift in cron.
6. TUI: guestctl tui one.qcow2 --fleet ./vms/.
7. Empty / fail: Empty dir / no disk formats.
8. Success: Clusters/snowflakes/blockers; waves; watch reports drift or clean.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Forensic Diff
• Migration Assurance
• Getting Started
• Page index

Forensic Diff

Purpose

Forensic Diff — Forensics surface.

When to use it

• Operate Forensic Diff when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: forensic-diff
• Nav: Forensics → Forensic Diff
• Primary interface: guestkit forensic-diff OLD NEW · diff / compare

Operate from CLI / TUI (UX)

1. guestkit forensic-diff OLD NEW · diff / compare.
2. Snapshot before/after.
3. forensic-diff before.qcow2 after.qcow2.
4. -o json for drift score.
5. Lighter: guestkit diff a b.
6. Fleet continuous: fleet watch.
7. Empty / fail: Identical images → low drift; mount fail on either side.
8. Success: Drift findings / security indicators JSON.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Fleet
• Inspect
• Profiles
• Getting Started
• Page index

Guest Agent

Purpose

Guest Agent — Guest Agent surface.

When to use it

• Operate Guest Agent when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: guest-agent
• Nav: Guest Agent → Guest Agent
• Primary interface: Build --features agent; inject offline; proxy on host

Operate from CLI / TUI (UX)

1. Build --features agent; inject offline; proxy on host.
2. cargo build --release --features agent --target x86_64-unknown-linux-musl.
3. guestkit agent-inject IMAGE --agent-binary ….
4. Boot guest; guestkit agent-proxy --socket … --listen 127.0.0.1:8765.
5. curl /ping /doctor /evidence.
6. Or guestkit agent-call --socket … --method guestkit.getEvidence.
7. Empty / fail: No channel → missing virtio-serial/QGA; Windows needs virtio-serial driver.
8. Success: /ping OK; RPC returns doctor JSON.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Guest Control Fabric
• KubeVirt Integration
• Repair
• Getting Started
• Page index

Guest Files

Purpose

Guest Files — Guest Files surface.

When to use it

• Operate Guest Files when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: files
• Nav: Guest Files → Guest Files
• Primary interface: list|ls, cat, extract|get, search|find, explore

Operate from CLI / TUI (UX)

1. list|ls, cat, extract|get, search|find, explore.
2. guestkit ls disk.qcow2 /etc.
3. guestkit cat disk.qcow2 /etc/fstab.
4. guestkit extract disk.qcow2 /etc/hostname ./hostname.txt.
5. guestkit find disk.qcow2 '*.conf'.
6. Multi-step: interactive or explore; backup: guestkit backup IMAGE -o out.tar.gz.
7. Empty / fail: Path missing → wrong mount/root; permission → sudo/NBD.
8. Success: Listing/content/extracted file on host.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Interactive Mode
• TUI (guestctl)
• Filesystems
• Getting Started
• Page index

Guest Control Fabric

Purpose

Guest Control Fabric — Guest Files surface.

When to use it

• Operate Guest Control Fabric when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: guest-control-fabric
• Nav: Guest Files → Guest Control Fabric
• Primary interface: Web/API via zyvor-api KubeVirt guest routes

Operate from CLI / TUI (UX)

1. Web/API via zyvor-api KubeVirt guest routes.
2. Deploy API+UI (compose/Helm).
3. GET .../guest/status → control state.
4. GET .../guest/capabilities → transport.
5. Live: POST .../guest/doctor or agent-proxy.
6. Airgap: POST .../guest/install-agent; halted VM: POST .../guest/repair-plan.
7. Empty / fail: console_only/blind_vm → install QGA/agent or stop VM for offline path.
8. Success: Envelope with transport, controlState, ok:true.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Guest Agent
• KubeVirt Integration
• Zeus VM Tools
• Getting Started
• Page index

VM Migration Guide

Purpose

VM Migration Guide — Guides surface.

When to use it

• Operate VM Migration Guide when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: vm-migration
• Nav: Guides → VM Migration Guide
• Primary interface: CLI assurance-first workflow (+ h2kvm convert)

Operate from CLI / TUI (UX)

1. CLI assurance-first workflow (+ h2kvm convert).
2. Convert if needed: guestkit convert / qemu-img.
3. doctor --target … --explain.
4. migrate-plan --export.
5. repair --fix boot / migrate-repair --apply.
6. Windows VirtIO via GUESTKIT_VIRTIO_WIN.
7. passport emit/verify then convert/boot on target.
8. Empty / fail: Boot fail post-cutover → fstab/GRUB/VirtIO; never write while guest running.
9. Success: Doctor high enough; passport verifies; first boot on target.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Migration Assurance
• Doctor
• Migration Plan
• Repair
• Getting Started
• Page index

Filesystems

Purpose

Filesystems — Inspection surface.

When to use it

• Operate Filesystems when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: filesystems
• Nav: Inspection → Filesystems
• Primary interface: guestkit filesystems|fs IMAGE · REPL · TUI Storage

Operate from CLI / TUI (UX)

1. guestkit filesystems|fs IMAGE · REPL · TUI Storage.
2. guestkit filesystems disk.qcow2.
3. --detailed for types/labels.
4. Cross-check guestkit usage|df and check|fsck.
5. In REPL: mount root then ls /.
6. LVM clues via inspect --profile migration.
7. Empty / fail: Empty partition list → wrong image / need NBD; LUKS needs cryptsetup.
8. Success: Partition/FS list (ext4/xfs + swap).

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Guest Files
• Repair
• Getting Started
• Page index

Inspect

Purpose

Inspect — Inspection surface.

When to use it

• Operate Inspect when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: inspect
• Nav: Inspection → Inspect
• Primary interface: guestkit inspect IMAGE · TUI Overview · web Image Vault

Operate from CLI / TUI (UX)

1. guestkit inspect IMAGE · TUI Overview · web Image Vault.
2. guestkit inspect disk.qcow2.
3. Add -o json or --summary.
4. Depth: --depth quick|standard|deep.
5. Flags: --include-packages|--include-services|--include-network.
6. Profile: --profile security|migration|performance|windows-migration.
7. Batch: inspect-batch *.qcow2 -p 4.
8. Empty / fail: No OS → encrypted/corrupt/empty disk; use filesystems + interactive mount.
9. Success: OS type/distro/hostname + sections (or JSON).

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Filesystems
• Packages
• Profiles
• Export Formats
• Getting Started
• Page index

Network Inspect

Purpose

Network Inspect — Inspection surface.

When to use it

• Operate Network Inspect when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: network
• Nav: Inspection → Network Inspect
• Primary interface: guestkit network IMAGE · REPL · TUI Network

Operate from CLI / TUI (UX)

1. guestkit network IMAGE · REPL · TUI Network.
2. guestkit network disk.qcow2.
3. --show-interfaces / --show-dns / --show-routes.
4. --export-json.
5. Or inspect --include-network.
6. Live: agent-proxy /evidence or KubeVirt guest/network.
7. Empty / fail: No ifaces → cloud-init-only / netplan not parsed.
8. Success: Interfaces + IP/MAC/DHCP + DNS.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Migration Plan
• Guest Agent
• Getting Started
• Page index

Packages

Purpose

Packages — Inspection surface.

When to use it

• Operate Packages when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: packages
• Nav: Inspection → Packages
• Primary interface: guestkit packages|pkg IMAGE · REPL · TUI Packages

Operate from CLI / TUI (UX)

1. guestkit packages|pkg IMAGE · REPL · TUI Packages.
2. guestkit packages disk.qcow2.
3. --filter nginx / --limit 50.
4. --json for automation.
5. Or inspect --include-packages.
6. Offline install staging: GUESTKIT_PACKAGE_CACHE + plan apply.
7. Empty / fail: Empty = no package DB / Windows guest / mount failed.
8. Success: Manager + package rows.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Fix Plans
• Profiles
• Getting Started
• Page index

Services & Users

Purpose

Services & Users — Inspection surface.

When to use it

• Operate Services & Users when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: services-users
• Nav: Inspection → Services & Users
• Primary interface: guestkit systemd-services IMAGE; users via REPL/inspect; TUI

Operate from CLI / TUI (UX)

1. guestkit systemd-services IMAGE; users via REPL/inspect; TUI.
2. guestkit systemd-services disk.qcow2 (--failed, --service UNIT).
3. guestkit systemd-journal / systemd-boot as needed.
4. Users: interactive → users, or inspect User Accounts.
5. TUI → Services / Users tabs.
6. inspect --include-services.
7. Empty / fail: Non-systemd OS → sparse services; Windows users via registry inspect.
8. Success: Enabled units listed; users show uid/shell.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Interactive Mode
• Doctor
• Guest Agent
• Getting Started
• Page index

KubeVirt Integration

Purpose

KubeVirt Integration — Integration surface.

When to use it

• Operate KubeVirt Integration when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: kubevirt-integration
• Nav: Integration → KubeVirt Integration
• Primary interface: zyvor-api HTTP + CLI offline on PVC path

Operate from CLI / TUI (UX)

1. zyvor-api HTTP + CLI offline on PVC path.
2. Deploy API with KubeVirt RBAC.
3. Stopped VM: GET/POST /api/v1/kubevirt/vms/{ns}/{name}/boot-inspect.
4. Or CLI: doctor PVC_PATH --target kubevirt.
5. Live: guest/status, guest/doctor, guest/evidence.
6. Install agent via guest/install-agent or vmtools.
7. Empty / fail: Running VM → offline inspect skipped; missing PVC path.
8. Success: available:true, source:guestkit, boot fields populated.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Guest Control Fabric
• Guest Agent
• Zeus VM Tools
• Doctor
• Getting Started
• Page index

Zeus VM Tools

Purpose

Zeus VM Tools — Integration surface.

When to use it

• Operate Zeus VM Tools when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: zeus-vm-tools
• Nav: Integration → Zeus VM Tools
• Primary interface: Package zyvor-vm-tools / zyvor-guest-agent; API /api/v1/vmtools/*

Operate from CLI / TUI (UX)

1. Package zyvor-vm-tools / zyvor-guest-agent; API /api/v1/vmtools/*.
2. Build packages.
3. POST .../vmtools/install?method=auto|cloud-init|qga|iso.
4. Check GET /api/v1/vmtools/coverage.
5. Quiesce: .../vmtools/quiesce / unquiesce.
6. Exec: .../vmtools/exec; offline: agent-inject.
7. Empty / fail: Coverage 0 → QGA down / no network → use qga file bootstrap.
8. Success: Agent connected; coverage chip; freeze/thaw works.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Guest Agent
• KubeVirt Integration
• Guest Control Fabric
• Getting Started
• Page index

Python Bindings

Purpose

Python Bindings — Interfaces surface.

When to use it

• Operate Python Bindings when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: python-bindings
• Nav: Interfaces → Python Bindings
• Primary interface: pip install zyvorai-guestkit or maturin develop --features python-bindings

Operate from CLI / TUI (UX)

1. pip install zyvorai-guestkit or maturin develop --features python-bindings.
2. from guestkit import Guestfs.
3. add_drive_ro → launch → inspect_os.
4. Mount via inspect_get_mountpoints + mount_ro.
5. cat/ls as needed.
6. umount_all + shutdown; see examples/python/.
7. Empty / fail: Import error → wrong package/feature; launch fail → NBD/sudo.
8. Success: Distro/hostname printed; clean shutdown.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• CLI Guide
• Guest Files
• Getting Started
• Page index

TUI (guestctl)

Purpose

TUI (guestctl) — Interfaces surface.

When to use it

• Operate TUI (guestctl) when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: tui
• Nav: Interfaces → TUI (guestctl)
• Primary interface: guestctl tui IMAGE · guestkit tui|ui IMAGE

Operate from CLI / TUI (UX)

1. guestctl tui IMAGE · guestkit tui|ui IMAGE.
2. Open TUI (optional --fleet DIR, --compare OTHER).
3. {/} groups; Tab views; Ctrl+P jump; : palette.
4. Assurance: d doctor, t target, p preview, e export.
5. Browse Packages/Services/Users/Network.
6. Config ~/.config/guestkit/tui.toml; h/? help.
7. Empty / fail: Blank panes → inspect failed (permissions/format); check footer.
8. Success: Dashboard populated; doctor score on Assurance.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Doctor
• Migration Plan
• Interactive Mode
• Inspect
• Getting Started
• Page index

CLI Guide

Purpose

CLI Guide — Onboarding surface.

When to use it

• Operate CLI Guide when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: cli-guide
• Nav: Onboarding → CLI Guide
• Primary interface: guestkit --help; guestkit commands

Operate from CLI / TUI (UX)

1. guestkit --help; guestkit commands.
2. guestkit commands for catalog.
3. Inspect group: inspect, filesystems, packages, network.
4. Assurance: doctor, migrate-plan, passport, policy, fleet.
5. Plans: plan generate|preview|apply|rollback.
6. Rescue: rescue -o …; prefer -o json / --fail-below for CI.
7. Empty / fail: Unknown subcommand → guestkit commands; feature-gated cmds need --features agent|ai|mcp.
8. Success: Help lists groups; sample inspect returns text/JSON.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Quick Reference
• Interactive Mode
• Export Formats
• Getting Started
• Page index

Getting Started

Purpose

Getting Started — Onboarding surface.

When to use it

• Operate Getting Started when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: getting-started
• Nav: Onboarding → Getting Started
• Primary interface: CLI first-hour; optional web :8088

Operate from CLI / TUI (UX)

1. CLI first-hour; optional web :8088.
2. Install: cargo install guestkit or release binary.
3. Confirm deps: qemu-img --version.
4. guestkit doctor vm.qcow2 --target kvm --explain.
5. guestkit migrate-plan vm.vmdk --target kvm --export plan.yaml.
6. Optional: guestctl tui vm.qcow2 or GHCR compose → :8088.
7. Empty / fail: Missing qemu-img/NBD → install qemu-utils; permission denied → sudo or modprobe nbd.
8. Success: Doctor prints 0–100 score + blockers; guestkit version works.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Quick Reference
• CLI Guide
• Doctor
• TUI (guestctl)
• Getting Started
• Page index

Interactive Mode

Purpose

Interactive Mode — Onboarding surface.

When to use it

• Operate Interactive Mode when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: interactive-mode
• Nav: Onboarding → Interactive Mode
• Primary interface: guestkit interactive|repl|shell IMAGE

Operate from CLI / TUI (UX)

1. guestkit interactive|repl|shell IMAGE.
2. Launch REPL (one mount).
3. info → filesystems → mount /dev/… /.
4. ls / cat / find / download.
5. packages / services / users / network.
6. Optional explore; then exit.
7. Empty / fail: ls /etc empty usually means unmounted — run mount; launch fail → NBD/loop/permissions.
8. Success: Welcome shows detected OS; packages/users return lists.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Guest Files
• TUI (guestctl)
• Inspect
• Packages
• Getting Started
• Page index

Quick Reference

Purpose

Quick Reference — Onboarding surface.

When to use it

• Operate Quick Reference when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: quick-reference
• Nav: Onboarding → Quick Reference
• Primary interface: Cheat sheet — CLI / TUI keys

Operate from CLI / TUI (UX)

1. Cheat sheet — CLI / TUI keys.
2. guestkit inspect disk.qcow2.
3. guestkit doctor IMAGE --target kvm.
4. guestkit migrate-plan IMAGE --target proxmox --export plan.yaml.
5. guestkit rescue IMAGE -o enable-ssh / fix-grub.
6. guestctl tui IMAGE → d/t/p/e.
7. Empty / fail: No OS found → check filesystems; wrong format → detect/info.
8. Success: Inspect shows OS/hostname; doctor score present.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• CLI Guide
• Inspect
• Doctor
• TUI (guestctl)
• Getting Started
• Page index

Profiles

Purpose

Profiles — Profiles surface.

When to use it

• Operate Profiles when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: profiles
• Nav: Profiles → Profiles
• Primary interface: guestkit inspect IMAGE --profile NAME · plan generate -p …

Operate from CLI / TUI (UX)

1. guestkit inspect IMAGE --profile NAME · plan generate -p ….
2. Inspect profiles: security, migration, performance, compliance, hardening, windows-migration.
3. -o json / --export html|markdown.
4. Day-0: plan generate with windows-rdp / linux-ssh.
5. Automate over fleet with shell loop.
6. --cache-refresh when needed.
7. Empty / fail: Unknown profile name.
8. Success: Profile sections + risk_level / inventory.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Inspect
• Fix Plans
• Export Formats
• Getting Started
• Page index

FAQ

Purpose

FAQ — Support surface.

When to use it

• Operate FAQ when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: faq
• Nav: Support → FAQ
• Primary interface: Reference answers; commands embedded

Operate from CLI / TUI (UX)

1. Reference answers; commands embedded.
2. Install: cargo install guestkit.
3. Not legacy appliance tooling — use GuestKit stack.
4. Passport vs virt-v2v: certify then convert.
5. Extract/list/rescue examples as in FAQ.
6. Cache under ~/.cache/guestkit/; escalate with version + repro.
7. Empty / fail: N/A (doc); point to troubleshooting for runtime.
8. Success: Reader can run cited command successfully.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• Troubleshooting
• Getting Started
• VM Migration Guide
• Getting Started
• Page index

Troubleshooting

Purpose

Troubleshooting — Support surface.

When to use it

• Operate Troubleshooting when your job matches this surface
• Prefer dry-run / doctor before mutating repairs on disks
• Shut down the guest before write operations

How to get there

• Doc id: troubleshooting
• Nav: Support → Troubleshooting
• Primary interface: Ops runbook — CLI diagnostics

Operate from CLI / TUI (UX)

1. Ops runbook — CLI diagnostics.
2. guestkit -v inspect … / RUST_LOG=debug.
3. NBD: modprobe nbd; qemu-nbd --disconnect.
4. Loop: losetup -D.
5. qemu-img check IMAGE.
6. Container: privileged + /dev/nbd*; gather version + uname + lsmod.
7. Empty / fail: Persistent device busy → disconnect all nbd / reboot.
8. Success: Same failing command succeeds after fix.

Host needs Linux + qemu-img / losetup / qemu-nbd; mount/repair often need root. GuestKit does not invent disk contents.

Related pages

• FAQ
• Getting Started
• Filesystems
• Getting Started
• Page index

GuestKit — Complete page index

Every primary navigable dashboard route.

Generated: 2026-08-29 · 29 routes

Regenerate: node scripts/customer-docs/generate-page-index.mjs

Onboarding

Inspection

Guest Files

Guest Agent

Assurance

Fix Plans

Fleet

Forensics

Profiles

Export

Integration

Interfaces

Guides

Support

Related

• Customer docs home
• Page-by-page guides