Docker macvlan can work on ZimaOS, and the February 2026 thread includes a user-verified Portainer setup plus a successful sudo docker network create example. The main trap is that macvlan behaves differently from a normal Docker bridge: containers get LAN-like addresses, but the Linux host cannot talk to those containers directly by default.
That host-isolation behavior is not a ZimaOS bug. It is a documented macvlan property in Docker and the Linux networking model.
What the Community Verified
The original user first had trouble creating macvlan through Portainer stacks. Another user created it from SSH, after which it appeared in the ZimaOS custom-app network dropdown. The original poster then reported success after creating a Portainer macvlan configuration first and the actual macvlan network second.
A later user also confirmed that direct Docker CLI creation required sudo because the regular ZimaOS account could not access the Docker socket.
Build the Network Around the Real LAN
Choose the correct physical parent interface, subnet, gateway and a safe IP range that does not overlap DHCP leases you want the router to assign. Do not copy eth0 or 192.168.0.0/24 from a forum example unless they match your server.
The current Docker macvlan guide also warns that the network hardware must tolerate multiple MAC addresses and that macvlan is Linux-only.
Understand Host-to-Container Isolation
Docker explicitly documents that a macvlan container cannot communicate directly with its host because of a Linux-kernel restriction. That means a service can work perfectly for other LAN clients while still being unreachable from the ZimaOS host itself.
If host access is required, Docker suggests either giving the container an additional bridge network or creating a macvlan interface on the host with an address in the same subnet. Treat the latter as advanced network configuration and document it so a reboot or interface rename does not silently break access.
Keep Portainer and ZimaOS From Recreating the Same Network
Create one owner for the network. If Portainer manages it, reference the existing external network from application stacks instead of asking every stack to recreate it. If you create it with Docker CLI, confirm ZimaOS apps reference the exact existing network name.
The Docker routing guide and network segmentation guide cover the adjacent routing and firewall issues.
Bottom Line
macvlan is usable on ZimaOS when it is created with the correct parent interface and privileges, but success is not just “the container has an IP.” Verify LAN access, host access requirements, reboot persistence, DHCP separation and one clear network owner before moving important services onto it.
