Skip to content

LychD on Linux, macOS and Windows

On all three systems you open Bridge in a browser to chat. Vessel is the server that connects that chat to your model and database. Linux normally runs Vessel in a rootless Podman container. Mac and Windows normally run it directly under your login. You can choose either placement on all three.

Installation guides Managed Linux · Native on any OS · Desktop containers

What do you want to know? The short answer
Where should Vessel run? Native runs under your OS account. A container limits which host files Vessel sees.
What do I install? Managed Linux needs Podman and systemd. Native installs need PostgreSQL 18, pgvector and a local engine for chat.
Where are my files? Look in your Linux user directories, macOS Library or Windows LocalAppData. Compose owns separate volumes.
What starts and stops it? systemd manages Linux containers. Native runs in a terminal, with optional sign-in startup on Mac and Windows.
How does model A give way to B? Managed Linux switches services. Native Vessel switches llama.cpp processes. Portable Compose serves one fixed model.
What can a process read? A native engine can read your account’s files. The Compose model receives one read-only model file.
How do the browser and model connect? The browser opens a local port. Native inference uses loopback. The Compose model runs inside the stack.
Who owns PostgreSQL? Containers have dedicated database storage. A native install creates a separate cluster for LychD.
Which credentials do I keep? Keep a separate copy of the credentials. You need them to reopen a restored database.
What can I snapshot or restore? Native PostgreSQL supports an independent backup on every OS. Quick local copies depend on Btrfs, APFS or Windows VSS and the chosen setup.
Can I share a service over a VPN? Linux can isolate overlapping peer addresses. Desktop Tether can offer one authenticated service to selected peers.
What survives an upgrade? Program files and data have separate lifecycles. Keep a matching database backup and credentials before upgrading.
How do I know chat works? Send a message, restart, then reopen the same conversation and check the saved reply.
Do I need to set up a VM? Native installs run directly on the host. Controlling a model outside a separate LychD guest is future work.

Where should Vessel run?

Choose a placement before installing. Run lychd platform to see which installation the current terminal addresses. Switching the setting selects a different installation with its own data.

Linux

The default is managed Podman. For native development, set export LYCHD_VESSEL_MODE=native in both terminals. For frontend work with synthetic data, use make frontend-dev and make developer-fixture. Frontend development

macOS

Native is the default and lets a compatible engine use the Mac GPU. For containers, set LYCHD_VESSEL_MODE=container and point LYCHD_CONTAINER_DIR at the prepared Compose project. Desktop container setup

Windows

Native runs directly in Windows without WSL. For Docker Desktop, select its Linux engine, set $env:LYCHD_VESSEL_MODE = 'container', and set $env:LYCHD_CONTAINER_DIR to the prepared project directory. PowerShell setup

What do I install?

Native chat needs PostgreSQL 18, its server-side pgvector extension, a trusted llama-server executable and a model file in GGUF format. Run lychd desktop install as your ordinary user. For dedicated-volume snapshots, select the volume before installing. Native prerequisites · Choose storage

Linux

Managed Linux needs systemd user services with lingering, cgroup v2, and rootless Podman and Quadlet 5.4+. Quadlet turns container definitions into systemd services. Build the CLI and image from the same revision and run lychd init --dry-run first. Linux install

macOS

The Apple Silicon .pkg includes the app and Python. Install PostgreSQL, pgvector and the model engine separately. Source setup and per-user test packages are both available. Get and verify a desktop edition

Windows

Use the x64 per-user .exe or the source checkout. Point LYCHD_PG_BIN at PostgreSQL’s bin directory and keep the engine DLLs beside llama-server.exe. Windows prerequisites

Where are my settings and data?

lychd platform prints the native settings, data and cache paths. Portable Compose keeps its database and credentials in project volumes owned by the container engine. Compose storage

Linux

Managed defaults are ~/.config/lychd for settings, ~/.local/share/lychd for data and ~/.cache/lychd for cache. Native uses lychd-native under each of the same XDG roots. Linux paths and mounts

macOS

Open ~/Library/Application Support/LychD for native config and data. Cache lives in ~/Library/Caches/LychD. Installed editions live separately in ~/Applications/LychD Editions.

Windows

Open %LOCALAPPDATA%\LychD for native config, data and cache. Program files live in %LOCALAPPDATA%\Programs\LychD Editions. A dedicated drive can hold the database.

How do I start and stop it?

Native on all three systems: run lychd desktop session in one terminal to start PostgreSQL and Vessel. Use lychd access in a second terminal for the browser address and password. Shut down with lychd stop, then lychd desktop stop. In a prepared source checkout, prefix these commands with uv run --no-sync. Foreground session

Linux

For managed Linux, lychd start brings up the systemd user services. Plan shutdown first. The public lychd stop currently refuses an active managed Vessel. Start services · Shutdown procedure

macOS

lychd desktop enable-login registers the working native installation with launchd as a per-user LaunchAgent. It starts that edition at sign-in. Login setup

Windows

The same command registers the interpreter in the current user's Registry Run key. Older scheduled-task registrations keep working until disabled. Sign-in setup and command-length limit

How does LychD switch from model A to model B?

Configure A and B as conflicting models. In Nexus, the model-selection screen, choose B, open Preview to see that A will stop, request the transition, and wait for B to become active. With the native two-model setup, also select a model before the first chat after startup. Portable Compose supports one optional fixed CPU model. Set up two models

Linux

Managed Vessel asks a host service, the Host Reactor, to switch the configured systemd units. systemd enforces their conflicts and start order. Native Vessel switches its own llama.cpp processes and checks port ownership through /proc. Managed switching

macOS

Native Vessel waits for A to exit, starts B and uses lsof to confirm that B owns the listening port. launchd handles sign-in startup. Vessel handles the switch.

Windows

Native Vessel does the same with llama-server.exe, using netstat.exe to verify the process. An occupied port or uncertain process ownership blocks the switch. Supported native engines

What can Vessel and the model access?

A native engine process can read files its OS account can read. It gets private scratch space and a filtered environment. To keep personal documents out of reach while using a native GPU, install under a separate standard account and restrict your documents to your own login. The Compose model receives one read-only GGUF file from the host. Foreign code needs its own sandbox in either placement. Native file access · Mounts by container

Linux

Managed Vessel gets read-only settings and selected data and secrets. It submits model switches through a mounted inbox. The Host Reactor validates each request. The container has no Podman socket or systemd bus. Native installation directories use mode 0700. Host permissions

macOS

Native chat, model switching and installed extensions use the login account’s access. Whole-volume snapshots require a separately authorized storage operator.

Windows

Native Vessel refuses to run elevated. Use NTFS permissions to keep personal files private from its standard account. The storage operator runs the privileged VSS step separately.

How do the browser and engine connect?

Open http://127.0.0.1:7134/ for the default local browser interface. Signing in checks the connection to Vessel. A reply in Bridge also checks the model connection. Open Bridge

Linux

Managed services communicate inside their Podman pod. The browser reaches the published loopback port. Native Vessel and its engine use the host's loopback directly.

macOS

Native Vessel forwards the model's configured endpoint, for example 127.0.0.1:8082, to the verified engine process on the Mac. Compose keeps its optional model inside the stack.

Windows

Use native Vessel for a Windows-native engine. The supplied Compose setup has no route or restart control configured for that engine. Its optional model runs on the stack's own loopback. Neither setup needs you to create host.containers.internal. Compose networking

Who owns PostgreSQL?

A native install creates a dedicated cluster, normally at 127.0.0.1:55432. Vessel uses a restricted database role. Another PostgreSQL service can coexist on a different port. Database setup

Linux

Managed PostgreSQL has its own container and data mount. A separate service applies schema migrations before Vessel starts. Managed startup

macOS

Native data defaults to data/postgres/native-data under LychD’s Application Support directory. Rerunning lychd desktop install checks that cluster and applies migrations.

Windows

The installation account owns the native cluster. To capture snapshots on a dedicated NTFS drive, register the live cluster against that drive. Registration procedure

Which credentials do I need for recovery?

Native installs generate five values for database access, application signing and browser login. Keep an independent protected copy and check it with lychd desktop verify-credential-backup. Backup, rotation and recovery

Linux

Native uses private credential files. Managed Linux mounts each Podman secret read-only into the service that needs it. Save the matching secrets and configuration separately from the database snapshot. Managed secrets

macOS

Private files are the default. You can move the values into your login Keychain after verifying the portable backup. Keep that backup for recovery under a new account.

Windows

Optional DPAPI encryption ties stored values to the Windows account. A fresh Windows profile needs the portable backup to recover them.

What do backups and snapshots restore?

For disk failure, all three native profiles can stream a verified PostgreSQL backup to independent storage with lychd desktop backup --destination …. A dedicated-volume restore creates an inactive database copy in a new directory and leaves the original cluster in place. Reopening LychD also requires matching configuration, credentials and current revocations. Database backup · Volume restore drill

Linux

Managed installation can create a Btrfs subvolume for a new database. A coordinated snapshot and restore of the whole installation is still a design. Btrfs setup · Whole-installation restore status

macOS

An APFS clone briefly stops PostgreSQL and makes a copy on the same disk. A test recovered a committed row from that copy. A whole-volume APFS snapshot uses a dedicated volume and a separate authorized producer. A successful whole-volume restore still needs a host trial. Clone procedure · Volume snapshots

Windows

The Volume Shadow Copy Service (VSS) snapshots a dedicated fixed NTFS drive while PostgreSQL is stopped. An authorized operator creates the snapshot. The standard account verifies it. Windows Server 2025 recovered a captured row and excluded a later write. Windows 11 still needs its own provider check and restore drill. VSS capture

Can I offer a service to a VPN peer?

Tether gives an authorized peer access to a specific service. The desktop helper offers one TCP service over WireGuard. The owner's Bridge chat stays local. Desktop service setup

Linux

Choose tether-container-v1 during managed initialization. Each imported peer attachment gets its own pod, so a private IP can appear on two attachments and still identify the right peer on each. Managed Tether

macOS

Run desktop-tether as your user. Each peer gets a separate userspace network. The helper forwards to one local TLS service that authenticates callers and leaves Mac routes and DNS alone.

Windows

Run desktop-tether.exe under a standard account. Arrange a reachable UDP port and any required firewall or router rule. Restart clears the grants. Stop the helper before sleep or hibernation until resume has been tested. Revoke and reconnect

How do I upgrade or remove LychD?

Keep the old revision, its pre-upgrade database backup and the matching credentials. After the upgrade, reopen a known conversation. Desktop upgrade and recovery

Linux

Keep the managed CLI, image and generated configuration together. Before removal, settle the services and inspect lychd del --dry-run for affected files and any Btrfs operation that needs an administrator. Managed removal

macOS

Stop Vessel and disable login through the old edition before changing editions. Install the new edition alongside it and run lychd desktop install. Removing an edition preserves account data.

Windows

Disable the old login registration before changing interpreters. Reinstall the same edition to repair program files. Uninstalling through Installed apps retains the account's data.

How can I tell whether chat works?

Send a distinctive message in Bridge and note its saved Run ID. Restart Vessel and PostgreSQL, reopen the conversation, and check the reply, model and ID. Recorded trials

Linux

Native Linux passed the browser test. For managed Linux, check the migration service and lychd logs --lines 120. Switching on the target Quadlet/GPU host still needs a hardware trial. Linux checks

macOS

Chrome passed on macOS 15 Apple Silicon. Cold sign-in, GPU performance, physical Docker Desktop, whole-volume restore and public installer acceptance have separate checks. Mac checks

Windows

Edge passed on Windows Server 2025 x64 under a standard account. Windows 11 hardware, cold sign-in, physical Docker Desktop, SmartScreen and the local VSS provider still need workstation checks. Windows checks

Do I need to manage a virtual machine?

Native LychD runs directly on the OS. Docker Desktop supplies its containers’ Linux environment. Using a separate LychD guest to control the outer host is a future deployment option. VM design and requirements

Linux

A Linux guest can host its own managed installation. Its services, storage and loopback belong to the guest. Linux guest qualification

macOS

Native mode reaches a Mac engine today. Switching it from a separate guest would require a private network route and an authorized operation on the Mac.

Windows

WSL and Podman guests have their own loopback. Connecting to a Windows engine would require a tested listener, firewall and return route. Restarting that engine would also require host-side authorization.