> ## Documentation Index
> Fetch the complete documentation index at: https://hayate.shiina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Pairing Mode vs Direct Mode: Hayate Transfer Modes

> Hayate offers two transfer modes: Pairing Mode for automatic LAN discovery with a shared code phrase, and Direct Mode for known IP:port connections.

Hayate gives you two ways to transfer files across your local network. **Pairing Mode** is the default experience: a shared code phrase lets sender and receiver find each other automatically without exchanging IP addresses. **Direct Mode** skips discovery entirely and connects straight to a known address — useful when you already know where the receiver is, or when your network restricts multicast traffic. Both modes use the same QUIC transport and end-to-end AEAD encryption; they differ only in how the two peers find each other and how the session key is authenticated.

## Pairing Mode

Pairing Mode is designed for everyday use. The sender broadcasts its presence over mDNS and UDP, and the receiver listens for an announcement that matches the shared code phrase. When a match is found, Hayate opens a QUIC connection and performs a cryptographic handshake — no IP address entry required.

The code phrase does more than help peers find each other. During key derivation, Hayate mixes the phrase bytes directly into the HKDF input keying material. This means only a peer that knows the exact phrase can derive the correct session key and decrypt your transfer.

```bash theme={null}
# Receiver waits for the matching code
hayate receive --code "forest-river-mountain"

# Sender broadcasts with the same code
hayate send ./report.pdf --code "forest-river-mountain"
```

If you omit `--code` on the sender, Hayate auto-generates a random 4-word phrase and prints it to the terminal for you to share verbally or via a side channel.

```bash theme={null}
# Sender auto-generates a phrase and displays it
hayate send ./report.pdf
# Output: code: ocean-timber-lantern-swift
```

Pairing Mode works on **macOS, Linux, Windows, and Android (Termux)**. The mDNS implementation is Bonjour-compatible on macOS and works out of the box on most home and office routers. On networks where multicast is unreliable, Hayate automatically falls back to a UDP broadcast path — discovery works either way.

## Direct Mode

Direct Mode skips discovery entirely. You provide the receiver's IP address and port as a `host:port` argument, and Hayate connects immediately. This is the right choice when you already know the receiver's address, when you are scripting automated transfers, or when your network administrator has disabled multicast.

```bash theme={null}
# Receiver listens on a specific port
hayate receive --port 50001

# Sender connects directly by address
hayate send ./archive.tar.gz 192.168.1.50:50001
```

You can customise the bind address and port with `--bind` and `--port`. In Direct Mode there is no passphrase, so authentication relies on network locality — only a host that can actually reach the receiver's address can initiate a transfer.

```bash theme={null}
# Bind to a specific interface
hayate receive --bind 10.0.1.5 --port 50001
```

## Choosing a Mode

| Feature                   | Pairing Mode                               | Direct Mode                            |
| ------------------------- | ------------------------------------------ | -------------------------------------- |
| Peer discovery            | Automatic (mDNS + UDP broadcast)           | Manual — you supply the IP and port    |
| Passphrase authentication | Yes — phrase is mixed into the session key | No — relies on network locality        |
| Multicast required        | mDNS preferred; UDP broadcast fallback     | Not required                           |
| Best for                  | Everyday transfers between any two devices | Enterprise/managed networks, scripting |

<Tip>
  **Use Pairing Mode** for ad-hoc transfers between laptops, phones, and servers where you don't want to look up IP addresses. **Use Direct Mode** when you're on a corporate network with multicast restrictions, when you're scripting a pipeline, or when you already have the receiver's address in a config file.
</Tip>