diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index c7259a4..bb57a68 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -6,6 +6,7 @@
- [Architecture](./architecture.md)
- [Source code, Building, and Installation](./install.md)
+- [Running on an emulated device](./emulator.md)
- [Glossary](./glossary.md)
# User and Administration Guide
diff --git a/src/emulator.md b/src/emulator.md
new file mode 100644
index 0000000..91e465f
--- /dev/null
+++ b/src/emulator.md
@@ -0,0 +1,84 @@
+# How to get Synit running on an emulated PostmarketOS device
+
+[vouch.id]: https://vouch.id/
+
+Begin by following the [generic PostmarketOS instructions for running using
+QEMU](https://wiki.postmarketos.org/wiki/QEMU_amd64_(qemu-amd64)), reprised here briefly, and
+then build and install the Synit packages and (optionally) the SqueakPhone user interface.
+
+## Build and install `qemu-amd64` PostmarketOS
+
+First, run `pmbootstrap init` (choose `qemu`, `amd64`, and a `console` UI); or, if you've done
+that previously, run `pmbootstrap config device qemu-amd64`.
+
+Then, run `pmbootstrap qemu --video 720x1440@60` to create an emulated PostmarketOS device and
+start it. You'll run that same command each time you boot up the machine, so create an alias or
+script for it, if you like.
+
+## Set up `ssh` access to the emulated device
+
+I have the following stanza in my `~/.ssh/config`:
+
+```
+Host pm-qemu
+ HostName localhost
+ Port 2222
+ User user
+ StrictHostKeyChecking no
+ UserKnownHostsFile /dev/null
+```
+
+Log in to the device using a username and password (`SSH_AUTH_SOCK= ssh pm-qemu`) and set up
+SSH key access via `~/.ssh/authorized_keys` on the device, however you like to do it. I use
+[vouch.id][] to log into my machines using an SSH certificate, so I do the
+following:
+
+```
+mkdir -p .local/bin
+cd .local/bin
+wget https://vouch.id/download/vouch
+chmod a+x
+sudo apk add python3
+echo 'export VOUCH_ID_PRINCIPAL=tonyg@leastfixedpoint.com' >> ~/.profile
+```
+
+Then I log out and back in again to pick up the `VOUCH_ID_PRINCIPAL` variable, followed by
+running
+
+```
+vouch server setup --accept-principals tonyg
+```
+
+(Substitute your own preferred certificate principal username, of course.) After this, I can
+use the [vouch.id][] app to authorize SSH logins.
+
+## Allow port forwarding over SSH to the device
+
+Edit `/etc/ssh/sshd_config` to have `AllowTcpForwarding yes`. This will let you use e.g.
+port-forwarded VNC over your SSH connection to the device once you have the user interface set
+up.
+
+## Build and install the packages
+
+Follow the [build and installation instructions](./install.md) to check out and build the code.
+
+Once you've checked out the `synit` module and have all the necessary build dependencies
+installed, change directory to `synit/packaging/squid` and run `start.sh` in one terminal
+window. Leave this open for the remainder of the build process. Open another terminal, go to
+`synit/packaging`, and run `make keyfile`. Then, run `make ARCH=x86_64`.
+
+Hopefully the build will complete successfully. Once it has done so, change to `synit/scripts`
+and run `./upload-bundle.sh pm-qemu`. Then log in to the emulated device and run the
+`./transmogrify.sh` script from the `/home/user` directory. Reboot the device. When it comes
+back, you will find that it is running Synit (check `ps` output to see that `synit-pid1` is in
+fact PID 1).
+
+## Build and install the user interface packages
+
+If you want to run the SqueakPhone image on your local machine, ensure your Unix user is in the
+`input` group.
+
+squeak-phone: ./push-image-to-phone.sh pm-qemu
+
+set `dpi.override` to have 256 in it
+
diff --git a/src/install.md b/src/install.md
index be9d78f..f2cfbb5 100644
--- a/src/install.md
+++ b/src/install.md
@@ -24,24 +24,28 @@ Synit builds upon many existing technologies, but primarily relies on the follow
- Rust nightly and Cargo (perhaps installed via [rustup](https://rustup.rs/)).
+ - The rust `cross` tool (even for `x86_64` builds):
+
+ ```
+ cargo install cross
+ ```
+
+ - Docker (containers are used frequently for building packages, among other things!)
+
- Python 3.9 or greater
- `git`, `ssh`, `rsync`
- Make, a C compiler, and so on; standard Unix programming tools.
- - Docker (containers are used frequently for (cross-)building of Alpine packages, among other
- things!)
-
- The `preserves-tool` binary installed on your `PATH`:
```
cargo install preserves-tools
```
- - For cross builds (e.g. the very common case of building for `aarch64` on
- an `x86_64` host), `qemu` and its `binfmt` support. On Debian, `apt install binfmt-support
- qemu-user-static`.[^debian-qemu-bug]
+ - `qemu` and its `binfmt` support (even for `x86_64` builds). On Debian,
+ `apt install binfmt-support qemu-user-static`.[^debian-qemu-bug]
- Source code for Synit components (see below).
@@ -52,7 +56,8 @@ Synit builds upon many existing technologies, but primarily relies on the follow
- **Great tolerance for the possibility of soft-bricking your phone.** This is experimental
software! When it breaks, you'll often have to (at least) reinstall PostmarketOS from
absolute scratch on the machine. I do lots of development using `qemu-amd64` for this
- reason.
+ reason. See [here](./emulator.md) for [instructions on running Synit on a emulated
+ device](./emulator.md).
## Get the code
diff --git a/src/introduction.md b/src/introduction.md
index 6db96ca..a437074 100644
--- a/src/introduction.md
+++ b/src/introduction.md
@@ -19,10 +19,9 @@ Linux's Unix heritage.
## Quickstart
-If you have a mobile phone or computer capable of running
-[PostmarketOS](https://postmarketos.org/), then you can
-[install](./install.md) the software to try it out. You can also run
-Synit inside a virtual machine.
+You can [run Synit on an emulated device](./emulator.md), or if you have a mobile phone or
+computer capable of running [PostmarketOS](https://postmarketos.org/), then you can
+[install](./install.md) the software on your device to try it out.
See the [installation instructions](./install.md) for a list of
supported devices.