![](\"www/smolBSD.png\")
\n\n**smolBSD**\n\nbuild your own minimal BSD UNIX system\n\n\n\n\n\n![](\"www/boot.png\")
\n\n![\"\"](\"static/smolBSD.png\")
\n\n## App Usage\n\n## QuickStart\n\n~~~\nscripts/app-run.sh # just does Setup, Config & Run\nfirefox http://localhost:5000\n~~~\n\n## Setup\n\n~~~\ncd app/\npython3 -m venv .\n. bin/activate\npip install -r requirements.txt\n~~~\n\n## Running\n\n~~~\ncd app/\n. bin/activate\nflask run\n~~~\n\n## Configuration\n\n~~~\n- 1st, env vars have preference\n- 2nd, app vars at .env\n- 3rd, flask vars at .flaskenv\n~~~\n\n## Cleanup\n\n~~~\nrm -ri bin/ include/ lib/ lib64/ __pycache__/ pyvenv.cfg\n~~~\n"
},
{
"path": "app/app.py",
"content": "import json\nimport logging\nimport os\nimport psutil\nimport socket\nimport subprocess\nimport dotenv\nimport sys\nfrom flask import Flask, send_file, jsonify, request\n\napp = Flask(__name__)\n# Get environment variables from .flaskenv / .env\ndotenv.load_dotenv()\n\ncwd = os.environ['FLASK_CWD'] if 'FLASK_CWD' in os.environ else '..'\nloglevel = int(os.environ['FLASK_LOGLEVEL']) if 'FLASK_LOGLEVEL' in os.environ else logging.ERROR\nlog = logging.getLogger('werkzeug')\nlog.setLevel(loglevel)\n\nvmlist = {}\n\ndef get_vmlist():\n vmlist.clear()\n for filename in os.listdir(f'{cwd}/etc'):\n if filename.endswith('.conf'):\n vmname = filename.split(\".conf\")[0]\n config_data = {}\n with open(f'{cwd}/etc/{filename}', 'r') as f:\n lines = f.readlines()\n for line in lines:\n line = line.strip()\n if not line:\n continue\n elif line.startswith('#') or line.startswith('extra'):\n continue\n elif '=' in line:\n key, value = line.split('=', 1)\n config_data[key.strip()] = value.strip()\n\n # Check if QEMU process is running\n status = 'running' if get_pid(vmname) > 0 else 'stopped'\n\n vmlist[vmname] = config_data\n vmlist[vmname]['status'] = status\n\n return vmlist\n\n\ndef list_files(path):\n try:\n items = [f for f in os.listdir(path) if not f.startswith(\".\")]\n return jsonify(items)\n except FileNotFoundError:\n return jsonify({\"error\": \"Directory not found\"}), 404\n except Exception as e:\n return jsonify({\"error\": str(e)}), 500\n\n\ndef get_port(vmname, service, default_port):\n port = default_port\n if vmname in vmlist and service in vmlist[vmname]:\n return vmlist[vmname][service]\n for vm in vmlist:\n if not service in vmlist[vm]:\n continue\n vm_port = int(vmlist[vm][service])\n if vm_port >= port:\n port = vm_port + 1\n\n return port\n\n\ndef query_qmp(command, vmname):\n if not 'qmp_port' in vmlist[vmname]:\n return jsonify(\n {\"success\": False, \"message\": f\"QMP not enabled in {vmname}\"}\n ), 404\n\n qmp_port = int(vmlist[vmname]['qmp_port'])\n\n with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n rep_len = 8192\n s.connect((\"localhost\", qmp_port))\n response = s.recv(rep_len)\n # mandatory before command (duh?)\n s.sendall('{\"execute\": \"qmp_capabilities\"}\\n'.encode('utf-8'))\n response = s.recv(rep_len)\n # actual command\n s.sendall(f'{{\"execute\": \"{command}\"}}\\n'.encode('utf-8'))\n response = s.recv(rep_len)\n\n return json.loads(response)\n\ndef get_pid(vmname):\n pid_file = f\"{cwd}/qemu-{vmname}.pid\"\n if not os.path.exists(pid_file):\n return -1\n f = open(pid_file, \"r\")\n pid = int(f.read().strip())\n if psutil.pid_exists(pid):\n return pid\n else:\n return -1\n\ndef get_cpu_usage(vmname):\n ncpus = 1\n r = query_qmp(\"query-cpus-fast\", vmname)\n if r and 'return' in r:\n ncpus = len(r['return'])\n pid = get_pid(vmname)\n if pid < 0:\n return 0\n process = psutil.Process(pid)\n return process.cpu_percent(interval=0.1) / ncpus\n\n## routes\n\n@app.route(\"/\")\ndef index():\n # do not render template, frontend logic handled by Vue\n return send_file(\"index.html\")\n\n@app.route(\"/static/smolBSD.png\")\ndef assets():\n return send_file(\"static/smolBSD.png\")\n\n@app.route(\"/vmlist\")\ndef vm_list():\n return jsonify(get_vmlist())\n\n\n@app.route(\"/getkernels\")\ndef getkernels():\n return list_files(f'{cwd}/kernels/')\n\n\n@app.route(\"/getimages\")\ndef getimages():\n return list_files(f'{cwd}/images/')\n\n\n@app.route(\"/start\", methods=[\"POST\"])\ndef start_vm():\n vm_name = request.json.get(\"vm_name\")\n\n config_file = f'{cwd}/etc/{vm_name}.conf'\n\n if not os.path.exists(config_file):\n return jsonify(\n {\"success\": False, \"message\": \"Config file not found\"}\n ), 404\n\n try:\n ret = subprocess.Popen([f\"{cwd}/startnb.sh\", \"-f\", config_file, \"-d\"], cwd=cwd)\n return jsonify({\"success\": True, \"message\": \"Starting VM\"})\n except Exception as e:\n return jsonify({\"success\": False, \"message\": str(e)}), 500\n\n\n@app.route(\"/stop\", methods=[\"POST\"])\ndef stop_vm():\n vm_name = request.json.get(\"vm_name\")\n pid_file = f'{cwd}/qemu-{vm_name}.pid'\n\n try:\n pid = get_pid(vm_name)\n if pid < 0:\n return jsonify(\n {\"success\": False, \"message\": \"PID file not found\"}\n ), 404\n os.kill(int(pid), 15)\n os.remove(pid_file)\n return jsonify({\"success\": True, \"message\": \"Stopping VM\"})\n except Exception as e:\n return jsonify({\"success\": False, \"message\": str(e)}), 500\n\n\n@app.route(\"/saveconf\", methods=['POST'])\ndef saveconf():\n try:\n data = request.get_json()\n if not data:\n return jsonify(\n {\"success\": False, \"message\": \"No JSON payload provided\"}\n ), 400\n\n vmname = data.get(\"vm\")\n if not vmname:\n return jsonify(\n {\n \"success\": False,\n \"message\": \"'vm' key is required in the JSON payload\"\n }\n ), 400\n\n os.makedirs(f'{cwd}/etc', exist_ok=True)\n file_path = f\"{cwd}/etc/{vmname}.conf\"\n\n with open(file_path, 'w') as file:\n for key, value in data.items():\n if key == \"tcpserial\":\n if value is True:\n serial_port = get_port(vmname, 'serial_port', 5555)\n key = \"serial_port\"\n value = f\"{serial_port}\"\n else:\n continue\n if key == \"rmprotect\" and value == False:\n continue\n\n file.write(f\"{key}={value}\\n\")\n\n qmp_port = get_port(vmname, 'qmp_port', 4444)\n file.write(f'qmp_port={qmp_port}\\n')\n extra = 'extra=\"-pidfile qemu-${vm}.pid\"'\n file.write(f'{extra}\\n')\n\n return jsonify({\"success\": True, \"message\": file_path}), 200\n\n except Exception as e:\n return jsonify({\"success\": False, \"message\": str(e)}), 500\n\n\n@app.route('/rm/![](\"images/smolTelegram.png\")
\n\n![](\"images/smolClaw.png\")
\n\n# smolClaw\n\n![](\"images/smolcap.png\")
\n\n[picoclaw][1] running on a microVM!\n\n![](\"logo.svg\")
\n![\"smolBSD](\"smolBSD.png\")
\n \n build your own minimal BSD UNIX system\n
\n\n\n smolBSD is a meta-operating system built on top of NetBSD. \n It lets you compose your own UNIX environment — from a single-purpose microservice system to a fully-custom OS image — in just a few minutes.\n
\n\n The smolBSD environment uses the netbsd-MICROVM kernel as its foundation, leveraging the same portable, reliable codebase that powers NetBSD itself. \n You decide what to include — sshd, httpd, or your own service — and smolBSD builds a coherent, minimal, bootable image ready to run anywhere.\n
\n\n$ bmake SERVICE=bozohttpd build\n➡️ starting the builder microvm\n➡️ host filesystem mounted on /mnt\n➡️ fetching sets\n➡️ creating root filesystem (512M)\n✅ image ready: bozohttpd-amd64.img\n\n
Build BSD systems like you build software — fast, reproducible, and minimal.
\nPick only the components you need — from kernel to services.
\nEvery build is deterministic, portable, and easy to version-control.
\nPowered by netbsd-MICROVM — boot to service in milliseconds.
\nRuns anywhere QEMU or Firecracker runs — cloud, CI, edge, or laptop.
\nBuild and boot your own BSD system in seconds:
\n\n$ git clone https://github.com/NetBSDfr/smolBSD\n$ cd smolBSD\n$ cat ~/.ssh/id_ed25519.pub >> service/sshd/etc/mykey.pub\n$ bmake SERVICE=sshd build\n➡️ starting the builder microvm\n➡️ fetching sets\n➡️ creating root filesystem (512M)\n✅ image ready: sshd-amd64.img\n➡️ killing the builder microvm\n\n$ ./startnb.sh -f etc/sshd.conf \n[ 1.0092096] kernel boot time: 14ms\nStarting sshd.\nServer listening on :: port 22.\nServer listening on 0.0.0.0 port 22.\n\n$ ssh -p 2022 ssh@localhost\n\n \n Download\n \n
Your own service in seconds using a simple\nDockerfile!
\n\nFROM base,etc\n\nLABEL SERVICE=caddy\n\nRUN pkgin up && pkgin -y in caddy\n\nEXPOSE 8881:8880\n\nCMD caddy respond -l :8880\n\n
\n A complete static web server in a few megabytes. \n smolBSD builds a minimal system with bozohttpd\npreconfigured and ready to serve content immediately on boot.\n
\n$ bmake SERVICE=bozohttpd build\n➡️ starting the builder microvm\n➡️ fetching sets\n➡️ creating root filesystem (512M)\n✅ image ready: bozohttpd-amd64.img\n\n$ ./startnb.sh -f etc/bozohttpd.conf\n[ 1.001231] kernel boot time: 10ms\nStarting bozohttpd on :80\nlistening on 0.0.0.0:80\n\n
\n A lightweight build and image creation service based entirely on\nNetBSD tools. \n The nbakery image gives you a taste of a preconfigured NetBSD environment with all the well known tools.\n
\n$ bmake SERVICE=nbakery build\n➡️ starting the builder microvm\n➡️ fetching sets\n➡️ creating root filesystem (512M)\n✅ image ready: nbakery-amd64.img\n\n$ ./startnb.sh -f etc/nbakery.conf\n[ 1.008374] kernel boot time: 11ms\n\nWelcome to the (n)bakery! 🧁\n\n💪 doas <command> to run command as root\n📦 pkgin to manage packages\n🚪 exit to cleanly shutdown, ^a-x to exit qemu\n🪟 you are inside a tmux with prefix ^q\n\n
\n A minimal secure shell server started with nitro,\ndesigned to launch instantly and provide remote access with zero unnecessary\nservices. \n Ideal for an SSH bouncer.\n
\n$ bmake SERVICE=nitrosshd build\n➡️ starting the builder microvm\n➡️ fetching sets\n➡️ creating root filesystem (512M)\n✅ image ready: nitrosshd-amd64.img\n\n$ ./startnb.sh -f etc/sshd.conf\n[ 1.011598] kernel boot time: 12ms\nCreated tmpfs /dev (1835008 byte, 3552 inodes)\nStarting sshd.\nServer listening on :: port 22.\nServer listening on 0.0.0.0 port 22.\n\n
\n smolBSD is an independent project built on top of NetBSD. \n Join us, share your micro-systems, or contribute new services and build recipes.\n
\n \n