CUVENA AGENTS 56.0.0 — START HERE



Extract this whole ZIP before installing. Choose one folder per machine:

Windows-Desktop: Setup.exe, INSTALL-GUIDE.txt, DEPLOYMENT-GUIDE.txt.

Windows-Headless: Setup.exe, worker, command-line helpers and headless-install.txt.

Linux: source, systemd installer/upgrade/uninstall helpers and linux-install.txt.



Deploy the v32 Cuvena website first. There is no new v32 database migration when

upgrading from v31. Older installations must apply their pending historical

migrations. The agent-only ZIP is not a website update.

All guides explain installation, purpose-separated credentials and validation.

Assign an Agent account in Agent management, then use the agent-account default

on the task or select a separate Task account. Both is an explicit opt-in.

Machine-wide Windows Setup requests elevation automatically and registers an

uninstaller that offers Keep settings or Remove local data. Closing the manager

leaves the background service running.



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-19.txt for the exact checks and limitations.



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.
