WPTSALL Client Complete Guide

WPTSALL Client is the local-first companion daemon and desktop application for the WPMMCC ATS WordPress plugin. This guide details installation, updates, uninstallation, configuration parameters, and the complete end-to-end automated translation workflow.

1. Overview & Product Architecture

WPTSALL Client ships in two form factors sharing the exact same compiled Rust core engine (tokio async runtime, reqwest with rustls, bundled SQLite, and cryptographic signature validation):

• WebUI (Daemon / Background Service): Runs as a headless daemon on 127.0.0.1:8977. Ideal for servers, VPS, local workstations, or NAS devices. Accessible via any standard web browser.
• Desktop Application (Tauri 2): Native window for the same engine. It listens on 127.0.0.1:8978 by default and stays on this computer, so it can run beside the WebUI on port 8977. It does not open its interface onto the network.

2. Cross-Platform Installation

Official signed packages for WebUI and Desktop are published on the WPTSALL Client releases page. Every package is signed with minisign and includes a SHA-256 checksum.

https://github.com/wpmmcc/wptsall-client/releases

Linux

Download the signed .deb or portable zip for your architecture (x86_64 or aarch64), plus the matching .minisig file. WebUI packages are named wptsall-client-webui-…. Desktop packages are named wptsall-client-…. After install, the WebUI listens at http://127.0.0.1:8977.

macOS

Download the signed .dmg or portable zip from the same page. The Desktop app is minisign-verified, but it is not Apple Developer-ID signed, so Gatekeeper asks for authorization on first launch (see below). The Desktop window listens on 127.0.0.1:8978.

Windows

Download the signed -setup.exe or portable zip for your architecture from the same page. The package is minisign-verified, but it is not Authenticode-signed, so SmartScreen asks for authorization on first launch (see below).

First-Launch Authorization (Unsigned OS Builds)

Release artifacts are protected by minisign signatures and SHA-256 checksums — this guarantees what you download is exactly what we published. However, the Desktop application currently carries no operating-system code-signing certificate (no Apple Developer ID, no Microsoft Authenticode). On first launch the OS itself will therefore show a warning. This is expected behavior for an unsigned build, not evidence of tampering:

• macOS (Gatekeeper): "WPTSALL Client" cannot be opened because it is from an unidentified developer. — Open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway. On macOS 14 and earlier you can instead right-click the app → Open → Open. Terminal users may clear the quarantine flag after verifying checksums: xattr -dr com.apple.quarantine "/Applications/WPTSALL Client.app"
• Windows (SmartScreen): Windows protected your PC. — Click More info, then Run anyway. Or, after verifying checksums: Unblock-File .\wptsall-client.exe

Recommended order: verify first (minisign + SHA-256, commands in the release README-AUTHORIZATION.md), then authorize. Full step-by-step instructions ship inside every release as FIRST-LAUNCH-AUTHORIZATION.md and as README-AUTHORIZATION.md next to the downloads.

Building from Source

If you prefer compiling directly with Rust toolchains:

# Build WebUI binary
cd client-wpplugin/source
cargo build --release
# Output binary: target/release/wptsall-client

# Build Desktop App (requires Node.js + Tauri CLI)
cd client-desktop
npm install
npm run tauri build

3. Updating & OTA Security

WPTSALL Client provides automatic, in-place Over-The-Air (OTA) updates with strict verification safeguards:

• In-App Update Check: In the WebUI, navigate to Settings → About and click Check for Updates. When a release source is configured (see WPTSALL_SERVER_BASE below) and a new version is available, it downloads and installs in place.
• Cryptographic Verification: Every update kit is checked against the official minisign public key (RWR7lrdabZEEywfWEfrRJXIyP5h+LHEabOA8JFiNJ3vGLpNtppyabHfP) and verified with SHA-256. Tampered or partially downloaded kits are rejected immediately.
• Anti-Rollback Protection: Version numbers are checked sequentially to prevent downgrade attacks.
• Zero-Downtime Safe Swapping: On Windows, where active executable files are locked by the OS, the updater renames and replaces the binary safely, with automatic rollback if replacement fails. On Linux and macOS, the system service restarts cleanly.
• Manual Update: You can also run the installer script again at any time; it will safely upgrade the binary in place without touching your configuration or task database.

4. Uninstallation & Data Retention

Dedicated uninstaller scripts for all products and operating systems are provided in the releases repository:

Linux / macOS Uninstallation

# Standard uninstall (keeps your SQLite database, settings, and logs)
sh uninstall-webui.sh

# Complete uninstall including database and logs
sh uninstall-webui.sh --purge-data --yes

# If you also have Desktop installed and want to remove shared binaries
sh uninstall-webui.sh --purge-shared --purge-data --yes

Windows Uninstallation

# Standard uninstall via PowerShell
.\uninstall-webui.ps1

# Complete purge including SQLite database and logs (-PurgeData requires -Yes)
.\uninstall-webui.ps1 -PurgeData -Yes

5. Parameter Configuration & Environment Variables

WPTSALL Client can be configured via environment variables, configuration files, or interactively within the WebUI Settings tab.

Port 8977 and Conflict Handling

The WebUI listens on 127.0.0.1:8977 by default — loopback only, so the interface is never exposed to your network. Port 8977 is not registered with IANA and sits away from the common service and development ranges (3306, 5432, 6379, 8080, 9000, 9200, and friends), so conflicts are rare in practice. If another local program has already taken the port, the client fails to start with bind web ui failed: 127.0.0.1:8977; set WPTSALL_WEB_UI_PORT (or WPTSALL_WEB_UI_BIND for a full address) to a free port and restart the service. For the systemd user unit, systemctl --user edit wptsall-client is the cleanest way to add the override; the Desktop app exposes the same variables as environment variables for the embedded WebUI.

6. End-to-End Integration Workflow

Understanding how WPMMCC ATS (WordPress) and WPTSALL Client coordinate during automated translation:

1. Content Model Scan (WordPress): In wp-admin, navigate to WPMMCC ATS → Content Models. The plugin scans posts, taxonomies, menus, and third-party plugins (WooCommerce, ACF, Elementor), generating a unified translation rule set.
2. Site Relations (WordPress): Under Site Relations, define your target language virtual site (e.g. Source: English, Target: Spanish with URL prefix /es/).
3. Authorize Client (WordPress): Under Task Management → Authorization, click Generate Connection Pack. The pack carries your site URL, route secret and a one-time pairing code, and stays claimable for the validity window you choose (default 5 minutes). WP-CLI alternative: wp wptsall security issue-pairing-pack --device-id=<client-device-id>.
4. Connect Site (Client): Open the client WebUI (http://127.0.0.1:8977) or Desktop app. On the Sites page, paste the connection pack JSON together with the pairing code and import it — the client claims a device-scoped token automatically and tests the connection.
5. Configure AI Provider (Client): Under My Components, install a provider component from the catalog (DeepSeek, OpenAI, Claude, DeepL compatible, or a local OpenAI-compatible endpoint such as Ollama on http://127.0.0.1:11434) and store its API key under API Keys.
6. Execute Translation Worker: Under the Worker tab, click Run Once (or start continuous background polling). The client claims pending batches from WordPress, translates them using your provider endpoint, and executes idempotent write-backs.
7. Target Sites Live: Translated articles, terms, and custom fields appear immediately under their respective virtual site URLs.