Cuvena Windows Desktop installation · v56.0.0

Download the complete agent bundle · Plain-text guide

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.