Skip to main content

Agent lifecycle and recovery

Use this guide to verify a new install, apply agent updates, choose a safe repair path, or recover management after an endpoint changes identity or location.

Roles and responsibility​

  • Viewer can review endpoint status, version, inventory, and recent activity.
  • Operator can run supported endpoint actions, including agent updates.
  • Admin manages organizations and higher-risk operational settings.
  • Owner handles tenant-sensitive workflows such as export and deletion requests.

The operating-as selector can reduce your effective role. If an expected action is unavailable, confirm both your assigned role and the role currently selected. See Tenant administration for the complete public role summary.

Verify an installation​

  1. Generate a current platform-specific bootstrap command in the production portal.
  2. Confirm the tenant and organization before running it with administrative authority on the endpoint.
  3. Wait for the endpoint to appear in the expected organization.
  4. Check that the portal shows a recent heartbeat, operating system, architecture, and agent version.
  5. Wait for the first audit before relying on patch, script, terminal, reboot, remote access, or homelab actions.

A successful bootstrap command by itself is not verification. The expected result is a current heartbeat and inventory from the intended endpoint identity. If the endpoint does not appear, follow Troubleshooting before reinstalling.

Apply an agent update​

Operator or higher access can run an available agent update for a supported direct endpoint. Before starting:

  • confirm the endpoint is online and is a directly installed agent rather than an inventory-only guest row;
  • record the current agent version;
  • check the endpoint's effective agent-update policy; and
  • avoid starting the update when losing the current remote session would leave you without another administrative path.

The expected result is that the endpoint reconnects and reports the target version. Treat an accepted command as work in progress until the portal shows the new version and a fresh heartbeat. If it does not reconnect, preserve the visible command result and follow the repair ladder below.

Use the safest repair path​

Work from least disruptive to most disruptive:

  1. Verify visibility. Confirm tenant, organization, direct-agent status, last heartbeat, and effective role.
  2. Check the endpoint. Confirm outbound connectivity and that the TvRMM service is running. Record visible errors before changing the installation.
  3. Retry only a supported action. If the agent is online and the portal presents an update or other recovery action, use that action and wait for a new heartbeat.
  4. Diagnose and repair locally. Use Agent cleanup and removal to list local agents, run diagnosis, and try identity-preserving repair before removing an agent when its service, certificate, watchdog, or local installation may be recoverable. Listing verifies the configured server health endpoint only; it does not prove that the agent identity can complete heartbeats.
  5. Clean up one damaged or duplicate instance. If repair is not appropriate, dry-run the selected removal and remove only the intended instance.
  6. Re-enroll with a fresh identity when required. Generate a new bootstrap command only after the stale local instance is removed, identity recreation is intentional, or support confirms that re-enrollment is the right path.

Do not delete broad system directories, copy identity files between machines, or reuse an old enrollment command. Contact support when the endpoint hosts critical workloads, the cleanup list is ambiguous, or the only working administrative path depends on the agent being repaired.

Identity-preserving repair commands​

Windows:

.\cleanup-agent-windows.ps1 -Diagnose
.\cleanup-agent-windows.ps1 -Repair -Select 1 -DryRun
.\cleanup-agent-windows.ps1 -Repair -Select 1 -Yes

Unix-like systems:

sudo sh cleanup-agent-unix.sh --diagnose --select 1
sudo sh cleanup-agent-unix.sh --repair --select 1 --dry-run
sudo sh cleanup-agent-unix.sh --repair --select 1 --yes

Repair preserves the existing endpoint identity. Use identity recreation only when replacement identity is intentional and ordinary repair cannot recover the installation.

.\cleanup-agent-windows.ps1 -RecreateIdentity -Select 1 -ConfirmRecreateIdentity -DryRun
sudo sh cleanup-agent-unix.sh --recreate-identity --select 1 --confirm-recreate-identity --dry-run

Identity recreation removes local identity and certificate material and may require fresh portal enrollment. Review the selected instance before running without dry-run.

Recreate an endpoint identity​

Identity recreation is appropriate after a rebuild, an unrecoverable local identity problem, or removal of a stale or incorrect tenant attachment.

  1. Preserve the endpoint name, organization, last reported version, and any visible error or command result.
  2. Follow the cleanup guide's list and dry-run steps on the endpoint.
  3. Remove only the intended local agent instance.
  4. Generate a fresh bootstrap command for the correct tenant, organization, platform, and architecture.
  5. Verify the new heartbeat, version, and first audit before running operational actions.

The re-enrolled endpoint may appear as a new portal identity while the prior record remains available for history or retirement. If record continuity matters, stop before deleting either record and contact support with both endpoint identifiers.

Relocation and reconnect fallback boundaries​

Where the portal exposes Platform → Server → Agent Connectivity, an authorized server or platform owner can configure validated public and internal agent endpoints and select Save and notify agents.

Agents retain the endpoint that last worked and automatically try the other configured endpoint after a connection or TLS failure. This is reconnect fallback, not uninterrupted session failover. An offline agent cannot receive a newly queued endpoint list.

Every advertised URL must use HTTPS, remain reachable, and be covered by the server certificate. Retain the currently working endpoint until representative agents report fresh heartbeats. Use diagnosis and identity-preserving repair before considering removal or identity recreation.

Do not manually edit service URLs, certificates, trust bundles, or identity files using an unverified procedure. Contact support before a planned relocation or when the current service destination is unavailable. Include the endpoint identity, platform, current destination, last heartbeat, and whether you retain local administrative access.

The expected outcome of a supported relocation is a fresh heartbeat from the same intended endpoint after the destination and trust path are confirmed. Recovery time and identity continuity are not guaranteed.

Escalate with useful evidence​

Contact support when:

  • cleanup output is ambiguous or shows multiple active-looking identities;
  • an update was accepted but the endpoint did not return with the target version;
  • a certificate, trust, tenant, or organization mismatch remains after verification;
  • a relocation or service outage requires destination changes; or
  • repair could interrupt the only administrative path to a critical endpoint.

Provide the endpoint name and identifier, tenant and organization, platform and architecture, current and target agent versions, last heartbeat, the action attempted, your effective role, and the visible error or result stage. Do not send private keys, bootstrap secrets, or raw identity material.