hardpass-vm 0.1.1

A small, reliable Ubuntu cloud-image VM manager built on QEMU.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Hardpass

`hardpass` is a small Rust CLI for managing local Ubuntu cloud-image VMs with QEMU.

It exists for people who want a simpler, more predictable local VM workflow than Multipass:
- macOS and Linux hosts
- Ubuntu guest images only
- host-native guest architecture only
- QEMU user networking
- stable per-VM SSH port forwarding

## Commands

- `doctor` checks for required local tools and firmware.
- `create` creates a named VM.
- `start` boots a named VM and waits for SSH.
- `stop` gracefully stops a named VM.
- `delete` stops and removes a named VM.
- `list` shows known VMs.
- `info [--json]` prints VM details.
- `ssh-config install` adds the managed Hardpass include to `~/.ssh/config`.
- `ssh-config sync` rewrites the managed Hardpass host aliases.
- `ssh` opens an interactive SSH session.
- `exec` runs a remote command over SSH.

## Install

From crates.io:

```bash
cargo install hardpass-vm
```

That installs the `hardpass` executable.

From the GitHub repository:

```bash
cargo install --git https://github.com/peterdelevoryas/hardpass --bin hardpass
```

From a local checkout:

```bash
cargo install --path .
```

That installs the `hardpass` executable into Cargo's bin directory so the examples below can be run directly.

## Quick Start

```bash
hardpass doctor
hardpass create dev
hardpass start dev
hardpass list
hardpass info dev
hardpass ssh dev
hardpass exec dev -- uname -a
hardpass ssh-config install
hardpass ssh-config sync
hardpass stop dev
hardpass delete dev
```

`create` defaults to Ubuntu `24.04` on the host-native guest architecture. You can override VM size and forwarding when needed:

```bash
hardpass create test \
  --release 24.04 \
  --cpus 4 \
  --memory-mib 4096 \
  --disk-gib 24 \
  --forward 8080:8080

hardpass start test
```

Use `info --json` when another tool needs machine-readable state:

```bash
hardpass info dev --json
```

The JSON payload includes `ssh.alias`, so other tools can discover the SSH alias directly.

## State and SSH

Hardpass stores state under `~/.hardpass` by default. Set `HARDPASS_HOME` if you want a different root.

Install the one-time include block, then sync the current VM aliases:

```bash
hardpass ssh-config install
hardpass ssh-config sync
```

Each VM name becomes an SSH alias with the stored loopback port and identity file:

```bash
ssh dev
```

If the managed include is installed, `hardpass create` and `hardpass delete` keep the alias file up to date automatically for the default `~/.hardpass` root.

## Host Requirements

- `qemu-img`
- `qemu-system-x86_64` or `qemu-system-aarch64`
- `ssh`
- `ssh-keygen`
- AArch64 hosts also need discoverable UEFI firmware for QEMU

Run `hardpass doctor` to confirm the local environment before creating a VM.

## Security Notes

- SSH connections disable host key checking and known-host persistence for loopback convenience.
- The default cloud-init config creates an `ubuntu` user with passwordless sudo.
- Guest networking uses QEMU user networking, not bridged networking.

## Testing

```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```

The real-QEMU integration smoke test is opt-in:

```bash
HARDPASS_REAL_QEMU_TEST=1 cargo test --test library_api_smoke -- --ignored
```