diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..3550a30
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake
diff --git a/README.md b/README.md
index 195f927..5702764 100644
--- a/README.md
+++ b/README.md
@@ -412,3 +412,22 @@ See [doc/PERF-HANDOFF.md](doc/PERF-HANDOFF.md) and [doc/BENCHMARKS.md](doc/BENCH
 The historical Shen 22.4 head-to-head versus the `shen-c` 0.2.3 interpreter (same
 machine) is preserved in [doc/BENCHMARKS.md](doc/BENCHMARKS.md): fib 66–79× faster, n-queens ~2.5× faster,
 Einstein's riddle ~1.5× slower.
+## Optional Nix environment
+
+Nix is optional; the normal shen-lua build and launcher commands continue to work
+with tools installed by any method. For a pinned development toolchain:
+
+```sh
+nix develop
+```
+
+The flake also exports `packages.toolchain` for composition by
+[Bifrost](https://github.com/pyrex41/bifrost):
+
+```sh
+nix shell .#toolchain
+```
+
+If direnv is installed, `direnv allow` opts this checkout into the same dev
+shell automatically. Nothing activates until that explicit authorization, and
+Nix is never required at runtime.
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..4b6a7af
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1787631388,
+        "narHash": "sha256-vMiXptXarfSdJb1Gkc+FYVOAibuBRj7qxGa8z68q1Uw=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "ac6b2166e7a9375683b8e98f860f273222337b16",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..53d2b71
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,8 @@
+{
+  description = "shen-lua development environment";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+  outputs = { nixpkgs, ... }: let systems = [ "aarch64-darwin" "x86_64-darwin" "aarch64-linux" "x86_64-linux" ]; each = f: nixpkgs.lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system}); in {
+    packages = each (pkgs: { toolchain = pkgs.buildEnv { name = "shen-lua-toolchain"; paths = with pkgs; [ gnumake gcc luajit luarocks ]; }; default = pkgs.buildEnv { name = "shen-lua-toolchain"; paths = with pkgs; [ gnumake gcc luajit luarocks ]; }; });
+    devShells = each (pkgs: { default = pkgs.mkShell { packages = with pkgs; [ gnumake gcc luajit luarocks ]; }; });
+  };
+}