diff --git a/README.md b/README.md
index ab650d0..c303989 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,8 @@ just test
 just lint
 ```
 
+Nix users can enter a devshell with `nix develop`, or `direnv allow` to auto-enter via the bundled `.envrc`. Pre-built artifacts (including the devshell) are available from our [binary cache](docs/install-nix.md#binary-cache).
+
 ## Production Deployment
 
 ### Quick Deploy (Docker/Podman Compose)
@@ -59,6 +61,7 @@ podman-compose -f docker-compose.prod.yaml up -d
 
 ### Installation Guides
 
+- [Nix](docs/install-nix.md)
 - [Debian](docs/install-debian.md)
 - [Containers](docs/install-containers.md)
 - [Kubernetes](docs/install-kubernetes.md)
@@ -99,4 +102,3 @@ This project is very grateful to [@nonbinary.computer](https://tangled.org/did:p
 ## License
 
 AGPL-3.0-or-later. Documentation is CC BY-SA 4.0. See [LICENSE](LICENSE) for details.
-
diff --git a/docs/install-nix.md b/docs/install-nix.md
new file mode 100644
index 0000000..2ba8fac
--- /dev/null
+++ b/docs/install-nix.md
@@ -0,0 +1,70 @@
+# Tranquil PDS production installation on NixOS
+
+This guide covers installing Tranquil PDS on NixOS via the flake and the bundled NixOS module.
+
+## Prerequisites
+
+- A server :p
+- Disk space enough for blobs (depends on usage; plan for ~1GB per active user as a baseline)
+- A domain name pointing to your server's IP
+- A wildcard TLS certificate for `*.pds.example.com` (user handles are served as subdomains)
+- Flakes enabled (`experimental-features = nix-command flakes` in `nix.conf`)
+
+## Add the flake as an input
+
+In your system flake:
+
+```nix
+{
+  inputs.tranquil.url = "git+https://tangled.org/tranquil.farm/tranquil-pds";
+
+  outputs = { self, nixpkgs, tranquil, ... }: {
+    nixosConfigurations.pds = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        tranquil.nixosModules.default
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+## Enable the service
+
+In `configuration.nix`:
+
+```nix
+{
+  services.tranquil-pds = {
+    enable = true;
+    database.createLocally = true;
+    settings = {
+      server.hostname = "pds.example.com";
+      # see example.toml for all options
+    };
+  };
+}
+```
+
+This will set up the local postgres database for you automatically. If you prefer to manage postgres yourself, leave `database.createLocally` at its default (`false`) and set `settings.database.url` manually.
+
+See [example.toml](../example.toml) for the full set of configuration options.
+
+## Binary cache
+
+Pre-built artifacts from the flake — the package, frontend, and devshell — are published to [tranquil.cachix.org](https://tranquil.cachix.org). To pull from it instead of building locally, add to your NixOS config:
+
+```nix
+nix.settings = {
+  substituters = [ "https://tranquil.cachix.org" ];
+  trusted-public-keys = [ "tranquil.cachix.org-1:PoO+mGL6a6LcJiPakMDHN4E218/ei/7v2sxeDtNkSRg=" ];
+};
+```
+
+> [!NOTE]
+> Due to a current spindle limitation, the aarch64 package is cross-compiled on an x86_64 builder and published under a separate attribute. If you're running on aarch64, set the package manually:
+>
+> ```nix
+> services.tranquil-pds.package = inputs.tranquil.packages.x86_64-linux.tranquil-pds-aarch64;
+> ```