quickchr

Experimental — quickchr is under active development. Most testing has been on macOS (Apple Silicon + Intel), with CI on Linux (x86_64 + aarch64). Windows support is early-stage: unit tests pass on windows-latest CI, but integration tests (running a real CHR via QEMU for Windows) are not yet automated. Expect rough edges on Windows — bug reports welcome.

CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.

• Bun runtime
• QEMU with qemu-system-x86_64 and/or qemu-system-aarch64
• qemu-img for disk resize and extra-disk features (--boot-size, --add-disk, quickchr disk)
• UEFI firmware (edk2) for arm64 CHR

Install QEMU:

# macOS
brew install qemu

# Ubuntu/Debian
sudo apt install qemu-system-x86 qemu-system-arm qemu-efi-aarch64 qemu-utils

# Fedora/RHEL
sudo dnf install qemu-kvm qemu-system-aarch64 edk2-aarch64 qemu-img

# Arch
sudo pacman -S qemu-full

# Windows — install QEMU (qemu-img is included)
winget install SoftwareFreedomConservancy.QEMU

# Install Bun (PowerShell — matches bun.sh official install docs)
powershell -c "irm bun.sh/install.ps1 | iex"
# Alternative: winget install Oven-sh.Bun

CLI:

bun install -g @tikoci/quickchr
quickchr doctor

Library:

bun add @tikoci/quickchr

The easiest way to start is the interactive wizard — it walks through every option and starts the CHR for you:

quickchr setup

Or run quickchr with no arguments on a TTY to get the same wizard automatically. See MANUAL.md §3 setup for a step-by-step breakdown of every wizard prompt.

All wizard options are also available as flags for scripting:

# Create a machine without starting it
quickchr add --name my-chr --channel stable --arch arm64

# Create with a resized boot disk and extra blank disks
quickchr add --name lab --boot-size 1G --add-disk 512M --add-disk 2G

# Start an existing machine
quickchr start my-chr

# Create and start in one step
quickchr start --name throwaway --version 7.22.1 --boot-size 2G

# List instances (table view)
quickchr list

# Detailed status for one instance
quickchr status my-chr

# Stop an instance
quickchr stop my-chr

# Stop all instances
quickchr stop --all

# Run a RouterOS CLI command on a running instance
quickchr exec my-chr /system/resource/print
quickchr exec my-chr ":put [/system/routerboard/get serial-number]"

# Attach to serial console of a running instance (exit: Ctrl-A X)
quickchr console my-chr

# Tail QEMU log
quickchr logs my-chr
quickchr logs my-chr --follow

# Query live machine config (license, device-mode, admin users)
quickchr get my-chr
quickchr get my-chr license
quickchr get my-chr device-mode --json

# Manage snapshots (requires qcow2 boot disk)
quickchr snapshot my-chr list
quickchr snapshot my-chr save before-upgrade
quickchr snapshot my-chr load before-upgrade
quickchr snapshot my-chr delete before-upgrade

# Apply or renew a trial license
quickchr license my-chr

# Network discovery and virtual socket management
quickchr networks
quickchr networks sockets

# Set up shell completions (bash/zsh/fish)
quickchr completions

# Reset disk to fresh image
quickchr clean my-chr

# Inspect disk layout
quickchr disk lab

# Remove instance entirely
quickchr remove my-chr

# Check prerequisites
quickchr doctor

quickchr separates boot-only machine management from post-boot provisioning.

• Boot-only / QEMU-local features work on older RouterOS 7.x builds: image download, boot/start, disk resize, extra disks, network attachment, and port mappings.
• Post-boot provisioning is validated/tested on RouterOS 7.20.8+ only: package install, managed login or custom user creation, disabling admin, CHR license operations, and device-mode changes.
• This is a quickchr support policy, not a RouterOS claim that older versions can never work. We intentionally stop at the first long-term baseline to avoid version-specific provisioning traps that are not covered by tests.
• If you plan to provision, prefer --channel long-term or an explicit version >= 7.20.8.

By default quickchr start runs QEMU in the background: QEMU is spawned as a detached process and the command returns once CHR has booted. Use quickchr list, quickchr status, and quickchr stop to manage it.

# Background (default) — returns after CHR finishes booting
quickchr start --channel stable

# Foreground — serial console attached to your terminal
quickchr start --channel stable --fg

In foreground mode, your terminal becomes the CHR serial console. Use these key sequences:

Note: Background QEMU processes are true OS-level orphans — quickchr does not use shell job control (&). After the command returns you can close the terminal and QEMU keeps running. Use quickchr stop <name> to shut it down cleanly.

• The CHR boot image starts as raw. Using --boot-size converts it to qcow2 and resizes it before first boot.
• Extra disks from --add-disk are always created as blank qcow2 images.
• quickchr clean <name> removes any resized boot disk and extra disks, then recreates them from the saved machine config.
• quickchr disk <name> shows the stored disk layout. If qemu-img is installed, it also shows virtual and actual sizes.
• quickchr snapshot manages qcow2 internal snapshots (requires a qcow2 boot disk).

By default each CHR gets a single user-mode NIC (SLIRP). Use --add-network to add more NICs or replace the default:

# Two CHRs on a shared L2 segment via socket_vmnet (macOS) or bridge (Linux)
quickchr start --name router1 --add-network user --add-network shared
quickchr start --name router2 --add-network user --add-network shared

# Named virtual socket (L2 tunnel between CHRs)
quickchr networks sockets create lab-switch
quickchr start --name r1 --add-network socket::lab-switch
quickchr start --name r2 --add-network socket::lab-switch

# Bridge to a physical interface
quickchr start --name gw --add-network user --add-network bridged:en0

Each instance gets a block of 10 ports. With the default base of 9100, the first instance maps:

The second instance gets 9110–9119, and so on.

import { QuickCHR } from "@tikoci/quickchr";

// Start a CHR instance
const chr = await QuickCHR.start({
  name: "disk-lab",
  channel: "stable",
  arch: "arm64",
  mem: 512,
  bootSize: "1G",
  extraDisks: ["512M", "2G"],
});

// Use REST API
const info = await chr.rest("/system/resource");
console.log(info);

// Run a RouterOS CLI command
const result = await chr.exec("/system/resource/print");
console.log(result);

// Stop (or remove)
await chr.stop();
await chr.remove();

console.log(chr.state.bootDiskFormat); // "qcow2"
console.log(chr.state.extraDisks);     // ["512M", "2G"]

import { describe, test, afterAll, expect } from "bun:test";
import { QuickCHR } from "@tikoci/quickchr";

let chr: Awaited<ReturnType<typeof QuickCHR.start>>;

test("boot CHR and check version", async () => {
  chr = await QuickCHR.start({ channel: "stable" });

  const resource = await chr.rest("/system/resource");
  expect(resource["board-name"]).toBe("CHR");
}, 120_000);

afterAll(async () => {
  if (chr) await chr.remove();
});

• MANUAL.md — complete reference: every CLI command, every library API, provisioning, channels, networking, storage, errors. Source-checked.
• DESIGN.md — architecture, layers, design principles.
• CONTRIBUTING.md — dev setup and bun run check.
• CHANGELOG.md — release history.

MIT