Networking

Yeet/catch can place services into different network modes. The mode is selected with --net on run or stage.

• host (default): no network namespace, service uses the host network.
• ts: Tailscale netns for the service.
• svc: per-service virtual IP on an internal subnet.
• lan: macvlan on the host LAN.

Modes are comma-separated:

yeet run <svc> ./compose.yml --net=svc,ts

For image, Dockerfile, Python, and TypeScript payloads, publish host ports with yeet run -p HOST:CONTAINER <svc> <payload>. Yeet stores the desired mappings in yeet.toml and catch records them with the service.

Use yeet service set <svc> -p HOST:CONTAINER to change published ports after deployment. The service set publish list is complete: include existing mappings you want to keep, or pass --publish-reset to replace or clear the list intentionally.

yeet service set web -p 80:80 -p 443:443
yeet service set web --publish-reset -p 443:443
yeet service set web --publish-reset

yeet info <svc> shows published ports in plain output, and JSON formats expose structured network.ports data.

--net=ts adds a Tailscale interface to the service netns, giving the service its own tailnet IP. Use yeet tailscale (alias: yeet ts) to run Tailscale commands for that service.

See the Tailscale page for setup, flags, and Serve examples.

svc assigns a stable private IP from an internal range (192.168.100.0/24).

• Use yeet ip <svc> to view it.
• This is useful for service-to-service traffic or when combined with Tailscale.
• On modern Debian and Ubuntu hosts, yeet prefers native nft for the host forwarding and masquerade rules that support svc.
• If nft is not available, yeet falls back to iptables-nft.
• iptables-legacy is supported as a compatibility fallback only.
• Yeet owns its own firewall objects for this path (table ip yeet for nft, or YEET_FORWARD / YEET_POSTROUTING chains for iptables backends) instead of appending anonymous one-off rules directly into the host ruleset.
• Inside each service netns, yeet also owns the DNAT chains used for published compose ports (YEET_PREROUTING and YEET_OUTPUT) and now reconciles them from the current docker endpoint state so stale sidecar-targeting rules are removed automatically during container churn.
• If a named service netns is recreated, catch now detects the stale docker endpoint wiring for that service and recreates the whole compose project so it rejoins the current netns cleanly.
• catch also performs this reconciliation pass at startup for netns-backed docker services and logs when it recreates a service for this reason.

You can inspect the current host-side firewall state with:

sudo nft list table ip yeet
sudo iptables-nft -S YEET_FORWARD
sudo iptables-nft -t nat -S YEET_POSTROUTING

If the host is on legacy compatibility mode, use iptables-legacy in place of iptables-nft.

For experimental VMs, svc is the default network mode. The guest gets a private IP on the service network. yeet ssh <svc> uses that address and proxies through the yeet host, so the guest does not need to be directly reachable from your laptop. The generated guest network config includes DNS for the service network.

lan uses macvlan to attach the service to the LAN.

• Default parent interface is the host default route from the catch host namespace.
• Override with --macvlan-parent.
• Optional --macvlan-vlan and --macvlan-mac.

For experimental VMs, lan attaches a TAP device to a host bridge so the guest can request a LAN address with DHCP. In v0, non-bridge LAN parents are rejected; pass a bridge interface with --macvlan-parent when the default route interface is not itself a bridge. VM networking supports svc, lan, or both in v0; Tailscale mode is not available for VMs yet.

mount and umount manage network mounts for a service.

yeet mount <svc> host:/export /mnt/data --type=nfs --opts=defaults
yeet umount <svc> /mnt/data

Mount flags:

• --type (default nfs)
• --opts (default defaults)
• --deps (list of systemd dependencies)