Pandrator Manager

pandrator-manager is Pandrator's Qt-free, per-user installation, update, repair, removal, and runtime control plane. It runs independently of the Pandrator application, browser, and optional tray client, and exposes an authenticated loopback API plus a standalone setup/recovery WebUI. Explicit private-network and HTTPS-ingress profiles support headless servers and GPU pods without changing the loopback-only default.

The current release is 0.9.1. For most users, the easiest installation is the Windows executable or Linux AppImage on the Pandrator 0.6.1 release page. These packages include their own runtime and do not require a suitable system Python.

Safety and ownership

• One Manager instance controls one explicit workspace.
• Install, update, repair, removal, and runtime changes show an exact plan before they run.
• The Manager checks disk space, paths, ports, downloads, and other prerequisites before changing the installation.
• Components are staged and validated before becoming active. A failed activation returns to the previous working slot.
• The Manager stops only processes it can identify and removes only paths it owns.
• User data is separate from replaceable runtimes and is preserved by default.
• The optional tray is only a client. Closing it does not stop the Manager, Pandrator, or a running service.
• Product updates are checked against project-signed manifests and artifact hashes.

The Windows executable is not Authenticode-signed and may produce an Unknown publisher or SmartScreen warning. Verify its release checksum when you download it.

Installation

The native packages are the recommended installation:

• Windows: PandratorManager-0.9.1-windows-x86_64.exe
• Linux: PandratorManager-0.9.1-x86_64.AppImage

If you already have Python 3.11 or 3.12, install the Manager as an isolated command-line tool:

pipx install pandrator-manager
# or
uv tool install pandrator-manager

Use pandrator-manager[tray] instead if you want the optional desktop tray. For a downloaded wheel, replace the package name with its local path.

For development from this checkout:

python -m pip install -e ./pandrator_manager

A normal Python package installation does not enable autostart, launch a daemon, download a component, or request elevation.

Installation location

On its first interactive desktop launch, the native Windows or Linux launcher opens the operating system's folder chooser. Select the parent directory; the managed installation is created as <selected directory>/Pandrator. Cancelling the chooser makes no installation changes.

The launcher stores the canonical parent directory in the user's platform configuration directory and reuses it on later launcher, CLI, and optional tray runs. The installed stable launcher also identifies its own workspace, while autostart, manager handoff, and every component operation carry that workspace explicitly. This prevents a later component installation from silently returning to the home directory.

Use --choose-workspace to reopen the chooser, or select a location non-interactively:

PandratorManager-x86_64.AppImage setup --workspace /path/to/parent
PandratorManager-0.9.1-windows-x86_64.exe setup --workspace D:\path\to\parent

--workspace takes precedence over PANDRATOR_WORKSPACE, which takes precedence over launcher discovery and the remembered preference. Headless deployments should pass one of those explicit values; --no-open never opens a native dialog. The launcher can also reuse the workspace preference written by older Pandrator installers.

Basic use

pandrator-manager --workspace /path/to/workspace start-manager
pandrator-manager --workspace /path/to/workspace status
pandrator-manager --workspace /path/to/workspace list
pandrator-manager --workspace /path/to/workspace open --recovery

The mutation grammar is plan first, then execute the same action only when the component reports it as supported:

pandrator-manager --workspace /path/to/workspace plan \
  --kind ACTION --component ID[:COMPUTE[:QUANTIZATION]]
pandrator-manager --workspace /path/to/workspace ACTION \
  --component ID[:COMPUTE[:QUANTIZATION]] --yes --wait

The first command is read-only. The action is available only when the Manager's component definition has a supported recipe; see Current component coverage.

Runtime and recovery examples:

pandrator-manager --workspace /path/to/workspace runtime-start tts.xtts
pandrator-manager --workspace /path/to/workspace operations --active
pandrator-manager --workspace /path/to/workspace cancel OPERATION_ID
pandrator-manager --workspace /path/to/workspace doctor
pandrator-manager --workspace /path/to/workspace autostart enable

Use --json for automation. The manager API and operation records are versioned; clients should use stable component and service IDs rather than persisting transient loopback ports.

Headless and remote deployment

The native launcher can prepare exact workstation-facing URLs for both setup/recovery and Pandrator:

pandrator-manager-launcher setup \
  --workspace /srv/pandrator \
  --remote-setup-url https://setup.example.test \
  --remote-pandrator-url https://pandrator.example.test \
  --trusted-proxy-hops 1 \
  --no-open

The command still prints a short-lived, one-use recovery URL when --no-open is used. HTTPS mode expects an operated reverse proxy or ingress and binds to 127.0.0.1 by default. For a pod ingress in another network namespace, add --network-bind-host 0.0.0.0 and restrict access with the platform's network policy.

The URL token is only a bootstrap credential. After exchange, the browser receives a revocable, HTTP-only authorization that survives manager restarts and ordinary updates; only its SHA-256 digest is stored in manager state. Loopback and HTTPS authorizations use a 30-day inactivity window and a 90-day absolute limit. Trusted private HTTP offers a remembered-browser choice with a 7-day inactivity window and 30-day absolute limit, or a browser-session-only authorization. Reloading the page renews CSRF state without requiring another launch URL. The recovery header can sign out the current browser or forget all authorized browsers.

For a trusted LAN or VPN without TLS, use exact http://server:port URLs and --allow-insecure-private-network. The public and listening ports must match, forwarded headers are not trusted, and an owner password must be initialized locally because the manager will not accept password submission over remote plain HTTP. PANDRATOR_OWNER_PASSWORD is supported as a one-time deployment secret for first startup; it is consumed from the environment and is not persisted or forwarded to backend workers.

The remote setup manager controls only its own host and workspace; it is not a multi-host controller. The normal Pandrator WebUI keeps host mutations local by default. A deliberately administered single-owner deployment may set PANDRATOR_ALLOW_REMOTE_MANAGER_MUTATIONS=1, while the recovery UI remains the recommended remote installation and repair surface.

MCP recovery enrollment

Pandrator MCP normally reaches Manager through the authenticated application proxy. This keeps the permanent Manager client bearer on the managed host.

An operator who needs app-down remote diagnostics or recovery may expose the Manager's separately bounded HTTPS recovery origin and enroll a distinct MCP credential:

pandrator-mcp target add production \
  --mode external \
  --origin https://pandrator.example \
  --recovery-origin https://recovery.pandrator.example \
  --scope app.read \
  --scope manager.read \
  --recovery-scope manager.read \
  --recovery-scope manager.runtime

pandrator-mcp target login production
pandrator-mcp target pin production
pandrator-mcp target login production --manager-recovery
pandrator-mcp doctor --target production

Open the one-use Manager recovery URL first so the enrollment approval opens in an authorized browser. The approval page shows the client, both canonical origins, requested scopes, and expiry. The issued recovery credential is audience- and instance-bound, expires after at most 30 days, is rate-limited per client, and is stored directly in the workstation's OS keyring.

Direct automation is disabled unless Manager is configured with an exact HTTPS recovery origin. It cannot use the permanent local bearer, change network settings, access arbitrary files, or bypass native plans and confirmations. Application and recovery clients can be revoked independently through their owner-authorized client-administration APIs.

The local workspace owner can inspect and revoke recovery clients without copying the permanent Manager bearer out of the host:

pandrator-manager --workspace /srv/pandrator automation-client list
pandrator-manager --workspace /srv/pandrator automation-client revoke CLIENT_ID --yes

The recovery browser offers the same owner operation. After server-side revocation, delete the controller's separate keyring value with pandrator-mcp target logout production --manager-recovery --yes.

For a pod, persist both the Pandrator data root and the Manager workspace/state and restrict a cross-namespace --network-bind-host 0.0.0.0 listener with platform network policy. Losing either state volume changes the identity that the MCP pins and requires deliberate re-enrollment.

The complete workstation, LAN, external-server, pod, and agent-host setup is in the Pandrator MCP guide.

Legacy import, releases, and uninstall

Inspect legacy state without changing it:

pandrator-manager --workspace /path/to/workspace legacy
pandrator-manager --workspace /path/to/workspace legacy-import --yes

The first command only inspects the older installation. Import keeps unknown files in place, can be repeated safely, and refuses to proceed if the inspected source changes before confirmation. Use --json for automation.

Inspect accepted release slots or review a signed release:

pandrator-manager --workspace /path/to/workspace releases
pandrator-manager --workspace /path/to/workspace release-plan \
  --manifest /path/to/release-manifest.json
pandrator-manager --workspace /path/to/workspace release-update \
  --manifest /path/to/release-manifest.json --yes --wait

These commands verify the embedded trust policy, platform/architecture, artifact length and SHA-256, release sequence, compatible manager version, and signing-key rotation. Callers cannot replace the project's trusted key with an arbitrary one.

Uninstall first emits a reviewable plan:

pandrator-manager --workspace /path/to/workspace uninstall
pandrator-manager --workspace /path/to/workspace uninstall \
  --preserve-data --yes --wait
pandrator-manager --workspace /path/to/workspace uninstall \
  --export-data /new/path/pandrator-data.zip --preserve-data --yes --wait
pandrator-manager --workspace /path/to/workspace uninstall \
  --purge-data --yes --wait

Preservation is the default. Export refuses to overwrite an existing destination and verifies the ZIP before removal. Purge has a distinct destructive confirmation. The launcher performs final cleanup after the Manager exits and removes only files owned by the selected installation.

Surfaces

• The Pandrator WebUI shows provider installation and runtime actions where they are relevant.
• The manager recovery WebUI works before Pandrator is installed and while it is stopped or unhealthy.
• The CLI provides recovery and automation parity.
• pandrator-tray provides convenience actions only and is never required.

The tray extra is never a daemon dependency. pandrator-tray --check reports whether a usable desktop backend exists; on headless Linux it returns unavailable: No graphical desktop session is available. without importing an X11 backend or creating the requested workspace. Quitting or losing the tray does not stop any managed process.

Current component coverage

The Manager installs, updates, starts, stops, repairs, and removes the current component catalogue:

• Kokoro supports CPU, CUDA, ROCm on supported modern AMD hardware, and Metal.
• VoxCPM currently requires CUDA.
• CrispASR offers Whisper, Parakeet, and MOSS choices; MOSS diarization with Q8 precision is the default.
• Qwen3 TTS defaults to the 1.7B model. Automatic hardware selection sends unsupported or older AMD hardware to the CPU path.
• XTTS inference is available, but XTTS fine-tuning is not currently offered by the Manager.

Pandrator and source-backed engines are downloaded into staging, checked, and activated side by side. Manager updates use the project-signed release channel.

Getting help

Use GitHub Issues for problems or suggestions. Include the operating system, workspace layout, action you attempted, and logs with secrets removed.

License

Pandrator Manager is released under the MIT License. Third-party runtimes, services, and models retain their own licences and usage conditions.