CUVENA WINDOWS DESKTOP 56.0.0 INSTALL 1. Extract the complete Cuvena-Agents-v56.0.0.zip. Open Windows-Desktop. 2. Double-click Cuvena-Agent-Desktop-Setup-v56.0.0.exe. Windows requests administrator approval automatically. You do not need to right-click Run as administrator. Being in Administrators does not remove Windows UAC approval. 3. Setup installs for the whole computer and registers Control Panel uninstall. The Start menu shortcut is available to all users. Managing the machine vault or service requires administrator approval; running tasks is controlled in SaaS. 4. Open Cuvena Agent Manager. Pair using the HTTPS workspace URL and a one-use code from Agent management. Save the exact permitted servers in Settings. 5. Choose Configure & start service. The background service uses Windows Local Service, with no personal password prompt. It continues when the window closes, after sign-out, and after restart. A service that was stopped stays stopped during an upgrade until you choose Start service. 6. Complete ACCOUNT SETUP below. Connected/accepting work does not itself prove successful Windows authentication or script execution on another machine. UPGRADE / REPAIR Run the new Setup in the same machine-wide installation folder. It closes this installation's manager and waits for the service/worker to stop before replacing files. A busy operation must finish first. It preserves pairing and credentials. An older per-user installation must first be uninstalled using Keep settings and credentials; this installer will not run a duplicate personal and machine worker. Old per-user protected files are not automatically shared with all machine users. UNINSTALL / FRESH START Use Settings > Apps or Control Panel > Programs and Features > Cuvena Agent Manager. The uninstaller stops and removes its service and application files. Choose: Keep settings and credentials: retain the pairing/vault for reinstalling. Remove local data too: remove this installation's ProgramData pairing, settings, local logs and saved credentials. This is the clean-reset choice. Website scripts, tasks, agent registrations and run history are retained. Old backup folders outside this installation are retained. Retire a registration in Agent management only if it is no longer needed. See DEPLOYMENT-GUIDE.txt for silent installation, SCCM/Intune detection, Keep/Purge switches and exit codes. ACCOUNT SETUP — VERSION 12 1. In Credential management choose Agent account, Task account, or Both. Agent account: connects to target servers and runs tasks using the default. Task account: overrides the execution account after the agent connects. Both: deliberately allow this same saved account in either role. 2. Choose its authorized pool. Save centrally in Cuvena, or save it in the local agent vault. Local passwords stay on the agent; metadata appears in Cuvena. Centrally managed accounts appear on the agent without re-entering passwords. 3. In Agent management > Edit, assign the Agent account. Only Agent/Both accounts in that agent's space and pool are offered. This does not change the Windows service logon identity: the service securely uses the assigned connection credential when reaching a target. Windows and SSH still enforce access. 4. In task settings choose Agent account (default), or a Task/Both account. No task override means the script runs as the authenticated connection account. The website user who clicks Run does not become the Windows execution account. 5. Allow the exact target address in the agent's Execution settings. A hostname, IP and localhost are separate permitted addresses. For HTTPS, the certificate must be valid for the address used. The agent never disables certificate checks. 6. Run a harmless output-only script first. Open its run details: Agent ready, Server connection, Task account sign-in, Script execution. Failures have links to the relevant agent, task credential, target or task. Output names the actual authenticated/execution account. A missing completion record requires review; it is never retried automatically or reported as success. SYNCHRONIZATION Website saves are picked up on the next outbound heartbeat, normally within 15 seconds while connected. Local saves wake the next connection. Organization settings > Agent synchronization sets full reconciliation every 1–1440 minutes, with Sync all agents now and last synchronization status. Offline agents catch up after reconnecting. Sync does not silently widen locally permitted servers. One hosting cron entry runs bin/cron.php every minute; it also handles the other Cuvena scheduled jobs. See the full release's hosting and database instructions. UPGRADING FROM VERSION 11 OR EARLIER Update the website and run php bin/database.php apply BEFORE upgrading agents. Preserve private configuration, APP_KEY, pairing files and vaults. Existing saved credentials retain Task purpose; change a selected connection credential to Both or create an Agent account, then assign it to the agent. Existing tasks keep their selected task credential. Choose the Agent account default explicitly if wanted. Old agents cannot claim the new two-account jobs. Upgrade every execution agent. No uninstall or re-enrollment is needed for a healthy machine-wide installation. WINDOWS TARGET REQUIREMENTS Remote PowerShell uses WinRM HTTPS with a trusted certificate and an account allowed to access its endpoint. IP and localhost work only when the listener, certificate and authentication are configured for that address. The connection credential is separate from the optional task credential. A task override needs Windows sign-in rights and the Secondary Logon service on the target. Opening PowerShell in an existing desktop session proves that existing token works; it does not prove that Windows will accept a new password-based remote logon for the same displayed name. Check the reported stage and Windows event 4625 on the target when Windows rejects a saved account. Keep your chosen work account; Cuvena does not silently substitute another account. Scripts run in a background session. A GUI such as Notepad will not appear on the signed-in desktop. Verify returned output and actual file/system effects. VALIDATION BOUNDARY This release was built and checked on Windows with isolated test accounts, PowerShell process execution, vault/role checks, loopback SSH, database upgrades, browser forms and installer lifecycle fixtures. It has not been validated with your actual work-account password on a live remote target. Linux systemd and PAM sign-in need acceptance testing on a Linux host; this Windows build environment has no Linux runtime. See RELEASE-13.txt for the exact checks and limitations. VERSION 13 DIAGNOSTICS Upgrade SaaS and apply database release 13 before starting this agent. Central job credentials are encrypted for this agent and decrypted in memory. Wait for the next heartbeat to register its protected job key. Preserve the .job-key file with other agent state; restoring data preserves the pairing key. Detailed logs: agent-diagnostics.jsonl beside the agent state/configuration. SaaS: Agent management > Agent diagnostics. Passwords are never logged. Exact-match results verify delivery, not Windows/Linux sign-in permission. See RELEASE-13.txt in the full product package for update order and limits. AUTOMATIC LOCALHOST CERTIFICATE MAINTENANCE (v43) Setup starts WinRM automatically and installs machine-level certificate checks. Cuvena-owned localhost HTTPS certificates renew 30 days before expiry. Checks run hourly, at startup, after supported wake events, and after missed checks. Both IPv4 and IPv6 must pass normal TLS validation. Interrupted renewal retries safely. External certificates remain administrator-managed. No firewall or authentication permissions are widened. See localhost-certificate-maintenance.txt and ACCEPTANCE-43.txt. CUVENA v44 — CONTROLLED AGENT UPDATES FIRST INSTALLATION Version 44 is the first updater-enabled release. Install it once with Windows administrator or Linux root access. Existing v43 agents cannot self-bootstrap. The Windows setup installs a SYSTEM task named Cuvena Agent Updates. Linux setup installs cuvena-updater.timer and a separate root-owned recovery runtime. They check once a minute; sleeping/offline machines catch up after reconnecting. PLATFORM ADMIN Open Agent updates. Upload the matching signed artifact to Downloads and import its signed release envelope. Select organizations and offer the release, or also select compatible agents and click Update selected agents. No unselected customer receives an offer. Importing alone installs nothing. CUSTOMER APP Organization owners and administrators see an Overview notification when a newer release is offered. Open Agent updates, select the release and your own agents, then Update selected agents. Ordinary members cannot request updates. PROGRESS AND RECOVERY Queued → downloading → draining → installing → verifying → succeeded. New work pauses while current scripts finish. Unknown executions require outcome verification before installation. Success requires a fresh new-version heartbeat. On failure, the updater restores the previous version and verifies its heartbeat. Recovery needing attention keeps new work paused. Cancellation is available only before installation begins. Pairing, vaults and execution settings are preserved. The page checks progress every second without reloading the page or selections. LOCAL DIAGNOSTICS Windows: C:\ProgramData\CuvenaUpdater\last-result.json and journal.json. Linux: /var/lib/cuvena-updater/last-result.json and journal.json; journalctl -u cuvena-updater.service. These protected files require administrator/root access. Do not remove an active journal or rollback files. Repair the same installation with the matching signed package if recovery cannot complete; verify heartbeat. PACKAGES AND SIGNING A real agent version needs a fresh package. Changing a SaaS label is not an installation. To test updates, use v44 then a signed higher-version build. The updater verifies the pinned RSA signature, package hash, length, platform, expiry and HTTPS origin. Redirects, unsigned packages and downgrades are rejected. Initial installation can prompt for elevation. Later updates use the installed privileged helper; Windows policy may still block an unapproved executable. RSA package signing is separate from a Windows Authenticode publisher signature. Linux updates require unchanged pinned dependencies; a dependency change needs an administrator bootstrap upgrade. Root-owned rollback data stays on the host. SAAS UPGRADE Back up databases and site files. Deploy v44 with maintenance enabled, preserve private configuration/storage, then run php bin/database.php apply all and check php bin/database.php status all before enabling traffic. v44 adds database tables; v43 did not. Do not import full schema SQL into an existing database. Keep config/agent-update-public.pem consistent with installed agent trust. Never upload the private release signing key to the website or distribute it. CERTIFICATES AND LIVE EXECUTION Windows localhost certificate renewal from v43 is retained. It renews the managed local certificate before expiry, with validation and recovery safeguards. It does not renew certificates on arbitrary remote targets. Live monitoring and test/run details check every second while visible, update in place and show stale/retry state on network failures. Test connection opens the run directly. CUVENA 56.0.0 - RELEASE AND OPERATIONS GUIDE Desktop packaging: includes tkinter and Tcl/Tk. The build checks Tcl/Tk first, then launches the frozen desktop in an isolated self-test before building installers. No configuration, pairing or background worker is changed by that self-test. Agent updates: Overview and Notifications show approved releases to authorized owners/admins. A separate notice explains missing updater bootstrap for recently connected legacy agents. SaaS version alone is not a customer release offer. Agent lists now show IDs and last heartbeats. Recent contact is the default; choose All non-revoked registrations to include offline machines, or Revoked to review historical registrations. No registrations are automatically deleted. Search, select all matching, clear selection, count and individual exceptions are available for customers and agents. Maximum 10,000 per request. No 500-row cutoff. Incompatible, revoked, already updating and non-newer agents remain unavailable. Comfortable and Compact rows visibly change spacing and survive progress refresh. Admin Email delivery is the account-message audit, separate from SMTP test history. It shows recipient, organization, type, queued/SMTP-accepted/failed state, expiry and recorded attempts. SMTP acceptance does not guarantee inbox delivery. Organizations -> Owner account access -> choose organization -> Show owners -> Send fresh owner setup link queues a 24-hour link to the saved active owner's email. This invalidates all earlier unused password links for the account, including links for its other organizations, and prevents stale queued setup links being sent. Passwords remain unchanged until the recipient completes setup. The action is restricted, rate limited and audited. No passwords or reset links appear in audit. New owner welcome links last 24 hours. Existing users get a sign-in link. Forgot password issues a 30-minute link. Cron and enabled SMTP are required. Templates: Platform settings -> Email templates -> Organization welcome or Owner password setup. Existing custom templates are preserved. Retained: managed localhost certificate renewal, wake recovery safeguards, one-second monitoring/test-run content refresh, direct connection testing, signed platform-controlled desktop/headless/Linux updates and verified rollback. Remote target certificates and operating-system policies require their own management. PLATFORM AGENT UPDATES Bundled packages are verified and registered automatically when the platform administrator opens the updated deployment, or runs php bin/database.php apply all. In Admin > Agent updates, choose a release and customers. Offer the release for customer-controlled installation, or select agents and request their update. No manual registration step is needed. Customer App updates remain limited to releases offered to that organization. Review any package errors shown above the release selector.