Set up a gateway

Give your NAS a door.

The gateway is the small piece of Loft that runs at home. Your apps talk to it, and it talks to your NAS, signed in as you. It takes about ten minutes, and you only do it once.

What you need

  • A Linux machine that's always on and on the same network as the NAS: x86_64 or arm64, with Python 3.12 or newer. Debian 13, Ubuntu 24.04 and current Raspberry Pi OS have it; on an older system, use the container. A 64-bit Raspberry Pi will do. Use a machine that does nothing else if you can (see Security).
  • A NAS or server that shares folders over SMB 3, and its address on your network.
  • Your NAS username and password. You'll type them into the app later, not into the gateway's settings.

  1. Install

    Coming soon. The gateway isn't available to download yet. When it is, the .deb and the container image will be on Download, and the commands to install them will be right here.

  2. Point it at your NAS

    Run loft-gateway init. It asks for your NAS address, writes the settings file and creates the gateway's keys. At the end, it shows a pairing code.

    Then run loft-gateway doctor. It checks that the gateway can reach the NAS, which SMB version and encryption the NAS offers, that the clock is right, and that the certificate is valid. If something is wrong, it tells you what. Add --user and your NAS username to check sign-in and the shared folders too. It asks for the password and never prints it.

    An older NAS without SMB encryption? By default the gateway refuses to connect without it. With smb_encryption = "server" in the settings file, the NAS decides instead, and the connection on your home network is encrypted only if the NAS asks for it. It's your choice.

  3. Pair your apps

    Run loft-gateway pair and scan the QR code with the Loft app, or open the link on the device. The code carries the gateway's address and its keys, so the app knows it's talking to your gateway from the very first connection. Then sign in with your NAS username and password.

    There's no field for typing in a gateway address, on purpose: a typed address could lead you to a fake gateway that collects passwords. If you really need it, Set up manually is on the app's pairing screen.

  4. Away from home (optional)

    At home, nothing more is needed. To use Loft away from home, choose one:

    • A tunnel, for example Cloudflare Tunnel. No open port on your router, but the tunnel provider can read the traffic, and you sign in at home.
    • Direct, with a port forwarded on your router to the gateway. Encrypted end to end, and you can sign in from anywhere. The gateway limits sign-in attempts.

    The differences are explained in How it works. Run loft-gateway pair again after changing it, so the code includes the new address.

Limit what Loft shows (optional)

Loft shows every shared folder your NAS account can open, and the NAS's own permissions decide the rest. You can narrow it further in the settings file: only some shared folders, hidden folders or paths, or only some users. All of these are empty by default.

Updating

The gateway never updates itself. Install the new .deb or pull a new container image after reading the release notes. → Source for release notes and checksums.