diff --git a/README.md b/README.md
index e860f06..a28cfc1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,32 @@
-# nixos-config
+# nixfiles
 
-My NixOS configuration files
\ No newline at end of file
+My NixOS configuration files.
+
+## Machines
+
+* `tohru`: Dell Latitude 5300, personal laptop
+* `yevaud`: Oracle Cloud free AMD VM, hosts a Forgejo instance
+
+## Usage
+
+### Building
+
+To build locally, run `colmena apply-local` as root.
+
+To build the remote machines, run `colmena apply`. See the [colmena documentation](https://colmena.cli.rs/) for command-line options. Notable options include:
+* `--on [hostname]`: build a specific machine only
+* `--reboot`: reboot after building (but note [this bug](https://github.com/zhaofengli/colmena/issues/166) means it may hang even when the reboot completes successfully)
+
+### Updating
+
+Run `npins update` to update the dependencies within the currently selected upgrade channels.
+
+To upgrade to a new major version of a dependency, simply re-add it and the old version will be overwritten, e.g.:
+
+```sh
+npins add --name nixpkgs channel nixos-unstable
+```
+
+In either case, commit the changes to `npins/sources.json`.
+
+See the [npins documentation](https://github.com/andir/npins) for more details.
\ No newline at end of file