Cuvena Linux installation · v56.0.0
Download the complete agent bundle · Plain-text guide
CUVENA LINUX AGENT 56.0.0 REQUIREMENTS AND INSTALL A systemd Linux host, Python 3.11+, python3-venv, OpenSSH client, root/sudo, outbound HTTPS and access to install the pinned Python requirements. The Linux folder is a source distribution; it is not an offline self-contained binary. Extract the whole ZIP, open Linux, then run: sudo sh install-linux.sh Enter a one-use code from Agent management. For another workspace URL: sudo env CUVENA_URL=https://app.cuvena.com sh install-linux.sh The installer creates a dedicated cuvena user and enables cuvena-agent at boot. CONFIGURE AND CONNECT As root, add permitted addresses to allowed_targets in /etc/cuvena/agent.json. Preserve the pairing fields and state_directory. Keep ownership root:cuvena and mode 0640. Add ssh_known_hosts with the path of a verified known_hosts file, for example /var/lib/cuvena/known_hosts. Make that file readable by the cuvena user. Verify host-key fingerprints independently; do not disable host-key checking. For a centrally managed Linux credential, save its actual login name and password in Cuvena and choose Agent account or Both. No local duplicate is needed. For an agent-managed password (prompted locally), use: sudo -u cuvena /opt/cuvena/venv/bin/python /opt/cuvena/cuvena_agent.py vault save --config /etc/cuvena/agent.json --reference connector --account svc_connect --purpose connection --target server01.example.com --protocol ssh --known-hosts /var/lib/cuvena/known_hosts Use --purpose task for a task override, or both for both roles. Local private-key bindings may be used for the Agent connection; a task override requires its own password. Keep private keys and the vault readable only by the service account. sudo systemctl restart cuvena-agent sudo systemctl status cuvena-agent sudo journalctl -u cuvena-agent -n 50 Then assign the Agent account in Cuvena Agent management. Verify the heartbeat, then a harmless task's returned output. The worker continues after logout. TARGET EXECUTION The target requires SSH and Python 3. Agent-account default runs as the account that authenticated to SSH. A task override signs in through the target's su/PAM policy with its separate password. That account must be permitted by target PAM rules; Cuvena does not grant sudo, bypass PAM, or change host security settings. Bash/Python/PowerShell scripts require their interpreter installed on the target. Linux task-account passwords containing newline characters are not supported. UPGRADE / UNINSTALL Drain in Cuvena and wait for active work to finish. Run sudo sh upgrade-linux.sh from the new Linux folder. Pairing, vault and local policies are preserved; a backup is kept at /opt/cuvena.previous. Check the heartbeat before accepting work. Run sudo sh uninstall-linux.sh and confirm UNINSTALL to disable/remove the service definition. It retains program files, pairing, vault and the cuvena user for recovery. It does not implement an automatic data purge. Website history is preserved. 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. 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. 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.