# Rayfish > Rayfish is a peer-to-peer mesh VPN: private virtual networks with no central server, where every device is addressed by its cryptographic identity. These docs describe the `ray` CLI and daemon. Networks are closed by default; a coordinator admits peers with one-time invite codes or live approval. ## Docs - [Introduction](https://rayfish.xyz/docs/01-introduction): Rayfish is a peer-to-peer mesh VPN that creates private virtual networks without any centralized infrastructure. It is built on top of [iroh](https://iroh.computer), a library that provides encrypted QUIC-based peer-to-peer connectivity with automatic NAT traversal, hole-punching, and relay fallback. - [Getting Started](https://rayfish.xyz/docs/02-getting-started): Five commands take you from nothing to a working mesh between two machines. Run the first three on the machine that creates the network, the last on the one joining. - [How It Works](https://rayfish.xyz/docs/03-how-it-works): This chapter is the map. The chapters that follow drill into individual subsystems; this one steps back and shows how the pieces fit: the artifacts that exist on the wire, and how a network takes shape as peers join. - [Magic DNS](https://rayfish.xyz/docs/04-magic-dns): Magic DNS lets you reach peers by name instead of IP. Every peer gets a hostname, chosen via `--hostname` at create/join time, falling back to a default you set with `ray up --hostname `, and finally to a random name from a word list. - [File Sharing](https://rayfish.xyz/docs/05-file-sharing): Rayfish includes peer-to-peer file sharing over the mesh. Files are content-addressed via blake3 and transferred directly between peers, with no cloud storage and no size limits. - [Access Control](https://rayfish.xyz/docs/06-access-control): This chapter is about **traffic control**: who can talk to whom *once they're in* the network. That's a different question from **admission**, who is allowed to join in the first place, which the coordinator gates with invite codes and live approval (see **Membership** and **Getting Started**). Admission decides membership; everything below decides which packets flow between members. - [Local Device Firewall](https://rayfish.xyz/docs/07-local-device-firewall): The local device firewall gives each peer control over its own inbound and outbound traffic. It is the fine-grained layer on top of network segmentation: which networks a host joins decides *who can reach it at all*, and the firewall decides *what those peers can do*, by direction, protocol, port, and per-network scope. It is bottom-up by default ("I decide what reaches my ports"), but on any network the coordinator can suggest rules that ride in the signed network state; see the **Access Control** chapter. - [Mesh SSH](https://rayfish.xyz/docs/08-mesh-ssh): Rayfish ships an embedded SSH server, so you can SSH into a node over the mesh with no SSH keys to manage. It is the same model as Tailscale SSH: the peer connecting to you is already cryptographically identified by the encrypted mesh link, so that identity is the credential and there are no `authorized_keys` files anywhere. - [Device Pairing](https://rayfish.xyz/docs/09-device-pairing): Rayfish's identity model normally binds one cryptographic key to one device. Device pairing extends this so that a single user can operate multiple devices under a shared identity, using certificate-based pairing. - [Exit Nodes](https://rayfish.xyz/docs/10-exit-nodes): An exit node is a member that offers itself as an **internet gateway** for a network: other members route all their non-mesh traffic out through it, so their public IP becomes the gateway's. It's the same idea as a Tailscale exit node. Nothing about mesh traffic changes; only the destination of packets that would otherwise have gone straight out your own uplink. - [Configuration](https://rayfish.xyz/docs/11-configuration): Rayfish persists its state so that networks survive restarts. Configuration is **sharded**: global settings live in `settings.toml`, and each network gets its own file under `networks/.toml`. The daemon reads them all on startup to reconnect to every saved network. - [CLI Reference](https://rayfish.xyz/docs/12-cli-reference): Every `ray` subcommand, grouped by what it does. This is the lookup table; the **Getting Started** chapter walks the common ones in order, and the feature chapters explain the concepts behind them. - [Membership](https://rayfish.xyz/docs/13-membership): Membership is the heart of rayfish's identity and authorization system. It decides how peers are identified, how their IP addresses are assigned, and who is allowed to join a network. - [Network Lifecycle](https://rayfish.xyz/docs/14-network-lifecycle): This chapter ties everything together by walking through the complete lifecycle of a network. - [Statistics](https://rayfish.xyz/docs/15-statistics): rayfish exposes Prometheus-compatible metrics, alongside iroh's own endpoint metrics. - [Audit Logging](https://rayfish.xyz/docs/16-audit-logging): rayfish keeps an append-only log of peer connection events at `~/.config/rayfish/audit.log`. The daemon opens (or creates) it on startup. - [Troubleshooting](https://rayfish.xyz/docs/17-troubleshooting): Most problems fall into one of four buckets: the daemon isn't running the way you think, two peers can't reach each other, DNS names don't resolve, or the firewall is dropping traffic you expected to flow. Work top-down: confirm the daemon, then the connection, then the name, then the policy. - [Glossary](https://rayfish.xyz/docs/18-glossary): Rayfish's vocabulary is dense and load-bearing, and several terms are easy to confuse (room id vs invite code, coordinator vs operator, member vs peer). This chapter defines each one in a sentence or two, with a pointer to the chapter that covers it in full. - [Identity](https://rayfish.xyz/docs/19-identity): Every device on a rayfish network has a persistent Ed25519 keypair stored at `~/.config/rayfish/secret_key`. This keypair is the device's cryptographic identity: it determines the device's EndpointId and, by extension, its virtual IP address. - [Transport](https://rayfish.xyz/docs/20-transport): Rayfish uses iroh to provide encrypted peer-to-peer QUIC connectivity with automatic NAT traversal. - [TUN Device](https://rayfish.xyz/docs/21-tun-device): A TUN (network TUNnel) device is a virtual network interface that operates at the IP layer. Unlike a TAP device (which works at the Ethernet layer), a TUN device sends and receives raw IP packets (both IPv4 and IPv6) without Ethernet framing. - [Packet Forwarding](https://rayfish.xyz/docs/22-packet-forwarding): Packet forwarding is the data plane of rayfish. It moves packets between the TUN device and peer connections. - [Peer Discovery](https://rayfish.xyz/docs/23-peer-discovery): rayfish publishes each network's state to a discovery record so that peers can find each other and fetch the network state (membership and any coordinator-suggested firewall rules) even when the coordinator is offline. A single record per network contains everything needed to *discover and bootstrap* into a network, but discovery is not admission: on a closed network the coordinator still gates who actually gets in (see **Membership**). rayfish uses iroh's pkarr/DHT relay for this discovery. - [Daemon Architecture](https://rayfish.xyz/docs/24-daemon-architecture): Rayfish uses a daemon/client split similar to Tailscale. The daemon (`ray daemon`) is a long-lived background process that owns all shared resources, while the CLI commands you type are thin clients that talk to it. - [Security Model](https://rayfish.xyz/docs/25-security-model): All communication is encrypted end-to-end by iroh's QUIC implementation. Connections use TLS 1.3 with Ed25519 certificates derived from each peer's keypair. No traffic, including relayed traffic, can be read or modified by intermediaries. ## Optional - [Full documentation (single file)](https://rayfish.xyz/llms-full.txt) - [Agent skill: set up a network](https://rayfish.xyz/skill/SKILL.md) - [manymux documentation index](https://rayfish.xyz/manymux/llms.txt): persistent terminal sessions over ssh, the site's other project.