Skills routeros-qemu-chr
📦

routeros-qemu-chr

Low Risk ⚙️ External commands🌐 Network access📁 Filesystem access

Run MikroTik RouterOS CHR in QEMU

MikroTik RouterOS CHR provides a full-featured virtual router for testing and development, but setup requires navigating QEMU options, VirtIO drivers, and firmware configurations. This skill provides complete guidance for running CHR with acceleration, proper VirtIO setup, and REST API integration.

Supports: Claude Codex Code(CC)
⚠️ 63 Poor
1

Download the skill ZIP

2

Upload in Claude

Go to Settings → Capabilities → Skills → Upload skill

3

Toggle on and start using

Test it

Using "routeros-qemu-chr". Boot CHR with KVM acceleration and REST API on port 9180

Expected outcome:

QEMU launches with hardware acceleration. RouterOS boots in ~5 seconds. HTTP 200 response from http://127.0.0.1:9180/ confirms readiness. REST API accessible at http://127.0.0.1:9180/rest/ with admin credentials.

Using "routeros-qemu-chr". Enable KVM on GitHub Actions Ubuntu runner

Expected outcome:

udev rule created at /etc/udev/rules.d/99-kvm4all.rules. KVM device permissions updated to 0666. QEMU successfully opens /dev/kvm for hardware acceleration. Boot time reduced from ~30s to ~5s.

Using "routeros-qemu-chr". Configure port forwarding for RouterOS services

Expected outcome:

Host ports mapped: 9180→80 (REST API), 9122→22 (SSH), 9728→8728 (API), 9729→8729 (API-SSL), 9291→8291 (WinBox). Services accessible from host via localhost ports.

Security Audit

Low Risk
v2 • 4/16/2026

Documentation and reference skill for running RouterOS CHR in QEMU. Static analysis flagged 343 patterns, but evaluation reveals these are false positives: shell backtick notation in markdown code examples (not execution), sudo in GitHub Actions CI (expected), MD5 references in kernel history docs (not actual usage), and legitimate acceleration detection commands. All network access targets MikroTik infrastructure for downloading CHR images. Risk level set to LOW due to external command patterns in documentation examples, but no actual malicious code present.

5
Files scanned
794
Lines analyzed
12
findings
2
Total audits

High Risk Issues (4)

SKILL.md:16-316references/chr-licensing.md:25-71references/github-actions-ci.md:7-254references/known-issues.md:5-81references/virtio-drivers.md:9-53
Documentation Shell Examples Misidentified as Execution
Static scanner flagged 264 instances of Ruby/shell backtick notation. These are markdown code blocks showing shell command syntax, not actual command execution. Files are documentation with command examples.
references/github-actions-ci.md:34-48
sudo Commands in GitHub Actions CI (Expected Behavior)
GitHub Actions workflow uses sudo for package installation (apt-get install). This is standard CI/CD practice, not privilege escalation risk.
references/github-actions-ci.md:103references/known-issues.md:55-62
nohup for Background QEMU Process (Legitimate Use)
nohup is used to run QEMU in background during CI testing. This is standard practice for running VMs in CI environments.
SKILL.md:271
Base64 HTTP Basic Auth (Standard Practice)
Static scanner flagged btoa('admin:') as weak crypto. This is standard HTTP Basic Auth encoding, not cryptographic weakness.
Medium Risk Issues (3)
SKILL.md:32-38references/github-actions-ci.md:71-72references/chr-licensing.md:36
Network Access to External URLs
Skill downloads CHR images from MikroTik infrastructure. URLs point to download.mikrotik.com and cdn.mikrotik.com for official RouterOS images.
references/github-actions-ci.md:11SKILL.md:69
Device File Access for Virtualization
/dev/kvm access for KVM acceleration detection. This is standard practice for virtualization tooling.
references/github-actions-ci.md:110-238SKILL.md:104-148
Temp Directory Access
/tmp used for QEMU vars files, serial sockets, and log files. Standard temp file usage for VM management.
Low Risk Issues (2)
SKILL.md:110-270references/github-actions-ci.md:130-232
Hardcoded IP Addresses (Localhost)
127.0.0.1 used for RouterOS REST API and port forwarding. Standard localhost addressing.
SKILL.md:24-45references/known-issues.md:35
System Information Commands (Acceleration Detection)
uname, sysctl, and stat commands used for platform detection. Standard virtualization tooling practice.

Risk Factors

⚙️ External commands (3)
SKILL.md:66-83 references/github-actions-ci.md:34-48 references/github-actions-ci.md:103
🌐 Network access (2)
SKILL.md:32-38 references/github-actions-ci.md:71-72
📁 Filesystem access (2)
SKILL.md:69 references/github-actions-ci.md:11
Audited by: claude View Audit History →

Quality Score

45
Architecture
100
Maintainability
87
Content
32
Community
40
Security
100
Spec Compliance

What You Can Build

Automated RouterOS REST API Testing in CI

Run RouterOS CHR as a CI test fixture to validate REST API calls, generate RAML schemas, and test /app YAML configurations without manual router setup.

Development and Learning Environment

Boot a free-license CHR instance to explore RouterOS features, test firewall rules, experiment with bridging, and learn networking concepts without production hardware.

Multi-Architecture Testing

Test RouterOS configurations across both x86_64 and aarch64 architectures using QEMU with appropriate firmware (SeaBIOS for x86, UEFI for ARM) and acceleration options.

Try These Prompts

Basic CHR Setup 
Help me set up RouterOS CHR in QEMU. I need to download the latest stable image and boot it with KVM acceleration and port 9180 for the REST API.
GitHub Actions CI Integration 
Write a GitHub Actions workflow that downloads RouterOS CHR, boots it with KVM if available (falls back to TCG), waits for boot, then runs REST API tests.
ARM64 UEFI Boot Configuration 
Configure QEMU to boot RouterOS CHR aarch64 on macOS Apple Silicon. Include the UEFI pflash setup and explicit virtio-blk-pci device configuration.
Debugging Boot Failures 
RouterOS CHR fails to boot with a blank screen. The disk image uses if=virtio on aarch64. What might be wrong and how do I fix it?

Best Practices

  • Use explicit -device virtio-blk-pci instead of if=virtio shorthand on aarch64 to avoid the MMIO trap that causes silent boot failures
  • Check /dev/kvm writability (not just existence) before enabling KVM, and always fall back to TCG gracefully in case KVM is unavailable
  • Use port forwarding patterns like tcp::9180-:80 instead of hardcoding localhost IPs to make the configuration portable and reusable

Avoid

  • Do not use if=virtio on aarch64 architecture - this resolves to MMIO which RouterOS does not support, causing silent boot failures
  • Do not skip the KVM permission check - /dev/kvm may exist but be unreadable, and QEMU does not silently fall back to TCG on permission errors
  • Do not use git pull && git push in concurrent CI builds - use the retry-with-rebase pattern to avoid push rejections from race conditions

Frequently Asked Questions

What is the speed limit on the free CHR license?
The free CHR license limits interface throughput to 1 Mbps. REST API calls, SSH, WinBox, and WebFig access are unaffected. This limit applies only to actual data forwarding between interfaces.
Why does QEMU Guest Agent not work with HVF acceleration?
RouterOS QGA daemon only starts when it detects a KVM hypervisor via CPUID. Under HVF (macOS) or TCG (software emulation), CPUID 0x40000000 returns no KVM vendor string, so the daemon never starts. Use Linux with KVM for QGA testing.
How do I choose between SeaBIOS and UEFI for CHR boot?
Use SeaBIOS for x86_64 (default, fastest boot). Use UEFI for aarch64 ARM architecture. On x86_64, only SeaBIOS can boot the proprietary boot partition; OVMF cannot read it.
Why is my aarch64 CHR stuck at boot with if=virtio?
On aarch64 virt machine, if=virtio resolves to MMIO transport. RouterOS has virtio_pci but not virtio_mmio driver, so the kernel stalls silently. Always use explicit -device virtio-blk-pci on aarch64.
Can I run multiple CHR instances simultaneously?
Yes. Use unique host ports for each instance (9180, 9181, 9182 for REST API, etc.). Each instance needs its own disk image and PID tracking for cleanup.
What acceleration method should I use?
Use KVM on Linux when host/guest architectures match. Use HVF on macOS Apple Silicon for aarch64 guests. Use TCG as fallback on all platforms when hardware acceleration is unavailable.

Developer Details

Author

tikoci

License

MIT

Repository

https://github.com/tikoci/routeros-skills/tree/main/routeros-qemu-chr

Ref

main

File structure

📁 references/

📄 chr-licensing.md

📄 github-actions-ci.md

📄 known-issues.md

📄 virtio-drivers.md

📄 SKILL.md