smolBSD: build your own minimal BSD system

About

smolBSD helps you create a minimal NetBSD-based virtual machine that boots and starts a service in a couple milliseconds.

No prior NetBSD installation is required. Create and start a microvm from any GNU/Linux, NetBSD, or macOS system. PVH boot and various optimizations enable NetBSD/amd64 and NetBSD/i386 to directly boot QEMU or Firecracker in about 10 ms on modern x86 CPUs.

$ bmake SERVICE=bozohttpd build
➡️ starting the builder microvm
➡️ fetching sets
➡️ creating root filesystem (512M)
✅ image ready: bozohttpd-amd64.img

Why smolBSD

Build BSD systems like you build software: fast, reproducible, and minimal.

🧩 Composable

Pick only the components you need, from kernel to services.

⚙️ Reproducible

Every build is deterministic, portable, and easy to version-control.

🚀 Instant Boot

PVH boot to service in ~10 ms on modern hardware.

🐳 Docker Familiar

Build with SMOLerfiles, run with smoler.sh, push and pull via OCI registries.

Two Workflows

Choose the style that fits you: Docker-native or POSIX shell scripting.

🐳 smoler.sh (Docker-style)

$ ./smoler.sh build smolerfiles/Dockerfile.caddy
✅ caddy-amd64:latest built

$ ./smoler.sh run caddy-amd64:latest
[   1.001231] kernel boot time: 10ms
caddy respond -l :8880

Build, run, list, push, and pull images, just like Docker. Images are stored with name-arch:tag naming and can be shared via OCI registries.

🔧 bmake + startnb.sh (manual)

$ bmake SERVICE=caddy build
✅ image ready: caddy-amd64.img

$ ./startnb.sh -f etc/caddy.conf
[   1.001231] kernel boot time: 10ms
caddy respond -l :8880

Full control over the build process and QEMU flags. Images are raw .img files in images/. startnb.sh is the low-level VM launcher that smoler.sh uses under the hood.

SMOLerfile

Define your service with a Dockerfile-compatible syntax. smoler.sh generates the full smolBSD service configuration for you.

FROM: NetBSD sets (base,etc)
LABEL smolbsd.service: service name
LABEL smolbsd.publish: port mapping
LABEL smolbsd.minimize: shrink image
RUN: run commands inside the builder
CMD: default service command

FROM base,etc

LABEL smolbsd.service=caddy
LABEL smolbsd.minimize=y
LABEL smolbsd.publish="8881:8880"

RUN pkgin up && pkgin -y in caddy

EXPOSE 8880

CMD caddy respond -l :8880

OCI Registry

Push and pull microvm images to any OCI-compliant registry, share and version your systems like Docker images.

$ ./smoler.sh push caddy-amd64:latest
✅ pushed to ghcr.io/netbsdfr/smolbsd/caddy-amd64:latest

$ ./smoler.sh pull caddy-amd64:latest
✅ pulled caddy-amd64:latest (347M)

Official images at github.com/orgs/NetBSDfr/packages. Set SMOLREPO to use a custom registry.

Quick Start

Build and boot your own BSD system in seconds:

$ git clone https://github.com/NetBSDfr/smolBSD
$ cd smolBSD

# Docker-style
$ ./smoler.sh build smolerfiles/Dockerfile.myservice
✅ myservice-amd64:latest built

$ ./smoler.sh run myservice-amd64:latest -P
[   1.0092096] kernel boot time: 14ms

# Or classic Makefile
$ bmake SERVICE=sshd build
✅ image ready: sshd-amd64.img

$ ./startnb.sh -f etc/sshd.conf
Starting sshd.
Server listening on 0.0.0.0 port 22.

Service Examples

rescue

The smallest possible microvm, just ~10 MB. A minimal rescue environment with read-only root filesystem.

Supports amd64, i386, and aarch64.

$ bmake SERVICE=rescue build
✅ image ready: rescue-amd64.img

$ ./startnb.sh -k kernels/netbsd-SMOL \
  -i images/rescue-amd64.img
[   1.0000000] NetBSD/amd64 booting ...
#

sshd

A minimal SSH server with key-based authentication. Add your public key, build the image, and you have a remote shell in seconds.

$ cat ~/.ssh/id_ed25519.pub >> service/sshd/etc/mykey.pub
$ bmake SERVICE=sshd build
✅ image ready: sshd-amd64.img

$ ./startnb.sh -f etc/sshd.conf
[   1.0092096] kernel boot time: 14ms
Starting sshd.
Server listening on 0.0.0.0 port 22.

$ ssh -p 2022 ssh@localhost

bozohttpd

A complete static web server in a few megabytes. smolBSD builds a minimal system with bozohttpd preconfigured and ready to serve content immediately on boot.

$ bmake SERVICE=bozohttpd build
✅ image ready: bozohttpd-amd64.img

$ ./startnb.sh -f etc/bozohttpd.conf
[   1.001231] kernel boot time: 10ms
started in daemon mode as 'port http root /var/www'
listening on 0.0.0.0:80

caddy (SMOLerfile)

Define and run a full web server with a single SMOLerfile, build, run, and test in three commands.

$ ./smoler.sh build smolerfiles/Dockerfile.caddy
✅ caddy-amd64:latest built

$ ./smoler.sh run caddy-amd64:latest -P
caddy respond -l :8880

$ curl -I 127.0.0.1:8881
HTTP/1.1 200 OK
Server: Caddy

smolBSD