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. Clean up one damaged or duplicate instance. Use Agent cleanup and removal to list local agents, dry-run the selected removal, and remove only the intended instance.
  5. Re-enroll with a fresh identity when required. Generate a new bootstrap command only after the stale local instance is removed 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.

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 failover boundaries​

Changing an agent's service destination or configuring an alternate endpoint is an advanced support-assisted workflow. It is not automatic failover, and reconnect behavior depends on the endpoint's current trust, network reachability, and deployed service configuration.

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.