My laptop's NixOS configuration.
README.org
* README

Welcome to my default laptop configuration.
The motto is: *Do more with less*.

Understand deeply the happy path: the path that deals with complexity
that must be dealt with.
Then sit back and relax.

** Assumptions
1. There is a folder at `~/me` which stores all my stuff.
2. `~/me` is backed up appropriately.
3. `~/me/org` stores my notes.
4. Emacs is my text editor.

* Fastmail calendar synchronization

=vdirsyncer= synchronizes the Fastmail calendars bidirectionally with
=~/me/calendar/=, one directory per discovered calendar and one =.ics= file
per event. =khal= discovers those directories. The user timer runs a sync every
15 minutes after the previous run; manually run =vdirsyncer sync
fastmail_calendar= when needed. Sync propagates local edits *and deletions* to
Fastmail. Conflicts are reported rather than automatically resolved. The
existing =~/me= restic backup includes the local calendar files, but not
vdirsyncer's status directory at =~/.local/share/vdirsyncer/status/=.

** Provision and initialize

1. Create a Fastmail app password with calendar and contacts access. Contacts
   synchronization is not configured here.
2. On the laptop, encrypt the password in a separate agenix secret. The editor
   should contain only the password, with no extra text:
   #+begin_src sh
   cd ~/laptop/secrets # adjust if this repository is elsewhere
   env EDITOR='emacs -nw -Q' nix run ..#agenix -- -e fastmail-caldav-password.age
   #+end_src
   This uses the recipients in =secrets/secrets.nix=. Do not put plaintext
   credentials in the repository or the Nix store. Track the encrypted file so
   the Git-backed flake can read it, then rebuild the laptop configuration:
   #+begin_src sh
   jj status
   nixos-rebuild switch --flake ..#laptop --sudo
   #+end_src
   Run the rebuild from =secrets/=, or adjust the flake path accordingly.
3. Before the first sync, check any existing =~/me/calendar/= contents and
   back them up. Discovery may offer to create local collection directories;
   review prompts rather than accepting unexpected changes:
   #+begin_src sh
   mkdir -p ~/me/calendar
   vdirsyncer discover fastmail_calendar
   vdirsyncer sync fastmail_calendar
   khal printcalendars
   khal list today 30d
   #+end_src
   Run discovery again when calendars are added on Fastmail. Calendar names
   reported by khal may be collection IDs, not Fastmail display names; provide
   the desired default name after discovery for the Emacs configuration.

The timer is installed on activation but skips while the agenix secret is
absent. Until discovery is completed, sync attempts may fail; inspect them with
=systemctl --user status calendar-sync.timer calendar-sync.service= and
=journalctl --user -u calendar-sync.service=. The timer retries on its next
interval. Emacs uses vendored khalel to refresh a generated Org agenda file
every 15 minutes, independently of the sync timer. See the Calendar section of
=emacs/README.org= for commands, limitations, and generated-file precautions.

* Experimental pi MicroVMs

=sandbox/default.nix= declares two pi MicroVMs. The shared guest baseline
installs pi and its session wrapper, tmux, Git, Jujutsu, BusyBox, OpenSSH and
CA certificates. NixOS may also provide standard base utilities.

- =pi-clojure-rust= adds =uv=, Graphviz and full TeX Live for the paper's
  pdfLaTeX, BibTeX and arara tooling. Despite its historical name, it no longer
  declares Clojure or Rust tools. It uses VSOCK CID 100, a 5 GiB RAM ceiling,
  and balloon/free-page reporting. TeX Live is not directly installed in the
  laptop user's home packages.
- =pi-python= adds only =uv= to the shared baseline and uses =nix-ld= for
  uv-managed Python and common native wheels. It uses VSOCK CID 101 and the
  module's 512 MiB RAM ceiling. Python versions and project dependencies are
  managed separately with =uv=; some native wheels may require other libraries,
  and larger Python builds or workloads may exceed the memory limit.

Check that CIDs 100 and 101 are unused by other VMs on the host. Each sandbox
has its own persistent context image and SSH over VSOCK. Both declare a QEMU
user-mode network interface and guest DHCP/DNS configuration through the
upstream microvm.nix options. No host IP forwarding, bridge, NAT or inbound
port forwarding is configured. Guest Nix builds are not yet supported.

Each VM shares the host's =/nix/store= read-only via virtiofs instead of packing
its system closure into a store disk. This exposes host store contents readable
by the share service to the guest and adds virtiofsd to the isolation boundary;
it does not expose the host Nix daemon. Each persistent =context.img= remains
separate. Verify that each active VM generation remains rooted across host
upgrades and garbage collection before relying on it for important work.
The user has confirmed the read-only shares and accepts visibility of host store
contents. Changes require activation and a manual VM restart.

QEMU makes network connections on the host on the guest's behalf. This does
not itself enforce Mullvad lockdown. The user reports that fail-closed
behavior was verified for Mullvad failure scenarios. Guest access to host and
LAN services through user networking remains unverified. The VM does not
automatically restart on configuration changes; repeat relevant checks after
changes to Mullvad, QEMU or host networking.

Before evaluating, copy the intended SSH *public* key to =pi-sandbox-ssh.pub=
in this repository and track it so the Git-backed flake can read it. Never put
the private key in the repository or Nix store. For example, if the existing
laptop key is the intended one:

#+begin_src sh
cp ~/.ssh/id_leoqi.pub pi-sandbox-ssh.pub
git add pi-sandbox-ssh.pub
#+end_src

The laptop must pin the sandbox revision providing the shared tmux session and
host command. Run =nixos-rebuild= as your normal user so it can fetch SSH inputs
with your key; =--sudo= elevates activation.

The user reports workspace, authentication and recovery persistence are
confirmed, and pi starts and persists authentication. Bundled instructions and
extension discovery have not been separately confirmed. Balloon behavior and
the 5 GiB limit require validation; larger builds can be offloaded to Tangled CI/CD.

** Shared pi session

After activating this configuration, start the desired service and specify its
instance name on the laptop:

#+begin_src sh
sudo systemctl start microvm@pi-python.service
sandbox pi-python
# Or: sudo systemctl start microvm@pi-clojure-rust.service
#     sandbox pi-clojure-rust
#+end_src

The sandbox module provides this command. It uses public-key SSH over VSOCK
and attaches to one guest tmux session per VM, starting
=pi --continue= in =/context= when needed.
Detach with =Ctrl-b= then =d=; pi can continue while the VM runs. A VM restart
stops tmux and pi, but the next connection reloads the latest saved session for
=/context=. It cannot restore a running process. Use =/resume= to choose a
session created in another directory. The command does not start the VM.

SSH automatically accepts the first guest host key presented and saves it in
=~/.ssh/pi-python_known_hosts= or =~/.ssh/pi-clojure-rust_known_hosts=,
respectively. Later connections reject a changed key;
previously enrolled keys are preserved. This is trust on first use: VSOCK does
not independently authenticate the first key. Investigate a changed-key warning
rather than blindly removing the recorded key. SSH may still ask to unlock a
private key. The host command advertises =TERM=xterm-256color= regardless of
the calling terminal, so terminal-specific display and key behavior can differ.
The shared guest module provides tmux and extended-key configuration for each
VM; terminal behavior and detached-session survival need runtime validation.

** Shared SSH signing

=sandbox/default.nix= enables the sandbox module's experimental shared SSH commit
signing for every declared pi VM. It requires the sandbox revision that defines
=services.piSandboxes.signing= and these Git-tracked laptop files before NixOS
evaluation or activation:

- =secrets/pi-sandbox-signing.age=: the dedicated passphrase-free private signing
  key encrypted with agenix to the laptop host and personal recovery recipients
  from =secrets/secrets.nix=.
- =secrets/pi-sandbox-signing.pub=: its matching Ed25519 public key, without a
  comment. Register it as a signing key with each Git provider.

The plaintext signing key must never enter Git or the Nix store. Any guest
=developer= process can read, copy and use it; compromise of one VM compromises
all VMs' shared signing authority. Git and jj settings are defaults, not an
immutable enforcement boundary. The module is not yet runtime-verified; review
its signing documentation and verify key access, signatures and failure behavior
on the laptop. Activation does not restart existing VMs; stop and start them
manually without deleting =context.img=.

Removing the previous =pi-test= declaration did not delete or migrate its
existing container root or Nix profiles. They may be reviewed and explicitly
removed separately; do not point a MicroVM at them. Existing Podman data and
the MicroVM's =context.img= are unrelated and must not be removed as part of
that cleanup.