Windows (WSL2)¶

Yeliztli runs on Windows through WSL2 (Windows Subsystem for Linux). It is not supported directly on native Windows.

Set up¶

Install WSL2 with a Linux distribution (Ubuntu is a good default).
Inside WSL2, install Python 3.12+ and Node 20+.
Follow the native install steps inside your WSL2 shell.
Open http://localhost:8000 in your Windows browser. localhost is normally shared between Windows and WSL2; if the page doesn't load, see Can't reach the app from your browser? below.

Run the dev server¶

For local development, run the backend, the Vite dev server, and the Huey worker together. On WSL2 use the dev-wsl target so the servers bind to 0.0.0.0 and your Windows-host browser can reach them:

make dev-wsl

Then open http://localhost:5173. make dev-wsl is the WSL-friendly counterpart of make dev: it runs backend.main with YELIZTLI_HOST=0.0.0.0 and starts Vite with --host. Plain make dev binds to 127.0.0.1 only.

LAN exposure

Binding to 0.0.0.0 exposes the dev servers to your local network, not just your PC. That is fine on a trusted network, but for a private-by-default setup prefer mirrored networking (below), which keeps the loopback bind and still lets localhost work from Windows. Don't bind 0.0.0.0 on an untrusted network.

Can't reach the app from your browser?¶

If a server starts inside WSL2 but the browser shows "This site can't be reached", it is bound to 127.0.0.1 (loopback) and WSL2's localhost forwarding to Windows isn't reaching it. Fix it one of these ways.

Bind to all interfaces (quickest). Run make dev-wsl, or set YELIZTLI_HOST=0.0.0.0 for the backend and pass --host to Vite (make run-frontend VITE_ARGS=--host). Mind the LAN-exposure caveat above.

Mirrored networking (private, recommended). Keep the loopback bind and make localhost transparent between Windows and WSL2. Add this to C:\Users\<you>\.wslconfig on the Windows side, then run wsl --shutdown from PowerShell:

[wsl2]
networkingMode=mirrored

Reach WSL directly. As a fallback, browse the WSL VM's IP instead of localhost — find it with hostname -I inside WSL (e.g. http://172.22.98.184:5173).

Port 8000 already in use?¶

The backend defaults to port 8000. On WSL2 that port is easy to lose: Windows can forward localhost:8000 to a foreign Windows-side process, so the backend fails to bind (or /api requests reach the wrong process) even though make dev looks like it started. Move the whole dev stack to another port with API_PORT — it sets the backend port and points the Vite /api proxy at it, so the two stay in sync:

make dev API_PORT=8010       # or: make dev-wsl API_PORT=8010

You still open http://localhost:5173 — only the backend moves. API_PORT defaults to any exported YELIZTLI_PORT, else 8000. (For a non-dev, single-port make run, set the port via YELIZTLI_PORT / config.toml instead — see Configuration.)

Enable systemd¶

Yeliztli's background services use systemd on Linux/WSL2. Enable systemd in your distro by adding this to /etc/wsl.conf:

[boot]
systemd=true

Then restart WSL2 from PowerShell:

wsl --shutdown

After WSL2 restarts, yeliztli-setup install can register the services, and loginctl enable-linger "$USER" makes them start automatically.

Note

Keep your data and the repository inside the WSL2 filesystem (e.g. under your Linux home directory) rather than on a mounted Windows drive (/mnt/c/...) for much better performance.