Headless Linux server¶

Deploy Pynchy on a headless Linux server as a systemd user service. The examples use Tailscale and WhatsApp; configure a different channel when WhatsApp does not fit the deployment.

Prerequisites¶

On the server, use Ubuntu or Debian with Docker, a reachable Temporal service, and Tailscale when you need remote access. On your local machine, keep SSH access and GitHub CLI authentication when cloning a private repository.

Install the server dependencies¶

sudo apt-get update
sudo apt-get install -y docker.io docker-buildx sqlite3 gh
sudo usermod -aG docker $USER

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env

Log out and back in after changing Docker group membership, or verify it with sg docker -c "docker ps".

Clone and build¶

ssh-keyscan -H github.com >> ~/.ssh/known_hosts
git clone [email protected]:crypdick/pynchy.git ~/src/pynchy
cd ~/src/pynchy
uv sync
uv sync --extra whatsapp       # only when using WhatsApp
git clone [email protected]:YOUR-ACCOUNT/pynchy-personalization.git \
  data/personalization
uv run pynchy validate-personalization data/personalization
sg docker -c './src/pynchy/agent/build.sh'

Configure credentials and a channel¶

Configure model routes and non-secret settings in the private data/personalization/ checkout. Keep gateway, provider, and channel secrets in the Pynchy checkout's root .env. See Personalization repository.

Follow Channels for Slack or Discord setup. To use WhatsApp, authenticate from the server and scan its terminal QR code:

uv run pynchy-whatsapp-auth

First run and service¶

uv run pynchy

The first foreground run creates the initial workspace, installs the user service, enables it for boot, and enables user lingering. Verify it, stop the foreground process, then start the service:

systemctl --user start pynchy
systemctl --user status pynchy
journalctl --user -u pynchy -f

Use config-examples/pynchy.service.EXAMPLE as the unit-file reference.

Maintain and update the server¶

Use your normal operating-system update policy. The optional templates in config-examples/ install unattended upgrades and a daily Docker cleanup/reboot timer. Keep those live files under your own operational control.

For remote source updates, enable deployment separately from public diagnostic access; see remote deployment. Pynchy validates imports and rolls back a failed deployment.