netbsdfr/smolbsd/skill

Claude Code and agent skill by netbsdfr/smolbsd

Trust tier 2
  • community
Source check pending

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/skill

SKILL.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 microvm machine 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 .img disk 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

smolBSD/
├── Makefile # Entry point for manual image building (bmake)
├── mkimg.sh # Image creation script (called by Makefile, or directly via `bmake SERVICE=<name> base`)
├── startnb.sh # Low-level QEMU VM launcher
├── smoler.sh # High-level CLI dispatcher: build|run|push|pull|images
├── batch.sh # Batch launcher: N copies of a service on shifted ports
├── smoler/
│ ├── build.sh # SMOLerfile parser → generates service dir + calls bmake
│ └── img.sh # OCI push/pull/list (oras wrapper)
├── scripts/
│ ├── app-run.sh # Launcher helper for the app/ GUI
│ ├── fetch.sh # Smart curl wrapper (globbing, fresh checks)
│ ├── freshchk.sh # Freshness check (remote Last-Modified cache in db/)
│ ├── sh # Static shell used as /rescue/sh in rescue images
│ └── uname.sh # Architecture/machine detection helper
├── sailor/ # Cloned sailor repo (minimization), invoked by mkimg.sh
├── service/ # All service definitions
│ ├── common/ # Shared runtime scripts bundled into /etc/include/ in VM
│ │ ├── basicrc # Standard env, networking, devices, SSL_CERT_FILE, rc.pre/rc.local
│ │ ├── choupi # Emoji/ASCII toggle for terminal output
│ │ ├── funcs # rsynclite() helper (tar-based directory sync)
│ │ ├── vars # BASEPATH, DRIVE2 path constants
│ │ ├── shutdown # Clean halt (sync, umount, optional viocon kill signal)
│ │ ├── mount9p # 9P filesystem mount (host directory sharing)
│ │ ├── qemufwcfg # QEMU fw_cfg variable loader
│ │ ├── pkgin # Package manager bootstrapper
│ │ └── sailor.vars # Sailor integration variables
│ ├── base/ # Full base+etc system with ksh (builder image base)
│ ├── build/ # Builder microVM service (orchestrates service builds)
│ ├── rescue/ # ~10 MB minimal rescue shell
│ └── <service>/ # One directory per service
│ ├── etc/rc # Runtime init script (MANDATORY for init(8) services)
│ ├── postinst/ # Build-time scripts executed on host/VM builder
│ ├── options.mk # Service build variables (IMGSIZE, ADDPKGS, SETS, etc.)
│ ├── own.mk # User overrides (git-ignored, not committed)
│ ├── sailor.conf # Sailor minimization rules
│ ├── packages/ # Pre-built binary packages for offline install
│ └── NETBSD_ONLY # Marker: build only on native NetBSD
├── smolerfiles/ # SMOLerfile / Dockerfile examples
│ ├── Dockerfile.inc # Shared INCLUDE snippets
│ ├── Dockerfile.<name> # Per-service SMOLerfile (Dockerfile-compatible)
│ ├── SMOLerfile.<name> # Named SMOLerfiles (same syntax, different naming)
│ ├── *.smol # Minimal SMOLerfiles (service name from filename)
│ └── *.inc # Shared include fragments
├── etc/ # VM config files for startnb.sh (-f flag)
│ └── <service>.conf # hostfwd, imgtag, use_pty, KERNEL, NBIMG, etc.
├── bios/ # BIOS firmware files for microvm machine type
├── confkerndev/ # Kernel driver disabler tool (SMOLIFY)
├── app/ # Flask-based web GUI for VM management
├── www/ # Project website and assets
├── k8s/ # Kubernetes device plugin / deployment examples
├── misc/ # Miscellaneous documentation
├── contribs/ # Contributed scripts
├── share/ # Shared assets (e.g. ssh.pub keys)
├── .github/workflows/ # CI/CD pipeline
│ ├── main.yml # Builder + rescue images for amd64 + evbarm-aarch64 on push
│ └── smoler.yml # SMOLerfile service images on smolerfiles/* push
├── db/ # Fetch freshness cache (remote Last-Modified, see freshchk.sh)
├── images/ # Built .img disk images (empty in repo, populated at build)
├── kernels/ # Downloaded kernels (empty in repo, populated at build)
├── sets/ # Downloaded NetBSD sets (empty in repo, populated at build)
├── pkgs/ # Optional pre-fetched packages (empty in repo, populated at build)
├── mnt/ # Build-time mount point (empty directory)
└── disks/ # Additional disk images

3. Two Workflows

3.1 smoler.sh (Docker-style, high-level)

smoler.sh is a thin dispatcher that routes subcommands to dedicated scripts:

CommandRoutes ToPurpose
./smoler.sh build [-y] [-t tag] [--build-arg K=V] [VAR=val] <SMOLerfile>smoler/build.shParse SMOLerfile → generate service dir → call bmake build
./smoler.sh run <image> [startnb.sh flags]startnb.shRun 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.shPush to OCI registry via oras
./smoler.sh pull <image>smoler/img.shPull from OCI registry via oras
./smoler.sh images [ok]smoler/img.shList 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:

  1. 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)

  1. Checks for etc/<base>.conf → passes -f etc/<base>.conf to startnb.sh
  2. Falls back to checking images/<image>.img → passes -i <image> to startnb.sh
  3. If neither exists, shows startnb.sh -h usage

`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)
CommandPurpose
bmake buildimgBuild the builder image (native on NetBSD/FreeBSD/Linux; on macOS this fails — the build target falls back to fetchimg there)
bmake fetchimgDownload pre-built builder image from GitHub Releases (macOS, no FFS support)
bmake SERVICE=<name> buildBuild a service image using the builder microVM
bmake SERVICE=<name> baseBuild only the base filesystem (no builder VM — runs mkimg.sh directly)
bmake SERVICE=<name> MOUNTRO=y buildBuild with read-only root
bmake SERVICE=<name> ARCH=evbarm-aarch64 buildBuild for ARM64
bmake kernfetchDownload the appropriate kernel
bmake setfetchDownload NetBSD sets
bmake pkgfetchDownload binary packages
bmake fetchallAll of the above
bmake rescueShortcut: SERVICE=rescue build
bmake liveFetch 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); running buildimg directly 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 variables
  • service/<name>/etc/rc — runtime init script
  • service/<name>/postinst/postinst-N.sh — build-time execution scripts
  • etc/<name>.conf — VM config for startnb.sh
4.1 Parsing Flow (build.sh internals)
  1. INCLUDE expansion: INCLUDE <file> directives are resolved first by catting the referenced file inline, producing a flat temporary SMOLerfile
  2. LABEL extraction: All LABEL lines (with or without smolbsd. prefix) are extracted via sed/awk, uppercased, and written to options.mk
  3. Service name: From LABEL smolbsd.service=NAME, or from .smol filename (SMOLerfile.foo → SERVICE=foo)
  4. Postinst-0.sh: Generated with chroot setup (pkgin bootstrap, resolv.conf, openssl certs)
  5. Line-by-line parsing: Each directive generates shell commands appended to postinst scripts or etc/rc
  6. Finalization: etc/rc gets . /etc/include/shutdown appended; etc/<name>.conf gets imgtag and use_pty
  7. Build: Calls make (NetBSD) or bmake (elsewhere) with SERVICE=<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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/netbsdfr/smolbsd/skill/badge)](https://verified-skill.com/skills/netbsdfr/smolbsd/skill)

Something wrong with this skill or its page? Tell us.