Escribir IronFlockOS en una unidad

ironflock os flash prepara la unidad desde la que arranca un dispositivo nuevo. Escribe IronFlockOS y el archivo de configuración del dispositivo (.flock) en la unidad, y el dispositivo se inscribe en su primer arranque: se conecta a IronFlock como el dispositivo de ese archivo .flock. Puedes preparar:

• una memoria USB, una tarjeta SD o un disco externo desde el que arranca el dispositivo,
• una memoria USB de instalación que instala IronFlockOS en el disco interno de un PC,
• un archivo de imagen de disco desde el que arranca una máquina virtual.

FlockFlasher es la app de escritorio para la misma tarea. Para obtener el archivo .flock de un dispositivo, consulta Conectar dispositivos.

Ejecución típica

# 1. Conectar la memoria USB o la tarjeta SD y listar las unidades en las que se puede escribir
ironflock os drives
# 2. Opcional: listar las imágenes que ofrece el catálogo
ironflock os images
# 3. Escribir IronFlockOS y el archivo .flock del dispositivo en la unidad
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash muestra su plan y pregunta antes de borrar la unidad. Cuando termina, pon la unidad en el dispositivo y arranca el dispositivo desde ella.

ironflock os images

Lista las imágenes de IronFlockOS que se pueden escribir en una unidad. Por defecto lista las imágenes del release del canal de producción.

ironflock os images [flags]

Se ejecuta en Linux y macOS. No necesita root. No pregunta nada.

Flags

Los flags que aceptan todos los comandos están en Flags, salida y códigos de salida.

Qué hace

La lista viene del catálogo firmado de IronFlockOS del servidor de descargas, <download base>/ironflockos/manifest.json. ironflock solo usa el catálogo cuando su firma Ed25519 se verifica con la clave del catálogo integrada en ironflock. FlockFlasher y el agente del dispositivo llevan fijada la misma clave. Ningún flag ni ninguna variable de entorno desactiva esta comprobación. La base de descarga es la nube de IronFlock salvo que indiques otra; consulta Base de descarga.

El último catálogo que se verificó se guarda en una carpeta de caché, una copia por base de descarga:

Cuando no se puede alcanzar el servidor de descargas, la copia guardada lo sustituye, con una nota en stderr. Se rechaza un catálogo de la misma base de descarga que sea más antiguo que la copia guardada.

Una imagen se nombra por su target de hardware, su variante y su kernel: ironflockos-<target>-<variant>, con -rt para el kernel de tiempo real. ironflockos-amd64-efi-base-rt es el sistema base con el kernel de tiempo real para PC x86-64 con UEFI. Los targets son:

• amd64-efi — PC x86-64 con UEFI
• arm64-efi — máquina ARM64 con UEFI
• rpi-arm64 — Raspberry Pi 4, 400 y CM4; Raspberry Pi 5 y CM5

Las variantes son base, nvidia e installer. La imagen de instalación crea una memoria USB que instala una de las imágenes que lleva en el disco de la máquina que arranca desde ella. Una imagen de una variante, un kernel o una arquitectura que este ironflock no conoce (de un release más reciente) se omite, con una nota en stderr.

Ejemplos

# Las imágenes del release de producción actual
ironflock os images
# Solo las imágenes de Raspberry Pi
ironflock os images --target rpi-arm64
# Las imágenes del canal de pruebas, como JSON
ironflock os images --channel test --json

Resultado

IMAGE                            VERSION  SIZE      HARDWARE
ironflockos-amd64-efi-base       0.13.0   638.1 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-base-rt    0.13.0   650.4 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-nvidia     0.13.0   1.0 GB    x86-64 PC with UEFI
ironflockos-amd64-efi-installer  0.13.0   2.5 GB    x86-64 PC with UEFI, installer stick for base, base-rt, nvidia
ironflockos-arm64-efi-base       0.13.0   582.4 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-base-rt    0.13.0   594.1 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-installer  0.13.0   1.5 GB    ARM64 machine with UEFI, installer stick for base, base-rt
ironflockos-rpi-arm64-base       0.13.0   639.4 MB  Raspberry Pi 4, 400 and CM4; Raspberry Pi 5 and CM5

Con --json (aquí con --target rpi-arm64):

{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"channels":{"production":"0.13.0","test":"0.13.0"},"images":[{"image_id":"ironflockos-rpi-arm64-base","version":"0.13.0","channels":["production","test"],"target":"rpi-arm64","variant":"base","kernel":"std","architecture":"arm64","boards":["raspberrypi4","raspberrypi5"],"hardware":["Raspberry Pi 4, 400 and CM4","Raspberry Pi 5 and CM5"],"file":"ironflockos-rpi-arm64-base-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-rpi-arm64-base-0.13.0.img.gz","size":639408901,"sha256":"9abd17f2098dfa236d440005222d0a6b583546ea9768e5eca8807c4e24ec88db"}]}

issued_at y key_id describen el catálogo, channels indica el release de cada canal, y from_cache es true cuando el servidor de descargas no respondió. Cada imagen tiene su file con su url, size y sha256. boards son los modelos de placa que indica un archivo .flock (board.model), y hardware son sus nombres. Una imagen de instalación tiene además payloads, los id de las imágenes que lleva.

Cuándo falla

• Código de salida 2 — --channel y --version juntos, una versión que no tiene forma de versión, o un canal, release, target, variante o kernel que el catálogo no tiene. El error indica lo que tiene el catálogo.
• Código de salida 1 — el catálogo no se verifica, ocupa más de 64 KiB, no es uno que este ironflock pueda leer o es más antiguo que la copia guardada; o no se puede obtener y no hay ninguna copia guardada.

ironflock os drives

Lista las unidades de esta máquina en las que se puede escribir una imagen de IronFlockOS: memorias USB, tarjetas SD, discos externos. No escribe, no desmonta ni abre ninguna unidad.

ironflock os drives [flags]

Se ejecuta en Linux y macOS. No necesita root. No pregunta nada. En Linux ejecuta lsblk (de util-linux) y lee /proc y /sys. En macOS ejecuta diskutil list, diskutil info y hdiutil info.

Flags

Los flags que aceptan todos los comandos están en Flags, salida y códigos de salida.

Qué unidades se rechazan

os flash rechaza las unidades que rechaza os drives, por los mismos motivos. Una unidad se rechaza cuando (se muestra el primer motivo que se aplica):

1. es una partición, como /dev/sdb1. El rechazo indica su disco: una imagen va al disco entero.
2. no es un disco: una unidad óptica, un disco en memoria (zram), un volumen construido sobre otras unidades (LVM, dm-crypt, RAID, device-mapper; en macOS, un contenedor APFS, un conjunto AppleRAID u otro disco sintetizado), o un tipo de dispositivo que el comando no conoce (nbd, mtdblock).
3. contiene parte del sistema en ejecución: /, /boot, /efi, /usr, /var, /etc o un montaje dentro de uno de ellos (la partición EFI en /boot/efi, los datos de Docker en /var/lib/docker), /home, /opt, /srv, /data, swap, o el soporte de un sistema live. Esto vale sea cual sea la forma en que el sistema está en la unidad: en una partición, a través de LVM, dm-crypt, RAID o device-mapper, en un sistema de archivos btrfs repartido en varias unidades, en un pool ZFS, en un overlay, o en un archivo que lee un dispositivo loop. En macOS: / y los volúmenes dentro de /System, a través de sus contenedores APFS hasta el disco que los contiene.
4. está en uso: por LVM, dm-crypt, RAID o device-mapper, por un pool ZFS con un dataset montado, o por un dispositivo loop que lee un archivo que hay en ella. En macOS, también por un contenedor APFS que hay en ella, un conjunto AppleRAID, una imagen de disco cuyo archivo está en ella, o por Core Storage, AppleRAID o un contenedor APFS que no está conectado. macOS solo libera una memoria USB con un contenedor APFS cuando se borra la memoria, así que el motivo indica el comando que la borra, por ejemplo diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (o Borrar en Utilidad de Discos).
5. es un disco interno de la máquina: un disco SATA o NVMe, la eMMC de una placa. Una unidad es interna salvo que esté conectada por USB o por otro bus cuyos dispositivos se puedan desenchufar. Un lector de tarjetas integrado es interno, pero su tarjeta SD es un soporte extraíble y se ofrece, también en un Mac. En macOS, un disco que no indica dónde está cuenta como interno. os flash --allow-internal escribe un disco interno que indica --drive, cuando ningún otro motivo lo rechaza.
6. puede contener parte del sistema en ejecución: cuando una parte del sistema en ejecución no se puede rastrear hasta una unidad, se rechazan todas las unidades. Es el caso en un contenedor, cuyo sistema está en su host, y en macOS para un sistema en un volumen que no llega a ningún disco físico, como Core Storage.
7. es de solo lectura, como una tarjeta SD bloqueada.
8. no tiene soporte, como un lector de tarjetas sin tarjeta.

Una unidad con sistemas de archivos montados se ofrece; mounted los enumera, y os flash los desmonta antes de escribir. Los dispositivos loop y, en macOS, las imágenes de disco conectadas no se listan, pero os flash escribe uno que indique --drive.

En un dispositivo que ejecuta IronFlockOS, el comando advierte en stderr y en warnings: todas las imágenes de IronFlockOS de un target tienen los mismos UUID de partición, así que, mientras haya conectada una segunda unidad de IronFlockOS, el sistema en ejecución no puede distinguir sus propias particiones de las de la unidad.

Ejemplos

# Las unidades en las que se puede escribir
ironflock os drives
# Todas las unidades, con el motivo de cada una rechazada
ironflock os drives --all
# Las unidades como JSON
ironflock os drives --json

Resultado

En Linux:

DEVICE        SIZE     BUS  MODEL
/dev/sdb      15.9 GB  usb  SanDisk Ultra
/dev/mmcblk0  31.9 GB  mmc  SD32G

Con --all:

DEVICE        SIZE     BUS   MODEL                    WRITABLE
/dev/sda      2.0 TB   sata  WDC WD20EZBX-00AYRA0     no: is an internal disk of this machine
/dev/sdb      15.9 GB  usb   SanDisk Ultra            yes
/dev/mmcblk0  31.9 GB  mmc   SD32G                    yes
/dev/nvme0n1  1.0 TB   nvme  Samsung SSD 980 PRO 1TB  no: holds / of the running system

En un Mac, con --all:

DEVICE      SIZE      BUS             MODEL                 WRITABLE
/dev/disk0  500.3 GB  Apple Fabric    APPLE SSD AP0512R     no: holds / of the running system
/dev/disk1  524.3 MB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk2  5.4 GB    Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk3  494.4 GB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk5  15.9 GB   Secure Digital  Built In SDXC Reader  yes

Con --json (abreviado):

{"drives":[{"device":"/dev/sdb","kind":"disk","size":15931539456,"bus":"usb","removable":true,"internal":false,"read_only":false,"vendor":"SanDisk","model":"Ultra","serial":"4C530001230812115352","mounted":[{"device":"/dev/sdb1","mountpoint":"/media/anna/STICK"}],"system":[],"maybe_system":[],"holders":[],"writable":true},{"device":"/dev/mmcblk0",...}],"warnings":[]}

Cuando no hay ninguna unidad en la que escribir, el texto lo indica, drives está vacío y el código de salida es 0.

Cuándo falla

• Código de salida 3 — en Linux, lsblk no está instalado; o el comando se ejecuta en un sistema que no es Linux ni macOS.

ironflock os flash

Escribe IronFlockOS en una unidad (una memoria USB, una tarjeta SD, un disco externo) y pone el archivo .flock del dispositivo en la partición IRONFLOCKOS de la unidad, la partición FAT32 con ese nombre que tiene toda unidad de IronFlockOS. El dispositivo se inscribe con ese archivo en su primer arranque. Con --output, escribe lo mismo en un archivo de imagen de disco para una máquina virtual.

Advertencia: Se borra todo lo que hay en la unidad. Comprueba el nombre de la unidad con ironflock os drives antes de escribir. os flash nunca elige una unidad por sí mismo.

ironflock os flash -c <device.flock> (-d <drive> | --output <file>) [flags]

Sin root, el error indica la línea de comandos que hay que escribir, con sudo delante. En macOS, un usuario que puede escribir en el dispositivo raw de la unidad no necesita root: el usuario que conectó una imagen de disco, o un usuario al que el propietario de la máquina dio la unidad, por ejemplo con sudo chown <user> /dev/disk4 /dev/rdisk4. Con --output, el comando no necesita root. Consulta también Privilegios de root.

Flags

Los flags que aceptan todos los comandos están en Flags, salida y códigos de salida.

Qué hace

1. Comprueba la unidad. Resuelve --drive y la rechaza por los motivos que da os drives, antes de leer, obtener o preguntar nada. Sin --drive (y sin --output), indica las unidades en las que puede escribir y termina con el código de salida 2.
2. Lee el archivo .flock. Tiene que ser un archivo con nombre *.flock de 5 MiB como máximo, un objeto JSON con un secret y una device_key, cuyos name y serial_number sean nombres simples.
3. Elige la imagen del catálogo firmado, que obtiene y verifica como hace os images. Toma la imagen que indica --image o, si no, la imagen por defecto (variante base, kernel estándar) del hardware que indica el archivo .flock: su board.model o, si no, su architecture cuando el catálogo tiene un único hardware para ella. Con --installer, toma la memoria USB de instalación de ese hardware que lleva la imagen.
4. Muestra el plan en stderr: la imagen, de dónde viene su archivo, el archivo .flock (por su nombre), el WiFi, la unidad y los sistemas de archivos de la unidad que desmonta. Después pregunta. «No» está preseleccionado, así que Enter solo no borra nada.
5. Obtiene el archivo de imagen: el archivo de --image-file o, si no, la copia de la caché o, si no, una descarga a la caché, que se reanuda donde se detuvo una descarga anterior. Como root, la caché es /var/cache/ironflock/images en Linux y /var/root/Library/Caches/ironflock/images en macOS. La descarga va a un archivo .part. Cada archivo solo se escribe cuando su tamaño y su SHA-256 son los del catálogo. Un intento de descarga que no trae ningún byte en un minuto termina, y la descarga desiste tras tres intentos así seguidos.
6. Vuelve a comprobar la unidad. Tiene que ser la unidad que mostró el plan y seguir sin estar rechazada: el mismo dispositivo, tamaño, número de serie y soporte. En Linux eso incluye el fabricante, el modelo, el bus y cada partición con su sistema de archivos, etiqueta, UUID y tamaño. En macOS, que no indica número de serie, son el modelo, el bus, la posición en el árbol de dispositivos y las particiones con sus UUID. Una memoria USB que se retiró después del plan deja su nombre a la siguiente unidad que se conecte; esa unidad no se escribe, y no se desmonta nada. Después, el comando desmonta los sistemas de archivos que enumeró el plan, y solo esos, y abre la unidad en exclusiva para escribir. En macOS escribe a través del dispositivo raw (/dev/rdisk4), que un segundo os flash no puede abrir a la vez.
7. Escribe la imagen, después relee la unidad y la compara.
8. Escribe el archivo .flock en la carpeta raíz de la partición IRONFLOCKOS, sin montarla. Una memoria USB de instalación recibe además installer.conf. Con --wifi-ssid, la copia de la unidad indica esa red; el propio archivo .flock no cambia.
9. En macOS, expulsa la unidad (diskutil eject) para que puedas sacarla. Cuando la expulsión falla, la unidad queda escrita igualmente: el comando advierte, y tú expulsas la unidad en el Finder antes de sacarla.

Como root, el comando solo usa una carpeta de caché cuando es una carpeta y no un enlace, pertenece a root y nadie más puede escribir en ella. Crea una que falte con el modo 0700 y se detiene ante cualquier otra antes de leer, borrar o descargar nada allí. Antes de obtener una imagen del catálogo, borra los archivos de imagen de la caché que el catálogo ya no lista, y sus descargas parciales.

Un --image para un hardware distinto del que indica el archivo .flock se escribe tras una advertencia en el plan: el dispositivo no ejecutaría sus apps. En un dispositivo que ejecuta IronFlockOS, el plan advierte como lo hace os drives. Con --allow-internal, el plan advierte de que la unidad es un disco interno.

--yes responde sí a la pregunta. Sin terminal (una tubería, un script) y sin --yes, el comando no pregunta y termina con el código de salida 4. --json tampoco pregunta nada, así que necesita --yes para escribir una unidad. Con --json, el plan no se imprime: stderr lleva solo los eventos de progreso, y las advertencias están en el resultado. Consulta Preguntas y confirmación y Salida y JSON.

WiFi

El dispositivo se une al WiFi que indica su archivo .flock. --wifi-ssid le da otra red. IronFlockOS solo se une a un WiFi con frase de contraseña, así que --wifi-ssid y --wifi-password-file van siempre juntos. La frase de contraseña viene de un archivo o de una tubería, nunca de la línea de comandos, donde ps y el historial del shell la mostrarían. El comando no la imprime en ninguna parte. La copia del archivo .flock en la unidad indica la red en wlanssid y password.

Nota: Cuando la frase de contraseña llega por /dev/stdin, stdin no es una terminal, así que el comando no puede preguntar. Añade --yes.

Memoria USB de instalación

Con --installer, la unidad pasa a ser una memoria USB de instalación para un PC con UEFI (amd64-efi, arm64-efi); ironflock os images --variant installer lista las imágenes de instalación. La memoria lleva varias imágenes de su hardware; installer.conf en la memoria indica la que instala (payload, la imagen elegida como en el paso 3) y contiene los flags --installer-* que indicaste. Cuando el PC arranca desde la memoria, el instalador:

1. elige el disco según --installer-disk: el disco más grande (por defecto), el disco /dev/<name> o el disco con el id by-id:<id>. Solo escribe un disco USB con --installer-allow-usb yes.
2. pregunta en la consola del PC antes de escribir, salvo con --installer-confirm no.
3. escribe la imagen y el archivo .flock del dispositivo en ese disco.
4. apaga el PC (por defecto), o lo reinicia con --installer-after reboot.

Saca la memoria y arranca el PC desde su disco interno. El dispositivo se inscribe en su primer arranque.

Advertencia: Una memoria escrita con --installer-confirm no borra el disco de cada PC que arranca desde ella, sin preguntar. Etiqueta una memoria así y mantenla lejos de otras máquinas.

Para reemplazar el Linux de una máquina en funcionamiento sin memoria USB, consulta Reemplazar Linux por IronFlockOS.

Un archivo de imagen descargado

--image-file escribe un archivo de imagen que descargaste antes, por ejemplo en una máquina que no puede descargar los archivos de imagen del catálogo. Toma la dirección del archivo del url de os images --json. El archivo solo se escribe cuando tiene el tamaño y el SHA-256 que el catálogo indica para la imagen.

El comando sigue necesitando el catálogo firmado para comprobar el archivo. Obtiene el catálogo o, cuando no se puede alcanzar el servidor de descargas, usa la copia que guardó la última vez que se verificó un catálogo de la misma base de descarga. Esa copia es por usuario: como root, es la copia de root. Un servidor propio también funciona: con otra base de descarga (--download-base o IRONFLOCK_DL_BASE), el comando obtiene el catálogo de <download base>/ironflockos/manifest.json y el archivo de imagen de <download base>/ironflockos/<version>/<file>.

Nota: El archivo se lee una vez más mientras se escribe, y su SHA-256 solo se vuelve a conocer después de la escritura. Guarda el archivo donde ningún otro usuario pueda cambiarlo.

Un archivo de imagen para una máquina virtual

--output <file> escribe la imagen y los archivos del dispositivo en un archivo normal en lugar de en una unidad: una imagen de disco raw desde la que arranca una máquina virtual como su disco. La imagen, sus comprobaciones y los archivos de IRONFLOCKOS son los mismos que para una unidad. No se busca, desmonta ni abre ninguna unidad, así que el comando no necesita root. --image, --image-file, --installer con sus flags y --wifi-ssid funcionan como con una unidad.

• Tamaño — El plan indica el archivo y su tamaño: el tamaño de la imagen descomprimida. Cuando la imagen aún está por descargar, esa línea sigue a la descarga.
• Pregunta — Un archivo nuevo no borra nada, y el comando no pregunta. Un archivo que ya existe se reemplaza: el plan lo dice, y el comando pregunta antes.
• Primero con otro nombre — La imagen va a un archivo nuevo en la misma carpeta, <file>.<number>.part. Recibe el nombre <file> solo cuando contiene la imagen entera, se ha releído y tiene los archivos del dispositivo en su partición IRONFLOCKOS. Una escritura que falla o se interrumpe elimina el archivo .part, y con ese nombre no hay nada, o está el archivo que había, sin cambios. Un kill -9 o un corte de corriente pueden dejar el archivo .part.
• Privado — El archivo contiene el secreto del dispositivo, igual que el archivo .flock. Recibe el modo 0600, también cuando reemplaza un archivo con un modo más amplio.
• Disperso — Donde la imagen tiene un bloque entero de ceros (bloques de 4 MiB), el archivo recibe un hueco en un sistema de archivos que admite huecos. Se lee igual y ocupa menos espacio.

# Escribir un archivo de imagen de disco para una máquina virtual, sin root
ironflock os flash -c device.flock --output device.img

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Output:       device.img, a new file: the image, unpacked; its size is known once the image is downloaded
(the progress of downloading, checking)
Unpacked, the image has 4.6 GB: the size of device.img.
(the progress of writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is in device.img and read back, with device.flock in its IRONFLOCKOS partition.
Grow the file to the size of the virtual machine's disk before the machine starts from it (truncate -s 20G device.img): on its first boot IronFlockOS makes slot B and /data in that space, and the device enrolls as kitchen-pc.

La imagen contiene la partición IRONFLOCKOS y el primero de los dos slots del sistema que IronFlockOS actualiza por turnos (el slot A). En su primer arranque, IronFlockOS crea el slot B, del mismo tamaño que el slot A, y la partición de datos /data en el resto del disco. Amplía el archivo antes de que la máquina virtual arranque desde él por primera vez: como mínimo a 10 GiB para base y a 18 GiB para nvidia. Lo que gana el archivo son ceros, que el sistema de archivos guarda como un hueco. Un hipervisor que acepta discos raw usa el archivo tal cual. Para otro formato, convierte el archivo ampliado, por ejemplo con qemu-img convert -f raw -O qcow2 device.img device.qcow2.

Las imágenes de amd64-efi y arm64-efi arrancan en QEMU; la imagen de la Raspberry Pi (rpi-arm64), no. Para amd64-efi en Linux con KVM y el firmware UEFI del paquete ovmf (Debian, Ubuntu):

# Ampliar el archivo, copiar las variables del firmware e iniciar la máquina
truncate -s 20G device.img
cp /usr/share/OVMF/OVMF_VARS_4M.fd device-vars.fd
qemu-system-x86_64 -machine q35 -accel kvm -cpu host -m 2048 -smp 2 \
  -drive if=pflash,format=raw,unit=0,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,unit=1,file=device-vars.fd \
  -drive file=device.img,format=raw,if=virtio \
  -netdev user,id=net0 -device virtio-net-pci,netdev=net0 \
  -device i6300esb \
  -nographic

• -nographic pone el primer puerto serie en la terminal, donde escriben GRUB y el kernel. Ctrl-A X termina QEMU.
• -device i6300esb es un watchdog, mediante el cual IronFlockOS reinicia una máquina que se cuelga.
• -netdev user da a la máquina la red del host, por la que el dispositivo alcanza IronFlock.
• Sin KVM (sin /dev/kvm, o en un host de otra arquitectura), omite -accel kvm y usa -cpu max. QEMU emula entonces la máquina, lo que es mucho más lento.

La imagen arm64-efi arranca con qemu-system-aarch64 -machine virt y el firmware del paquete qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd y una copia de AAVMF_VARS.fd), sin el watchdog. En un Mac con Apple silicon, QEMU de Homebrew la arranca con -accel hvf -cpu host y el firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, con una copia de edk2-arm-vars.fd.

Ejemplos

# Escribir en una memoria USB la imagen por defecto para el hardware del archivo .flock
sudo ironflock os flash -c device.flock -d /dev/sdb
# Escribir una memoria USB de instalación que instala la imagen NVIDIA en un PC
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Escribir una tarjeta SD para un dispositivo que se une al WiFi «Workshop»
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Escribir una memoria USB en un Mac
sudo ironflock os flash -c device.flock -d /dev/disk4

Resultado

El plan y el progreso van a stderr; las últimas líneas son el resultado. En Linux:

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Drive:        /dev/sdb: SanDisk Ultra, 15.9 GB, usb, serial 4C530001230812115352
Everything on /dev/sdb is erased. Unmounted first: /media/anna/STICK.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is on /dev/sdb and read back, with device.flock in its IRONFLOCKOS partition.
Start the device from it: it enrolls as kitchen-pc on its first boot.

En un Mac, primero sin root y después con sudo:

$ ironflock os flash -c pi.flock -d /dev/disk5
Error: "ironflock os flash" must run as root (sudo) to write a drive: sudo ironflock os flash -c pi.flock -d /dev/disk5
$ sudo ironflock os flash -c pi.flock -d /dev/disk5 --yes
IronFlockOS catalog of 2026-11-10T16:41:54Z, signed with key 036ef3bd.
Image:        ironflockos-rpi-arm64-base 0.14.0, for Raspberry Pi 4, 400 and CM4
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.14.0/ironflockos-rpi-arm64-base-0.14.0.img.gz (640.1 MB), downloaded and checked against the catalog
Device file:  pi.flock, for the device pi-workshop
WiFi:         Office (from the .flock)
Drive:        /dev/disk5: Built In SDXC Reader, 15.9 GB, Secure Digital
Everything on /dev/disk5 is erased. Unmounted first: /Volumes/UNTITLED.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.14.0 (ironflockos-rpi-arm64-base) is on /dev/disk5 and read back, with pi.flock in its IRONFLOCKOS partition.
/dev/disk5 is ejected and can be taken out.
Start the device from it: it enrolls as pi-workshop on its first boot.

Con --json, aquí para una memoria USB de instalación (--installer --installer-confirm no --yes --json):

{"action":"flashed","device":"kitchen-pc","device_file":"device.flock","hardware":"x86-64 PC with UEFI","image":{"image_id":"ironflockos-amd64-efi-installer","version":"0.13.0","file":"ironflockos-amd64-efi-installer-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-installer-0.13.0.img.gz","size":2512345678,"sha256":"..."},"installer":{"payload":"ironflockos-amd64-efi-base","disk":"largest","confirm":"no","after":"poweroff","allow_usb":"no"},"wifi":{"ssid":"Office","from":"flock"},"drive":{"device":"/dev/sdb","size":15931539456,"bus":"usb","model":"SanDisk Ultra","serial":"4C530001230812115352","internal":false},"source":"download","unmounted":["/media/anna/STICK"],"bytes":6442450944,"verified":true,"ejected":false,"files":["device.flock","installer.conf"],"catalog":{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"notes":[]},"warnings":[]}

Con --output, el resultado tiene output en lugar de drive, por ejemplo "output":{"file":"/home/anna/device.img","replaced":true}.

Cuándo se niega

Código de salida 3, y no se escribe nada:

• La unidad es una que rechaza os drives; el error da el motivo, y --yes no cambia nada. La única excepción es un disco interno de esta máquina: --allow-internal lo escribe cuando --drive lo indica, y el error nombra el flag cuando este haría que se pudiera escribir la unidad. El flag no levanta ningún otro rechazo y no responde a la pregunta.
• La unidad cambió entre el plan y la escritura, o en ese momento se rechaza. El error dice qué cambió.
• La unidad está en uso cuando se abre: hay montado un sistema de archivos que el plan no enumeró, un sistema de archivos no se desmonta o un programa tiene la unidad abierta.
• El comando no se ejecuta como root (o, en macOS, como un usuario que puede escribir en el dispositivo raw de la unidad). El error indica la línea de comandos con sudo.
• Con --output: el nombre no es un archivo normal (un dispositivo, una carpeta, una tubería con nombre o cualquier enlace simbólico), o su carpeta no existe, antes de que se lea u obtenga nada. Una carpeta que no admite un archivo nuevo (sin permiso, un sistema de archivos de solo lectura) se rechaza después del plan y antes de la descarga. Un archivo que tomó el nombre mientras se escribía la imagen, donde el plan indicaba un archivo nuevo, no se reemplaza.

Código de salida 2, una línea de comandos incorrecta:

• Ni --drive ni --output, también con --allow-internal. --output con --drive o con --allow-internal, sin nombre o con -. Un --output que indica el archivo .flock de -c o el archivo de --image-file.
• Un flag --installer-* sin --installer, o con un valor que el instalador no acepta.
• --wifi-ssid sin --wifi-password-file, o al revés.
• Un archivo .flock que no dice para qué hardware es; en ese caso, --image elige la imagen.
• Una imagen que el catálogo no tiene, una memoria USB de instalación que no lleva la imagen, o un hardware sin memoria USB de instalación.
• Con --host: --image-file y --output, porque --host no copia el archivo de imagen a la otra máquina ni trae ningún archivo de vuelta. Ejecuta el comando aquí sin --host, o en la propia máquina. El archivo .flock y el archivo de frase de contraseña sí se envían.

Código de salida 4: se respondió no a la pregunta (Enter solo o Esc), o no se pudo hacer y no se indicó --yes.

Código de salida 1, el comando falló:

• El archivo .flock o el archivo de frase de contraseña no son válidos, o el archivo de imagen no es el del catálogo.
• El catálogo no se puede usar, por los motivos por los que falla os images.
• Falla la descarga, la escritura o la relectura. Una escritura que falla después de su primer bloque (un error de E/S, una unidad más pequeña que la imagen) indica que la unidad contiene ahora una parte de la imagen, con la que no arranca nada: vuelve a escribirla.
• La imagen está en la unidad y releída, pero el archivo .flock no se pudo escribir en IRONFLOCKOS. Sin él, el dispositivo no se inscribe; el mismo comando vuelve a escribir ambos.
• Con --output: el sistema de archivos está lleno, los archivos del dispositivo no se pueden poner en la imagen, o la entrada del archivo .part se reemplazó mientras se escribía la imagen. El nombre queda entonces como estaba antes.

Código de salida 130: Ctrl-C mientras se descarga, se escribe o se relee la imagen. Una descarga interrumpida no ha escrito nada, y el mismo comando la reanuda. Una escritura o una relectura se detiene en el siguiente bloque, y el error dice qué contiene la unidad. Una vez releído el último bloque, el comando completa sus últimos pasos breves y termina con 0. Un segundo Ctrl-C termina el comando de inmediato; con --output puede quedar el archivo .part.