netbsdfr/smolbsd/skill
Claude Code and agent skill by netbsdfr/smolbsd
- community
Checking that the SKILL.md file is still in the repository.
Complete smolBSD platform expertise — the entire framework for building minimal NetBSD microVMs. Covers full lifecycle: SMOLerfile (Dockerfile-compatible) authoring, manual service directory creation, the dual build system (smoler.sh high-level vs bmake low-level), mkimg.sh image creation internals, startnb.sh QEMU/Firecracker PVH boot (~10ms), OCI registry push/pull (oras), networking & port publishing, bidirectional VirtIO sockets, BIOS/baremetal boot with confkerndev kernel slimming, GitHub Actions CI/CD pipeline, and every option, script, and convention. Includes a debugging playbook for known sharp edges (WAPBL vs. minimize/sailor, fstab corruption, PAM/utmpx failures in stripped images) and POSIX shell portability conventions. Supports amd64, i386, evbarm-aarch64.
Install
npx vskill@latest install netbsdfr/smolbsd/skillSKILL.md
smolBSD — Complete Platform Reference
This skill provides exhaustive knowledge of the entire smolBSD framework — enough for an agent to understand, navigate, extend, and debug every aspect of the project.
Read §20 (Debugging Playbook) before touching anything related to image minimization, sailor, or login/PAM in a stripped image — these are the areas that have produced the most subtle real-world failures and are easy to misdiagnose from source alone.
1. Project Overview
smolBSD builds minimal, fast-booting NetBSD virtual machines (microVMs). Key properties:
- ~10 ms boot via PVH (PVHv2) on QEMU
microvmmachine type - No prior NetBSD installation required on the host
- Immutable by design — images are built once, booted many times
- Host platforms: GNU/Linux, NetBSD, macOS (x86 VT-capable or ARM64 CPU recommended)
- Guest architectures:
amd64,i386,evbarm-aarch64 - VMMs: QEMU (primary), Firecracker, Bhyve (BIOS mode)
- Images are raw
.imgdisk files with FFS (NetBSD) or ext2 (Linux build hosts)
The fundamental unit is a service — a directory containing:
- NetBSD set selection (
base,etc,comp,man,rescue, …) - Build-time scripts (
postinst/*.sh) - Runtime init script (
etc/rc) - Build configuration (
options.mk)
2. Project Directory Layout
3. Two Workflows
3.1 smoler.sh (Docker-style, high-level)
smoler.sh is a thin dispatcher that routes subcommands to dedicated scripts:
| Command | Routes To | Purpose | |
|---|---|---|---|
./smoler.sh build [-y] [-t tag] [--build-arg K=V] [VAR=val] <SMOLerfile> | smoler/build.sh | Parse SMOLerfile → generate service dir → call bmake build | |
./smoler.sh run <image> [startnb.sh flags] | startnb.sh | Run a built image (resolves name → config file or raw path). Any startnb.sh flag passes through after the image name (e.g. -l drive2,drive3 for extra drives, -r, -e). This is the way to test a freshly built image — it loads the generated etc/<name>.conf (use_pty, hostfwd, imgtag), so it reproduces the real launch; calling startnb.sh directly bypasses that config. | |
./smoler.sh push <image> | smoler/img.sh | Push to OCI registry via oras | |
./smoler.sh pull <image> | smoler/img.sh | Pull from OCI registry via oras | |
./smoler.sh images [ok] | smoler/img.sh | List local images with size, date, signature status. Columns are sized as fixed proportions of terminal width (name = 50%, size/date/sig = 25% each); not auto-fit to content. Pass ok to show only images with verified smolsig. |
`smoler.sh run` name resolution:
- Strips
-amd64:…or-evbarm-aarch64:…suffix to get base service name
(note: an -i386:… suffix is not stripped — the etc/<base>.conf lookup for i386 images is a known quirk; the images/<image>.img fallback still works with the full name)
- Checks for
etc/<base>.conf→ passes-f etc/<base>.conftostartnb.sh - Falls back to checking
images/<image>.img→ passes-i <image>tostartnb.sh - If neither exists, shows
startnb.sh -husage
`smoler.sh build` regeneration: if service/<name>/ already exists, build.sh deletes its etc/rc, options.mk, postinst/ and etc/<name>.conf before regenerating them. Untracked files in the service dir (e.g. sailor.conf, own.mk) survive, but anything hand-edited in the deleted files is lost — commit what matters first.
3.2 bmake / make (Manual, low-level)
| Command | Purpose | |
|---|---|---|
bmake buildimg | Build the builder image (native on NetBSD/FreeBSD/Linux; on macOS this fails — the build target falls back to fetchimg there) | |
bmake fetchimg | Download pre-built builder image from GitHub Releases (macOS, no FFS support) | |
bmake SERVICE=<name> build | Build a service image using the builder microVM | |
bmake SERVICE=<name> base | Build only the base filesystem (no builder VM — runs mkimg.sh directly) | |
bmake SERVICE=<name> MOUNTRO=y build | Build with read-only root | |
bmake SERVICE=<name> ARCH=evbarm-aarch64 build | Build for ARM64 | |
bmake kernfetch | Download the appropriate kernel | |
bmake setfetch | Download NetBSD sets | |
bmake pkgfetch | Download binary packages | |
bmake fetchall | All of the above | |
bmake rescue | Shortcut: SERVICE=rescue build | |
bmake live | Fetch a full NetBSD live image |
Platform-specific builder image behavior (Makefile `build` target):
- On NetBSD/FreeBSD/Linux: builds the builder image natively (
bmake buildimg) - On macOS (and any other OS): fetches the pre-built builder image from GitHub (
bmake fetchimg); runningbuildimgdirectly on macOS fails because mkimg.sh rejects macOS - Builder image freshness is checked via SHA256; rebuilds/fetches only when the remote changes
4. SMOLerfile / Dockerfile Reference
SMOLerfiles are nearly 100% Dockerfile-compatible. smoler/build.sh parses them line-by-line and generates:
service/<name>/options.mk— build variablesservice/<name>/etc/rc— runtime init scriptservice/<name>/postinst/postinst-N.sh— build-time execution scriptsetc/<name>.conf— VM config forstartnb.sh
4.1 Parsing Flow (build.sh internals)
- INCLUDE expansion:
INCLUDE <file>directives are resolved first by catting the referenced file inline, producing a flat temporary SMOLerfile - LABEL extraction: All
LABELlines (with or withoutsmolbsd.prefix) are extracted viased/awk, uppercased, and written tooptions.mk - Service name: From
LABEL smolbsd.service=NAME, or from.smolfilename (SMOLerfile.foo→SERVICE=foo) - Postinst-0.sh: Generated with chroot setup (pkgin bootstrap, resolv.conf, openssl certs)
- Line-by-line parsing: Each directive generates shell commands appended to postinst scripts or
etc/rc - Finalization:
etc/rcgets. /etc/include/shutdownappended;etc/<name>.confgetsimgtaganduse_pty - Build: Calls
make(NetBSD) orbmake(elsewhere) withSERVICE=<name> IMGTAG=:<tag> build
4.2 All Supported Directives
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskill/SKILL.md
Popularity
- Repository stars
- 706
- Repository forks
- 53
- 7-day trend score
- 33
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/netbsdfr/smolbsd/skill)