• English

      • Connect Vibelet with Tailcat Direct

      Tailcat gives Vibelet an end-to-end WireGuard-encrypted path between the computer and phone without joining a tailnet. It is an optional Vibelet transport that requires no Tailscale account, root/admin access, inbound public port, or changes to the system VPN, DNS, and routing table.

      Tailcat first rendezvous through DERP and then attempts NAT traversal. It upgrades to a direct peer-to-peer UDP path when that succeeds and can remain on the encrypted DERP relay when it does not. “Tailcat Direct” therefore means that Vibelet prefers and attempts P2P; it cannot guarantee a direct path through every NAT and firewall.

      1. Enable Tailcat

      Run this on the computer that hosts the Vibelet daemon:

      npx vibelet --tailcat

      Vibelet automatically:

      1. Installs or updates the Vibelet daemon and its embedded Tailcat sidecar.
      2. Starts the Tailcat connection endpoint.
      3. Adds the Tailcat capability to the newly printed pairing QR code.

      You do not need to install Tailcat or the Tailscale app separately.

      2. Scan the new QR code

      Open a Vibelet app build that supports Tailcat and scan the new QR code printed by the command. An old QR code does not contain the Tailcat capability, so scan once again after enabling it.

      Vibelet races the eligible paths in the pairing profile and uses the first healthy connection. Enabling Tailcat does not remove LAN, Tailscale, or Cloudflare; those paths remain available as fallbacks.

      3. Understand 127.0.0.1:39876

      If the Vibelet app shows this current endpoint:

      127.0.0.1:39876

      That is expected. It is the phone app's local forwarder, not the computer's real address. The forwarder's upstream is the encrypted Tailcat P2P or DERP path.

      4. Check status

      Inspect the daemon and Tailcat sidecar on the computer:

      npx vibelet status

      In a healthy setup, tailcat.enabled and tailcat.running are both true. Vibelet redacts the Tailcat connection token from status output.

      If startup fails, inspect recent logs:

      npx vibelet logs

      5. Disable Tailcat

      npx vibelet --no-tailcat

      Both --tailcat and --no-tailcat are persistent choices. Vibelet stores the switch in ~/.vibelet/tailcat.json and reuses it for later starts and restarts.

      Troubleshooting

      Vibelet still uses Cloudflare or LAN

      This is not necessarily an error. Vibelet races the available paths, and LAN may finish its health check before Tailcat while both devices are on the same Wi-Fi. As long as the Tailcat sidecar is healthy, it remains an eligible remote path after the phone leaves the LAN.

      The connection never succeeds

      Check these in order:

      1. Both the computer and phone can make outbound HTTPS connections.
      2. The firewall or proxy does not block all outbound UDP. With restricted UDP, Tailcat may remain on DERP and have higher latency.
      3. Both devices use Vibelet builds that include Tailcat support.
      4. You scanned a new QR code after enabling Tailcat.
      5. npx vibelet status reports Tailcat as enabled and running.

      Do I also need Tailscale?

      No. Tailcat uses components from Tailscale's data plane without its control plane and does not require a tailnet account. If you already use a Tailscale IP, it can remain another Vibelet connection candidate alongside Tailcat.

      Security notes

      • Tailcat traffic is end-to-end encrypted with WireGuard.
      • Do not publicly share a Vibelet pairing QR code or raw tc... connection token.
      • Vibelet stores its Tailcat identity in a permission-restricted local file and redacts the connection token from status, logs, and telemetry.

      For Tailcat's implementation and limitations, see the official Tailscale Tailcat repository.