Skip to content

Commit e63babd

Browse files
ihexonihexon
committed
docs: update README
Signed-off-by: ihexon <14349453+ihexon@users.noreply.github.com>
1 parent 9882cd3 commit e63babd

4 files changed

Lines changed: 141 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
<p align="center">
2+
<img src="./icon.png" alt="revm logo" width="520" />
3+
</p>
14
<h1 align="center"><b>revm</b></h1>
25
<p align="center">revm helps you quickly launch Linux VMs / Containers</p>
36

@@ -26,6 +29,54 @@ xattr -d com.apple.quarantine revm-Darwin-arm64.tar.zst
2629
tar -xvf revm-Darwin-arm64.tar.zst
2730
```
2831

32+
## Command Overview
33+
34+
`cmd/revm` exposes three user-facing subcommands:
35+
36+
| Command | Alias | What it does |
37+
|---------|-------|--------------|
38+
| `revm chroot` | `run` | Boot a Linux microVM from a custom or built-in rootfs, then run a command inside it |
39+
| `revm dockerd` | `start` | Boot the built-in container VM and expose a Podman-compatible API socket on the host |
40+
| `revm attach` | — | Reconnect to an existing session over SSH, either as an interactive shell (`--pty`) or a one-off command |
41+
42+
Inside the guest, `cmd/guest-agent` finishes the boot sequence: it mounts pseudo filesystems and shared disks,
43+
configures networking (`gvisor` or `tsi`), starts SSH and optional Podman services, runs the requested command in
44+
`chroot` mode, and reports readiness back to the host.
45+
46+
## Quick Start
47+
48+
```bash
49+
# Run a command inside a rootfs-backed VM
50+
revm chroot --id build --rootfs ~/ubuntu-rootfs -- bash -lc 'uname -a'
51+
52+
# Re-enter the same VM from another terminal
53+
revm attach --pty build
54+
55+
# Start the built-in container engine
56+
revm dockerd --id engine
57+
export CONTAINER_HOST=unix:///tmp/engine/socks/podman-api.sock
58+
podman run --rm alpine uname -a
59+
```
60+
61+
## Key Flags
62+
63+
These flags come from `cmd/revm/flags.go` and are shared by `chroot` / `dockerd` unless noted otherwise.
64+
65+
| Flag | Applies to | Description |
66+
|------|------------|-------------|
67+
| `--id` | both | Session name; workspace defaults to `/tmp/<id>` and the same ID cannot be started twice at once |
68+
| `--cpus`, `--memory` | both | VM CPU and memory sizing |
69+
| `--mount` | both | Share a host directory into the guest through VirtIO-FS |
70+
| `--raw-disk` | both | Attach an ext4 raw disk image; missing images are auto-created |
71+
| `--network` | both | Choose `gvisor` (virtual NIC, NAT, DNS, port forwarding support) or `tsi` (transparent socket interception) |
72+
| `--system-proxy` | both | Read the macOS system proxy and forward it into the guest |
73+
| `--manage-api` | both | Custom Unix socket path for the host-side VM management API |
74+
| `--ssh-key` | both | Symlink the generated SSH private key to a user-chosen path |
75+
| `--report-events` | both | Send lifecycle events to an HTTP endpoint |
76+
| `--log-level`, `--log-to` | both | Control host-side logging verbosity and destination |
77+
| `--rootfs`, `--workdir`, `--envs` | `chroot` | Select the guest rootfs and the execution context for the launched command |
78+
| `--container-disk`, `--podman-api` | `dockerd` | Control persistent container storage and the exported Podman-compatible socket path |
79+
2980
---
3081

3182
## Documentation

‎README_zh.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
<p align="center">
2+
<img src="./icon.png" alt="revm logo" width="520" />
3+
</p>
14
<h1 align="center"><b>revm</b></h1>
25
<p align="center">快速启动 Linux 虚拟机 / 容器的轻量工具</p>
36

@@ -25,6 +28,53 @@ xattr -d com.apple.quarantine revm-Darwin-arm64.tar.zst
2528
tar -xvf revm-Darwin-arm64.tar.zst
2629
```
2730

31+
## 命令概览
32+
33+
`cmd/revm` 对外暴露三个用户命令：
34+
35+
| 命令 | 别名 | 作用 |
36+
|------|------|------|
37+
| `revm chroot` | `run` | 用自定义或内置 rootfs 启动 Linux microVM，并在其中执行命令 |
38+
| `revm dockerd` | `start` | 启动内置容器虚拟机，并在宿主机暴露兼容 Podman 的 API socket |
39+
| `revm attach` | — | 通过 SSH 重新连接已有会话，可进入交互 shell（`--pty`）或执行一次性命令 |
40+
41+
虚拟机内部实际运行的是 `cmd/guest-agent`：它负责挂载伪文件系统和共享磁盘、配置网络（`gvisor` 或
42+
`tsi`）、启动 SSH 和可选的 Podman 服务、在 `chroot` 模式中执行用户命令，并把就绪状态回报给宿主机。
43+
44+
## 快速开始
45+
46+
```bash
47+
# 在 rootfs 虚拟机里执行命令
48+
revm chroot --id build --rootfs ~/ubuntu-rootfs -- bash -lc 'uname -a'
49+
50+
# 在另一终端重新进入同一个会话
51+
revm attach --pty build
52+
53+
# 启动内置容器引擎
54+
revm dockerd --id engine
55+
export CONTAINER_HOST=unix:///tmp/engine/socks/podman-api.sock
56+
podman run --rm alpine uname -a
57+
```
58+
59+
## 关键参数
60+
61+
这些参数定义在 `cmd/revm/flags.go` 中，除特别说明外由 `chroot` / `dockerd` 共用。
62+
63+
| 参数 | 适用命令 | 说明 |
64+
|------|----------|------|
65+
| `--id` | 两者 | 会话名；工作目录默认是 `/tmp/<id>`，同一个 ID 不能并发启动两次 |
66+
| `--cpus`, `--memory` | 两者 | 虚拟机 CPU 和内存配置 |
67+
| `--mount` | 两者 | 通过 VirtIO-FS 将宿主目录共享到虚拟机 |
68+
| `--raw-disk` | 两者 | 挂载 ext4 原始磁盘镜像；文件不存在时会自动创建 |
69+
| `--network` | 两者 | 选择 `gvisor`（虚拟网卡、NAT、DNS、支持端口映射）或 `tsi`（透明套接字拦截） |
70+
| `--system-proxy` | 两者 | 读取 macOS 系统代理并传入虚拟机 |
71+
| `--manage-api` | 两者 | 自定义宿主机侧 VM 管理 API 的 Unix socket 路径 |
72+
| `--ssh-key` | 两者 | 将生成的 SSH 私钥软链接到指定路径 |
73+
| `--report-events` | 两者 | 将生命周期事件上报到 HTTP 端点 |
74+
| `--log-level`, `--log-to` | 两者 | 控制宿主机侧日志级别和输出位置 |
75+
| `--rootfs`, `--workdir`, `--envs` | `chroot` | 指定 rootfs，以及命令执行目录和环境变量 |
76+
| `--container-disk`, `--podman-api` | `dockerd` | 控制容器持久化磁盘与导出的 Podman 兼容 socket 路径 |
77+
2878
---
2979

3080
## 文档

‎cmd/guest-agent/README.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,42 @@
11
# Guest Agent
22

3-
The guest agent runs inside the Linux VM as a child of PID 1. It bootstraps the guest environment — mounting filesystems, configuring networking, starting services (SSH, Podman API), and executing user commands.
3+
`cmd/guest-agent` runs inside every `revm` VM as the in-guest bootstrap companion. It is not the normal user entry
4+
point; the host-side `cmd/revm` process creates the VM, injects configuration, and this agent finishes guest
5+
initialization.
6+
7+
## Responsibilities
8+
9+
- Extract embedded BusyBox and Dropbear binaries into `/.bin`.
10+
- Fetch the VM configuration from the host over vsock and persist it inside the guest.
11+
- Mount pseudo filesystems, raw block devices, and VirtIO-FS shares.
12+
- Configure guest networking for `gvisor` or `tsi`.
13+
- Start long-lived services such as SSH, Podman API, and NTP sync.
14+
- Run the user command in `chroot` mode, or keep the container engine alive in `dockerd` mode.
15+
- Probe readiness and report SSH / Podman / network status back to the host.
16+
- Sync disks and power off the VM on shutdown signals.
17+
18+
## Boot Flow
19+
20+
1. Initialize logging and extract embedded helper binaries.
21+
2. Read the machine config from the host via vsock.
22+
3. Mount `/proc`, `/sys`, `/dev`, `/tmp`, `/run`, block devices, and VirtIO-FS mounts.
23+
4. Start mode-specific services:
24+
- `chroot`: configure network, start SSH and time sync, then execute the requested command.
25+
- `dockerd`: configure network, start Podman API, SSH, and time sync.
26+
5. Run readiness probes and send ready events back to the host.
27+
6. Wait for shutdown, sync disks, and force power off the VM.
28+
29+
## File Map
30+
31+
| Path | Purpose |
32+
|------|---------|
33+
| `main.go` | Main orchestration for guest boot, mode dispatch, and lifecycle |
34+
| `pkg/service/embedded.go` | Extract embedded BusyBox / Dropbear binaries |
35+
| `pkg/service/mount.go` | Mount pseudo filesystems, block devices, and VirtIO-FS shares |
36+
| `pkg/service/network.go` | Guest network setup for `gvisor` and `tsi` |
37+
| `pkg/service/dropbear.go` | Dropbear SSH server bootstrap |
38+
| `pkg/service/podman.go` | Podman system service bootstrap |
39+
| `pkg/service/runcmdline.go` | Execute the user command, including TTY-aware console handling |
40+
| `pkg/service/readiness.go` | SSH / Podman / interface readiness probes |
41+
| `pkg/service/shutdown.go` | Shutdown coordination: sync then `poweroff -f` |
42+
| `pkg/supervisor/supervisor.go` | Minimal restart-capable process supervisor used by guest services |

‎icon.png‎

67.7 KB
Loading

0 commit comments

Comments
 (0)