routeros-qemu-chr

Name: routeros-qemu-chr
Author: tikoci

36stars8forks

How to install routeros-qemu-chr?

tikoci/routeros-skills/routeros-qemu-chr

$npx -y skills add tikoci/routeros-skills --skill routeros-qemu-chr

Installs into the current project.

Summary

MikroTik RouterOS CHR (Cloud Hosted Router) with QEMU. Use when: running RouterOS in QEMU, booting CHR images, debugging CHR boot failures, setting up VirtIO devices for RouterOS, choosing between SeaBIOS and UEFI boot, configuring QEMU port forwarding for RouterOS REST API, sett

Files · 1

View on GitHub

SKILL.md

1	# RouterOS CHR with QEMU
2
3	## What Is CHR
4
5	Cloud Hosted Router (CHR) is MikroTik's x86_64 and aarch64 RouterOS image designed for virtual machines. Free license allows unlimited use with 1 Mbps speed limit — sufficient for development, testing, API work, and packet sniffer debugging. A free 60-day trial removes the speed limit entirely (requires a free mikrotik.com account). See [CHR licensing reference](./references/chr-licensing.md) for full details on license tiers, trial activation, and expiry behavior.
6
7	## Image Variants
8
9	\| Image \| Architecture \| Boot method \| Source \|
10	\|---\|---\|---\|---\|
11	\| `chr-<ver>.img` \| x86_64 \| SeaBIOS (MBR chain-load) \| download.mikrotik.com \|
12	\| `chr-<ver>-arm64.img` \| aarch64 \| UEFI (EDK2 pflash) \| download.mikrotik.com \|
13	\| `chr-efi.img` (fat-chr) \| x86_64 \| UEFI (OVMF) \| tikoci/fat-chr GitHub \|
14
15	Standard x86 image has a proprietary boot partition — it looks like an EFI System Partition in GPT but is NOT FAT. UEFI firmware (OVMF) cannot read it. Only SeaBIOS can boot it via MBR chain-load.
16
17	The `fat-chr` repackaged image converts this to standard FAT16 with `EFI/BOOT/BOOTX64.EFI`, enabling UEFI boot. Required for Apple Virtualization.framework on X86 macOS, optional everywhere else.
18
19	Disk layout (128 MiB, both architectures): Hybrid GPT+MBR, partition 1 = boot (~33 MiB), partition 2 = ext4 root (~94 MiB).
20
21	## Downloading CHR Images
22
23	```typescript
24	// Resolve current version
25	const channel = "stable"; // or: long-term, testing, development
26	const version = await fetch(
27	`https://upgrade.mikrotik.com/routeros/NEWESTa7.${channel}`
28	).then(r => r.text()).then(s => s.trim());
29
30	// Download x86_64 image
31	const url = `https://download.mikrotik.com/routeros/${version}/chr-${version}.img.zip`;
32	// Download aarch64 image
33	const armUrl = `https://download.mikrotik.com/routeros/${version}/chr-${version}-arm64.img.zip`;
34	```
35
36	Images are distributed as `.img.zip` — unzip to get the raw `.img` disk file.
37
38	## Pattern Choices: QEMU Invocation
39
40	There are several valid approaches to launching CHR under QEMU. Each has tradeoffs:
41
42	### Pattern A: Inline arguments (simplest, good for scripts)
43
44	Everything on the command line. Easy for an LLM to construct and debug — all state is visible in one place.
45
46	```sh
47	qemu-system-x86_64 -M q35 -m 256 -smp 1 \
48	-drive file=chr.img,format=raw,if=virtio \
49	-netdev user,id=net0,hostfwd=tcp::9180-:80 \
50	-device virtio-net-pci,netdev=net0 \
51	-display none -serial stdio
52	```
53
54	Pros: Single command, easy to read, easy to modify.
55	Cons: Long command lines, hard to version-control, no persistence.
56
57	### Pattern B: Wrapper script (good for reuse)
58
59	A shell script that detects acceleration, handles firmware paths, manages PID files.
60
61	```sh
62	#!/bin/sh
63	# detect acceleration
64	if [ "$(uname -s)" = "Linux" ] && [ -w /dev/kvm ]; then
65	ACCEL="-accel kvm"
66	elif [ "$(uname -s)" = "Darwin" ] && [ "$(sysctl -n kern.hv_support 2>/dev/null)" = "1" ]; then
67	ACCEL="-accel hvf"
68	else
69	ACCEL="-accel tcg"
70	fi
71
72	qemu-system-x86_64 -M q35 -m 256 -smp 1 \
73	$ACCEL \
74	-drive file=chr.img,format=raw,if=virtio \
75	-netdev user,id=net0,hostfwd=tcp::${PORT:-9180}-:80 \
76	-device virtio-net-pci,netdev=net0 \
77	-display none -serial stdio
78	```
79
80	Pros: Portable, handles platform differences, parameterizable.
81	Cons: Shell scripting limitations, harder to compose from TypeScript.
82
83	### Pattern C: Programmatic launch from Bun/TypeScript (good for integration tests)
84
85	Launch QEMU as a child process with full control:
86
87	```typescript
88	import { $ } from "bun";
89
90	const port = 9180;
91	const accel = await detectAccel();
92	const proc = Bun.spawn([
93	"qemu-system-x86_64", "-M", "q35", "-m", "256",
94	"-accel", accel,
95	"-drive", `file=chr.img,format=raw,if=virtio`,
96	"-netdev", `user,id=net0,hostfwd=tcp::${port}-:80`,
97	"-device", "virtio-net-pci,netdev=net0",
98	"-display", "none",
99	"-chardev", `socket,id=serial0,path=/tmp/chr-serial.sock,server=on,wait=off`,
100	"-serial", "chardev:serial0",
101	"-monitor", `unix:/tmp/chr-monitor.sock,server,nowait`,
102	], { stdio: ["ignore", "pipe", "pipe"] });
103
104	// Wait for boot
105	await waitForBoot(`http://127.0.0.1:${port}/`);
106	```
107
108	Pros: Full lifecycle control, parallel instance management, TypeScript-native.
109	Cons: More code, QEMU args still need to be correct.
110
111	### Pattern D: Config file (`--readconfig`) (declarative, used by mikropkl)
112
113	QEMU's `--readconfig` loads an INI-format file for device/machine config. The mikropkl project uses this for its declarative VM packaging.
114
115	Tradeoffs: Separates concerns (config vs laun

People who liked this also viewed

6 picks

Type

routeros-qemu-chr

36stars8forks

View on GitHub

How to install routeros-qemu-chr?

tikoci/routeros-skills/routeros-qemu-chr

$npx -y skills add tikoci/routeros-skills --skill routeros-qemu-chr

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# RouterOS CHR with QEMU
2
3	## What Is CHR
4
5	Cloud Hosted Router (CHR) is MikroTik's x86_64 and aarch64 RouterOS image designed for virtual machines. Free license allows unlimited use with 1 Mbps speed limit — sufficient for development, testing, API work, and packet sniffer debugging. A free 60-day trial removes the speed limit entirely (requires a free mikrotik.com account). See [CHR licensing reference](./references/chr-licensing.md) for full details on license tiers, trial activation, and expiry behavior.
6
7	## Image Variants
8
9	\| Image \| Architecture \| Boot method \| Source \|
10	\|---\|---\|---\|---\|
11	\| `chr-<ver>.img` \| x86_64 \| SeaBIOS (MBR chain-load) \| download.mikrotik.com \|
12	\| `chr-<ver>-arm64.img` \| aarch64 \| UEFI (EDK2 pflash) \| download.mikrotik.com \|
13	\| `chr-efi.img` (fat-chr) \| x86_64 \| UEFI (OVMF) \| tikoci/fat-chr GitHub \|
14
15	Standard x86 image has a proprietary boot partition — it looks like an EFI System Partition in GPT but is NOT FAT. UEFI firmware (OVMF) cannot read it. Only SeaBIOS can boot it via MBR chain-load.
16
17	The `fat-chr` repackaged image converts this to standard FAT16 with `EFI/BOOT/BOOTX64.EFI`, enabling UEFI boot. Required for Apple Virtualization.framework on X86 macOS, optional everywhere else.
18
19	Disk layout (128 MiB, both architectures): Hybrid GPT+MBR, partition 1 = boot (~33 MiB), partition 2 = ext4 root (~94 MiB).
20
21	## Downloading CHR Images
22
23	```typescript
24	// Resolve current version
25	const channel = "stable"; // or: long-term, testing, development
26	const version = await fetch(
27	`https://upgrade.mikrotik.com/routeros/NEWESTa7.${channel}`
28	).then(r => r.text()).then(s => s.trim());
29
30	// Download x86_64 image
31	const url = `https://download.mikrotik.com/routeros/${version}/chr-${version}.img.zip`;
32	// Download aarch64 image
33	const armUrl = `https://download.mikrotik.com/routeros/${version}/chr-${version}-arm64.img.zip`;
34	```
35
36	Images are distributed as `.img.zip` — unzip to get the raw `.img` disk file.
37
38	## Pattern Choices: QEMU Invocation
39
40	There are several valid approaches to launching CHR under QEMU. Each has tradeoffs:
41
42	### Pattern A: Inline arguments (simplest, good for scripts)
43
44	Everything on the command line. Easy for an LLM to construct and debug — all state is visible in one place.
45
46	```sh
47	qemu-system-x86_64 -M q35 -m 256 -smp 1 \
48	-drive file=chr.img,format=raw,if=virtio \
49	-netdev user,id=net0,hostfwd=tcp::9180-:80 \
50	-device virtio-net-pci,netdev=net0 \
51	-display none -serial stdio
52	```
53
54	Pros: Single command, easy to read, easy to modify.
55	Cons: Long command lines, hard to version-control, no persistence.
56
57	### Pattern B: Wrapper script (good for reuse)
58
59	A shell script that detects acceleration, handles firmware paths, manages PID files.
60
61	```sh
62	#!/bin/sh
63	# detect acceleration
64	if [ "$(uname -s)" = "Linux" ] && [ -w /dev/kvm ]; then
65	ACCEL="-accel kvm"
66	elif [ "$(uname -s)" = "Darwin" ] && [ "$(sysctl -n kern.hv_support 2>/dev/null)" = "1" ]; then
67	ACCEL="-accel hvf"
68	else
69	ACCEL="-accel tcg"
70	fi
71
72	qemu-system-x86_64 -M q35 -m 256 -smp 1 \
73	$ACCEL \
74	-drive file=chr.img,format=raw,if=virtio \
75	-netdev user,id=net0,hostfwd=tcp::${PORT:-9180}-:80 \
76	-device virtio-net-pci,netdev=net0 \
77	-display none -serial stdio
78	```
79
80	Pros: Portable, handles platform differences, parameterizable.
81	Cons: Shell scripting limitations, harder to compose from TypeScript.
82
83	### Pattern C: Programmatic launch from Bun/TypeScript (good for integration tests)
84
85	Launch QEMU as a child process with full control:
86
87	```typescript
88	import { $ } from "bun";
89
90	const port = 9180;
91	const accel = await detectAccel();
92	const proc = Bun.spawn([
93	"qemu-system-x86_64", "-M", "q35", "-m", "256",
94	"-accel", accel,
95	"-drive", `file=chr.img,format=raw,if=virtio`,
96	"-netdev", `user,id=net0,hostfwd=tcp::${port}-:80`,
97	"-device", "virtio-net-pci,netdev=net0",
98	"-display", "none",
99	"-chardev", `socket,id=serial0,path=/tmp/chr-serial.sock,server=on,wait=off`,
100	"-serial", "chardev:serial0",
101	"-monitor", `unix:/tmp/chr-monitor.sock,server,nowait`,
102	], { stdio: ["ignore", "pipe", "pipe"] });
103
104	// Wait for boot
105	await waitForBoot(`http://127.0.0.1:${port}/`);
106	```
107
108	Pros: Full lifecycle control, parallel instance management, TypeScript-native.
109	Cons: More code, QEMU args still need to be correct.
110
111	### Pattern D: Config file (`--readconfig`) (declarative, used by mikropkl)
112
113	QEMU's `--readconfig` loads an INI-format file for device/machine config. The mikropkl project uses this for its declarative VM packaging.
114
115	Tradeoffs: Separates concerns (config vs laun

People who liked this also viewed

6 picks

Type