Sub-devices — share one prefix across many machines

You bought a /124 (16 IPv6 addresses), but the addresses route to one device. Sub-devices let you run wayangi on a second, third, or 16th machine — each one auto-claims one of your existing addresses, same install UX, no extra subscription.

Last updated 2026-05-22 · 4 min read

Why sub-devices exist

A /124 prefix carries 16 distinct public IPv6 addresses. The standard wayangi setup routes the whole /124 to one physical device, which can then bind any of those 16 addresses locally (Linux supports this via AnyIP routes — see the prefix-delegation guide). That's powerful when all your services are on one host.

It's awkward when the addresses live on different physical machines:

• One /128 on your VPS, hosting a Mastodon node.
• Another /128 on your home server, hosting Nextcloud.
• Another on a Raspberry Pi running a backup target.

Without sub-devices you'd buy three separate /128 plans (3 × $5/mo). With sub-devices you buy one /124 ($10/mo gets you 16 IPs) and provision the three machines as sub-devices under it — each auto-allocates one /128 from the prefix, runs the standard binary, gets its own tunnel.

How it works under the hood

parent device  /124 routed to its tunnel
└── 2001:df6:d2c0:1400::10/124  →  parent's WireGuard peer
    ├── ::10  (parent's anchor — keeps this one)
    ├── ::11  (sub-device "web-server")  →  sub-1's tunnel
    ├── ::12  (sub-device "db-replica")  →  sub-2's tunnel
    └── ::13..::1f  (unused — claim later via "+ Add sub-device")

The hub's WireGuard config has the parent's /124 as AllowedIPs, and each sub's /128 as its own AllowedIPs on a separate peer. WireGuard does longest-prefix match, so the /128 wins for that specific address — traffic for ::11 goes to the sub, traffic for ::13 (unclaimed) still goes to the parent.

Adding your first sub-device

1. Open the parent device

   From your dashboard, click the parent device row. The detail page opens.

2. Scroll to the Sub-devices panel

   The panel is visible only when the parent has an active paid prefix smaller than /128 (i.e. /124, /120, /116, /112, /104, /96, /64). Free-tier devices and single-IP /128 devices don't host sub-devices.

3. Name it and click + Add sub-device

   Pick something memorable — db-replica, backup-pi, vps-mastodon. The next page shows the sub-device's token. Copy it now; it's shown once.

4. Install + run on the target machine

   Standard wayangi install — there's nothing sub-device-specific in the binary, the hub does all the routing magic:

   curl -fsSL https://wayangi.dalang.io/install.sh | sh
   wayangi --token=<sub-token>

   The agent bootstraps, gets assigned the next free /128 from the parent's prefix, and brings up its WireGuard tunnel. You'll see it online (green dot) in the parent's Sub-devices panel within a minute.

Caps + math

The UI hard-caps sub-device count at 1024 per parent regardless of prefix size — purely to keep the management panel rendering quickly. If you need more, email [email protected].

Billing + lifecycle

• Sub-devices are free. They're claims on addresses the parent already paid for. No per-sub charge.
• A sub-device's status inherits the parent's. If the parent's subscription goes past_due, the sub's tunnel also stops (the bootstrap returns 402).
• Deleting the parent deletes every sub-device under it (foreign-key CASCADE). The prefix returns to the global pool.
• Deleting one sub-device frees its offset. The next sub you add reuses the lowest free offset under that parent.
• You can rotate a sub-device's token independently from the sub's own detail page.

Common gotchas

The Sub-devices panel doesn't show up on my device page

It's only visible when the parent has a paid prefix smaller than /128 AND the subscription is active. Free-tier and single-IP /128 devices have no room to subdivide.

Can a sub-device have its own sub-devices?

No — wayangi only supports one level of nesting. Sub-devices are always /128s. If you need a tree, buy a larger prefix (a /120 hosts 255 sub-devices in one flat layer).

My sub-device shows offline forever

Same checklist as a top-level device: agent installed and running? Outbound UDP/443 open? Token typed correctly? Run wayangi start in a terminal to see the bootstrap error.

The parent's traffic dropped when I added a sub-device

Only for the one specific /128 the sub claimed. The other 15 addresses in a /124 still route to the parent. If you were running a service bound to all addresses on the parent, that one /128 now belongs to the sub — rebind to a different offset, or move the service to the sub-device.

FAQ

What is a sub-device?

A child wayangi device that shares one /128 from its parent's IPv6 prefix. The parent buys the prefix; sub-devices each claim one of those addresses on a separate physical machine.

Do sub-devices cost extra?

No. Sub-devices are billed under the parent's subscription — if you already pay for a /124, you can add up to 15 sub-devices at no additional cost.

Why not just bind multiple IPs on one machine?

You can — Linux supports this via AnyIP local routes and wayangi sets that up by default on the parent device. Sub-devices are for the case where the addresses live on different physical machines.

Next up

• Bind all your prefix addresses on one machine — the inverse use case: one device, many IPs.
• Test your tunnel end-to-end — verify each sub-device is actually reachable from the open internet.
• Open the dashboard — manage the parent device, add your first sub.