FLAKE-CTL-FIRECRACKER-NETWORK-ADD(8)

🌸 NAME 🌸

okay bestie, this is the manual for FLAKE-CTL-FIRECRACKER-NETWORK-ADD(8). and yes, the first NAME block in the source is literally just the title with a dash, so I'm not gonna pretend it's deeper than that:

FLAKE-CTL-FIRECRACKER-NETWORK-ADD(8) -

💖 NAME 💖

flake-ctl firecracker network add — connect a VM application to the host network. that's the whole vibe. 🫶

✨ SYNOPSIS ✨

the shape of it is giving:

          USAGE:
              flake-ctl firecracker network add [OPTIONS] --app <APP>

          OPTIONS:
              --app <APP>
              --instance <INSTANCE>
              --help

🦋 DESCRIPTION 🦋

okay so this command connects the given firecracker flake application to the network of the host. the flake configuration of the application is looked up from the given application path and receives a static network setup. the TAP device the application expects is created and routed to the outgoing interface of the host. no cap. ✨

the command performs the following steps:

1. write the network setup to the flake configuration — the kernel commandline of the VM is extended by the options which configure its network:

boot_args:
  - ip=172.16.0.2::172.16.0.1:255.255.255.0::eth0:off
  - rd.route=172.16.0.1/24::eth0
  - nameserver=8.8.8.8

Gateway, netmask and name server are not configurable, they describe the private network between the host and the VMs and are compiled into the command. the address is a free address of that network, see ADDRESSES below. 💅

2. create the TAP device of the application:

sudo ip tuntap add tap-<APP> mode tap

3. connect the TAP device to the outgoing interface:

sudo ip addr add 172.16.0.1/24 dev tap-<APP>
sudo ip link set tap-<APP> up
sudo iptables -A FORWARD -i tap-<APP> -o <OUTGOING> -j ACCEPT

4. route the address of the application to its TAP device:

sudo ip route add 172.16.0.2/32 dev tap-<APP>

every TAP device provides the same gateway address and thus the same route to the private network. without a host route for the address of the application the traffic to it would be sent to the device that route points to, which is not necessarily the device the application is connected to. fr fr. 🧚

as the setup changes the network configuration of the host, the commands are called through sudo. the calling user therefore needs the permission to run them as root. 👑

the outgoing interface is the one the host setup was created for with ** flake-ctl-firecracker-network-init**(8). if there is no record of it, e.g because the host setup was created manually, the interface of the default route is used. 🦋

⚠️ the source has a docs build warning right here: System Message: WARNING/2 (./flake-ctl-firecracker-network-add.rst:, line 80) — Inline strong start-string without end-string. The steps only take effect if the host is prepared for NAT networking. Please run flake-ctl firecracker network init first. A device, address, route or rule which is already present is not created again. This allows to call the command more than once, e.g to create the setup again after a reboot of the host. Only the flake configuration is persistent, the setup on the host is not. Please note, the network setup of a VM also requires an initrd which provides support for systemd-(networkd, resolved) and which was created by dracut such that the boot_args become effective. See the Firecracker Networking section of the flake-pilot README for the complete picture.

🌈 INSTANCES 🌈

a TAP device cannot be shared across VM instances. therefore every instance of an application, created by calling it with the @NAME selector, needs its own address and its own TAP device. called with the --instance option the command creates the setup for that instance:

• the address is written to the instance section of the flake configuration, keyed by the selector. it takes the place of the global ip= setting when the application is called with that selector. 🎀
• the TAP device is named after the application and the selector, e.g tap-claude_id1 for claude @id1. 💅

🍓 ADDRESSES 🍓

the address handed out to an application is the lowest free address of the 172.16.0.0/24 network. an address which is already used by another flake registration is never handed out twice, and an application which is already configured keeps the address it has. periodt. ✨

only registrations which can be read take part in this. in user mode these are the registrations of the calling user and the system wide ones. iykyk. 🫶

💜 OPTIONS 💜

• --app <APP> — absolute path of the application on the host. the application has to be registered as a VM application, see ** flake-ctl-firecracker-register**(8).

⚠️ another docs warning from the source: System Message: WARNING/2 (./flake-ctl-firecracker-network-add.rst:, line 135) — Inline strong start-string without end-string.

• --instance <INSTANCE> — the @NAME instance selector the application is called with. for convenience the plain name without the @ prefix is accepted as well. 🌸

also, the synopsis lists --help; the detailed OPTIONS section in the source doesn't give it a blurb, so i'm not inventing one. no cap. 🫡

🎀 FILES 🎀

• /usr/share/flakes
• $HOME/.config/flakes
• /etc/flakes/network.yaml
• $HOME/.config/flakes/network.yaml

🔥 EXAMPLE 🔥

$ flake-ctl firecracker network add --app $HOME/bin/claude

$ flake-ctl firecracker network add --app $HOME/bin/claude --instance @id1

🌟 SEE ALSO 🌟

• flake-ctl-firecracker-network-init(8)
• flake-ctl-firecracker-network-remove(8)
• flake-ctl-firecracker-register(8)
• firecracker-pilot(8)

👑 AUTHOR 👑

Marcus Schäfer

💖 COPYRIGHT 💖

c. 2026, Marcus Schäfer

okay that's the tea ☕ — the footer/source-version line is FLAKE-CTL-FIRECRACKER-NETWORK-ADD(8)() and the date slot is empty, so there's literally no date to spill. bye bestie, go route those VMs 💅✨🌈