Skip to content

Commit ddb85b1

Browse files
drewdrew
authored
feat(vm): add openshell-vm crate with libkrun microVM gateway (#611)
1 parent c2e5256 commit ddb85b1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+10972
-61
lines changed

‎.github/workflows/release-vm-dev.yml‎

Lines changed: 518 additions & 0 deletions
Large diffs are not rendered by default.

‎.github/workflows/release-vm-kernel.yml‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
name: Release VM Kernel
2+
3+
# Build custom libkrunfw (kernel firmware) + libkrun (VMM) + gvproxy for all
4+
# supported openshell-vm platforms. Artifacts are uploaded to the rolling
5+
# "vm-dev" GitHub Release and consumed by release-vm-dev.yml when building the
6+
# openshell-vm binary.
7+
#
8+
# This workflow runs on-demand (or when kernel config / pins change). It is
9+
# intentionally decoupled from the per-commit VM binary build because the
10+
# kernel rarely changes and takes 15-45 minutes to compile.
11+
12+
on:
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: write
17+
18+
# Serialize with release-vm-dev.yml — both update the vm-dev release.
19+
concurrency:
20+
group: vm-dev-release
21+
cancel-in-progress: false
22+
23+
defaults:
24+
run:
25+
shell: bash
26+
27+
jobs:
28+
# ---------------------------------------------------------------------------
29+
# Linux ARM64 — native kernel + libkrun build
30+
# ---------------------------------------------------------------------------
31+
build-runtime-linux-arm64:
32+
name: Build Runtime (Linux ARM64)
33+
runs-on: build-arm64
34+
timeout-minutes: 60
35+
container:
36+
image: ghcr.io/nvidia/openshell/ci:latest
37+
credentials:
38+
username: ${{ github.actor }}
39+
password: ${{ secrets.GITHUB_TOKEN }}
40+
options: --privileged
41+
env:
42+
MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
43+
steps:
44+
- uses: actions/checkout@v4
45+
46+
- name: Mark workspace safe for git
47+
run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
48+
49+
- name: Build libkrunfw + libkrun from source
50+
run: tasks/scripts/vm/build-libkrun.sh
51+
52+
- name: Package runtime tarball
53+
run: |
54+
tasks/scripts/vm/package-vm-runtime.sh \
55+
--platform linux-aarch64 \
56+
--build-dir target/libkrun-build \
57+
--output artifacts/vm-runtime-linux-aarch64.tar.zst
58+
59+
- name: Upload artifact
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: vm-runtime-linux-arm64
63+
path: artifacts/vm-runtime-linux-aarch64.tar.zst
64+
retention-days: 5
65+
66+
# ---------------------------------------------------------------------------
67+
# Linux AMD64 — native kernel + libkrun build
68+
# ---------------------------------------------------------------------------
69+
build-runtime-linux-amd64:
70+
name: Build Runtime (Linux AMD64)
71+
runs-on: build-amd64
72+
timeout-minutes: 60
73+
container:
74+
image: ghcr.io/nvidia/openshell/ci:latest
75+
credentials:
76+
username: ${{ github.actor }}
77+
password: ${{ secrets.GITHUB_TOKEN }}
78+
options: --privileged
79+
env:
80+
MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
81+
steps:
82+
- uses: actions/checkout@v4
83+
84+
- name: Mark workspace safe for git
85+
run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
86+
87+
- name: Build libkrunfw + libkrun from source
88+
run: tasks/scripts/vm/build-libkrun.sh
89+
90+
- name: Package runtime tarball
91+
run: |
92+
tasks/scripts/vm/package-vm-runtime.sh \
93+
--platform linux-x86_64 \
94+
--build-dir target/libkrun-build \
95+
--output artifacts/vm-runtime-linux-x86_64.tar.zst
96+
97+
- name: Upload artifact
98+
uses: actions/upload-artifact@v4
99+
with:
100+
name: vm-runtime-linux-amd64
101+
path: artifacts/vm-runtime-linux-x86_64.tar.zst
102+
retention-days: 5
103+
104+
# ---------------------------------------------------------------------------
105+
# macOS ARM64 — kernel built via krunvm, libkrun built natively
106+
# ---------------------------------------------------------------------------
107+
build-runtime-macos-arm64:
108+
name: Build Runtime (macOS ARM64)
109+
runs-on: macos-latest-xlarge
110+
timeout-minutes: 90
111+
steps:
112+
- uses: actions/checkout@v4
113+
114+
- name: Install dependencies
115+
run: |
116+
set -euo pipefail
117+
brew install rust lld dtc xz
118+
# libkrunfw from Homebrew (used as a fallback/reference by build scripts)
119+
brew install libkrunfw
120+
# krunvm is needed to build the Linux kernel inside a Fedora VM
121+
brew tap slp/krun
122+
brew install krunvm
123+
124+
- name: Build custom libkrunfw (kernel)
125+
run: crates/openshell-vm/runtime/build-custom-libkrunfw.sh
126+
127+
- name: Build portable libkrun
128+
run: tasks/scripts/vm/build-libkrun-macos.sh
129+
130+
- name: Package runtime tarball
131+
env:
132+
CUSTOM_PROVENANCE_DIR: target/custom-runtime
133+
run: |
134+
tasks/scripts/vm/package-vm-runtime.sh \
135+
--platform darwin-aarch64 \
136+
--build-dir target/libkrun-build \
137+
--output artifacts/vm-runtime-darwin-aarch64.tar.zst
138+
139+
- name: Upload artifact
140+
uses: actions/upload-artifact@v4
141+
with:
142+
name: vm-runtime-macos-arm64
143+
path: artifacts/vm-runtime-darwin-aarch64.tar.zst
144+
retention-days: 5
145+
146+
# ---------------------------------------------------------------------------
147+
# Upload all runtime tarballs to the vm-dev rolling release
148+
# ---------------------------------------------------------------------------
149+
release-kernel:
150+
name: Release Kernel Runtime
151+
needs: [build-runtime-linux-arm64, build-runtime-linux-amd64, build-runtime-macos-arm64]
152+
runs-on: build-amd64
153+
timeout-minutes: 10
154+
steps:
155+
- uses: actions/checkout@v4
156+
157+
- name: Download all runtime artifacts
158+
uses: actions/download-artifact@v4
159+
with:
160+
pattern: vm-runtime-*
161+
path: release/
162+
merge-multiple: true
163+
164+
- name: Generate checksums
165+
run: |
166+
set -euo pipefail
167+
cd release
168+
sha256sum vm-runtime-*.tar.zst > vm-runtime-checksums-sha256.txt
169+
cat vm-runtime-checksums-sha256.txt
170+
171+
- name: Ensure vm-dev tag exists
172+
run: |
173+
git config user.name "github-actions[bot]"
174+
git config user.email "github-actions[bot]@users.noreply.github.com"
175+
git tag -fa vm-dev -m "VM Development Build" "${GITHUB_SHA}"
176+
git push --force origin vm-dev
177+
178+
- name: Prune stale runtime assets from vm-dev release
179+
uses: actions/github-script@v7
180+
with:
181+
script: |
182+
const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
183+
let release;
184+
try {
185+
release = await github.rest.repos.getReleaseByTag({ owner, repo, tag: 'vm-dev' });
186+
} catch (err) {
187+
if (err.status === 404) {
188+
core.info('No existing vm-dev release; will create fresh.');
189+
return;
190+
}
191+
throw err;
192+
}
193+
// Delete old runtime tarballs and checksums (keep vm binary assets)
194+
for (const asset of release.data.assets) {
195+
if (asset.name.startsWith('vm-runtime-')) {
196+
core.info(`Deleting stale asset: ${asset.name}`);
197+
await github.rest.repos.deleteReleaseAsset({ owner, repo, asset_id: asset.id });
198+
}
199+
}
200+
201+
- name: Create / update vm-dev GitHub Release
202+
uses: softprops/action-gh-release@v2
203+
with:
204+
name: OpenShell VM Development Build
205+
prerelease: true
206+
tag_name: vm-dev
207+
target_commitish: ${{ github.sha }}
208+
body: |
209+
Rolling development build of **openshell-vm** — the MicroVM runtime for OpenShell.
210+
211+
> **NOTE**: This is a development build, not a tagged release, and may be unstable.
212+
> The VM implementation itself is also experimental and may change or break without
213+
> notice.
214+
215+
### Kernel Runtime Artifacts
216+
217+
Pre-built kernel runtime (libkrunfw + libkrun + gvproxy) for embedding into
218+
the openshell-vm binary. These are rebuilt when the kernel config or pinned
219+
dependency versions change.
220+
221+
| Platform | Artifact |
222+
|----------|----------|
223+
| Linux ARM64 | `vm-runtime-linux-aarch64.tar.zst` |
224+
| Linux x86_64 | `vm-runtime-linux-x86_64.tar.zst` |
225+
| macOS ARM64 | `vm-runtime-darwin-aarch64.tar.zst` |
226+
227+
### VM Binaries
228+
229+
Self-extracting openshell-vm binaries with embedded kernel runtime and base
230+
rootfs. These are rebuilt on every push to main.
231+
232+
| Platform | Artifact |
233+
|----------|----------|
234+
| Linux ARM64 | `openshell-vm-aarch64-unknown-linux-gnu.tar.gz` |
235+
| Linux x86_64 | `openshell-vm-x86_64-unknown-linux-gnu.tar.gz` |
236+
| macOS ARM64 | `openshell-vm-aarch64-apple-darwin.tar.gz` |
237+
238+
**macOS users:** The binary must be codesigned with the Hypervisor entitlement:
239+
```bash
240+
codesign --entitlements crates/openshell-vm/entitlements.plist --force -s - ./openshell-vm
241+
```
242+
243+
files: |
244+
release/vm-runtime-linux-aarch64.tar.zst
245+
release/vm-runtime-linux-x86_64.tar.zst
246+
release/vm-runtime-darwin-aarch64.tar.zst
247+
release/vm-runtime-checksums-sha256.txt

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,9 @@ kubeconfig
181181
# Documentation build output
182182
_build/
183183

184+
# Gateway microVM rootfs build artifacts
185+
rootfs/
186+
184187
# Docker build artifacts (image tarballs, packaged helm charts)
185188
deploy/docker/.build/
186189

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
3939
| `crates/openshell-core/` | Shared core | Common types, configuration, error handling |
4040
| `crates/openshell-providers/` | Provider management | Credential provider backends |
4141
| `crates/openshell-tui/` | Terminal UI | Ratatui-based dashboard for monitoring |
42+
| `crates/openshell-vm/` | MicroVM runtime | Experimental, work-in-progress libkrun-based VM execution |
4243
| `python/openshell/` | Python SDK | Python bindings and CLI packaging |
4344
| `proto/` | Protobuf definitions | gRPC service contracts |
4445
| `deploy/` | Docker, Helm, K8s | Dockerfiles, Helm chart, manifests |

0 commit comments

Comments
 (0)