Your first server connection should end with verification
A simple install starts in the correct workspace and finishes with a verified server identity and fresh evidence. Follow the practical decisions behind the guided agent connection flow.
Published 5 November 2026. Hostwatch engineering review; implementation limits are stated below.
Start with the account that will own the server
A short installation command can hide a long list of assumptions. It may select an account, choose a network address, install a privileged service and create a credential that continues working after the terminal closes. Making that command easy to copy is useful, but the operator still needs to know what relationship it creates. The first installation decision is therefore the destination workspace. Open the correct Hostwatch control plane and confirm the account and company before generating a connection key. This prevents the frustrating situation in which a correctly installed agent reports to a workspace the intended administrators cannot see or operate.
Cloud customers use gethostwatch.com with an entitled workspace subscription or applicable trial. Private Enterprise customers use the origin supplied by their installation administrator and the annual installation license already governing that central application. The private model does not require an additional Cloud subscription. Both install the same Go agent component on owned servers. In either case, installation alone should not enroll unrelated hosts, share compute or import an operator's existing fleet. Name the new server clearly enough to recognize it later, including a role or location where that helps the team. The name is a human aid; the verified persistent server identity will establish which machine the connection actually reaches.
Confirm the supported host before generating a command
The quick installer targets Ubuntu or Debian with systemd on Linux x86-64 or ARM64. The operator needs authorized root or sudo access through their own SSH connection. Check the operating system, architecture and available disk space before treating a failed package command as an application defect. A newly provisioned virtual machine is a straightforward environment for this path. An existing production host can also work, but its agent and reverse-proxy ownership need inspection first. The installer deliberately refuses an existing agent or conflicting configuration instead of assuming that replacing a familiar filename is harmless to the workloads already on the machine.
Record the provider address and expected host identity through the normal provisioning channel. SSH access should reach the intended server rather than a recycled address or an old profile with a similar name. If another administrator provisioned the machine, confirm the login they supplied and the authorized public key. Hostwatch's browser pairing flow does not replace SSH authorization. It supplies a temporary installer for a relationship the workspace owner is creating; it does not grant general access to a cloud account. Keeping these steps distinct also makes troubleshooting direct: a rejected SSH key belongs to the host access setup, while an expired installer belongs to the workspace pairing flow.
Give the agent a dedicated hostname
The simplest supported network arrangement uses a dedicated DNS hostname for the agent's HTTPS endpoint. This might be a monitoring subdomain chosen by the organization, rather than the application's existing public hostname. Point its records at the intended server and consider every configured address family. An obsolete IPv6 record can send some clients and certificate checks elsewhere even when the IPv4 record looks correct. Use the authoritative DNS view to establish the intended record, then allow for resolver caches during a change. A successful lookup from one laptop is useful evidence, yet it does not prove that the entire public validation path now reaches the new host.
The quick path needs the documented HTTP and HTTPS reachability for its certificate and proxy arrangement. It installs a dedicated Nginx route and uses an HTTP certificate challenge, so the challenge URL must be publicly reachable on the expected HTTP route. Certbot's webroot documentation explains how the challenge file is served from the selected webroot. A DNS record hidden behind an unexpected proxy or a blocked port can prevent issuance. Advanced manual setup is the right place for an existing custom proxy, private routing or a different certificate strategy. Choose that path deliberately rather than repeatedly running the quick installer against a network layout it was not designed to configure.
Generate the short-lived command in the console
In Connect & help, create the server pairing entry and provide the dedicated hostname. The console returns a short-lived installation command and the expected agent address. This command is connected to the current owner, enrollment and entitlement; it is not a reusable public credential for any future server. Copy it into the authorized SSH session for the selected machine. Treat its embedded URL as a credential during its validity window. Avoid posting it in an issue, shared build log or unrelated assistant conversation. The public guide can show the shape of the process without publishing a live command that grants access to a real workspace.
The installer ticket lasts twenty minutes and limits delivery of the script and architecture-specific binary. If the command expires or is consumed before installation begins, replace it from the pairing flow instead of trying to reconstruct its secret portion. Generating a new installer invalidates the previous installer link for that enrollment. This makes an abandoned command less useful while leaving the operator with a clear recovery action. The server's long-term agent token has a different purpose and lifetime. After setup, manage that credential through the supported connection controls rather than assuming the expiration of the download link also revokes an installed agent's management relationship.
Understand what the installer changes
The command selects the supported Linux architecture, retrieves the corresponding official agent package and verifies the binary checksum bound to the ticket. It installs the agent's license and third-party notices with the executable. The agent receives a dedicated system service and protected configuration rather than living inside an application's source directory. Its local listener is separate from the public HTTPS route. The quick path configures the dedicated reverse proxy and certificate needed for that route. These are concrete changes to the monitored server, so the installation should be performed by the person or team responsible for its operating system and public network configuration.
The installer performs preflight checks for an existing agent, service configuration and conflicting proxy ownership. A refusal is a useful boundary, particularly on a host that already serves several products. It should lead to inspection or advanced setup, not to deleting files until the command happens to proceed. If certificate issuance fails, the recovery guidance distinguishes a partially installed local agent from a completed public connection. Read that result before repeating the command. The quick path does not promise that every distribution, reverse proxy and existing filesystem layout can be repaired automatically. Clear prerequisites and specific recovery instructions make a simple installation safer to repeat across a fleet.
Verify the connection after the terminal finishes
A successful shell exit is one installation result; a verified management relationship is another. Return to the console and use Verify and connect for the expected HTTPS agent address. The control plane checks the connection against the pairing credential and persistent server identity. Confirm that the resulting entry matches the machine you intended to add. Then look for a recent sample timestamp and sensible host measurements. A familiar display name or green badge alone is insufficient when a DNS record may still point at an older machine. The final verification connects account intent, server identity and fresh evidence in one place.
Use an observation that has a concrete meaning. Current CPU and memory evidence shows that the agent is collecting host data. Runtime inventory can show the containers or services the local configuration exposes. A configured workload health response adds evidence about that workload. These checks answer different questions, so choose a small combination that reflects the server's actual role. A newly installed empty server need not invent application data to look complete. If its first sample is missing, inspect service state, local logs and the management route before declaring success. A stale saved observation should remain clearly labeled while the current connection is being repaired.
Leave the application request path understandable
Hostwatch's hosted control plane coordinates management outside the application's normal request path. The product can receive telemetry and ask an agent to perform a permitted local operation without acting as the universal reverse proxy for customer traffic. The customer's application still receives traffic at its own origin or through the edge provider the customer chooses. This architecture makes address labeling important. The agent hostname should not be mistaken for the product's public hostname, and a management certificate should not be reported as proof that every application domain has a valid certificate. Keep the network diagram simple enough that a new operator can identify both routes.
Installing an agent also does not transfer domain ownership or replace upstream network protection. The infrastructure owner remains responsible for provider-level reachability, DNS, TLS and the applications exposed on the host. When adding service controls later, register only the routes and runtime targets the organization intends Hostwatch to manage. Verify the exact boundary in both the console and the runbook. A server can have healthy management connectivity while an application route fails, or a healthy public site while management access is interrupted. Recording those states separately prevents a one-word online label from hiding the particular connection that actually needs attention.
Make failure recovery a continuation of setup
An installation guide should explain likely next actions without forcing the operator to guess which step completed. If DNS validation fails before installation, fix the record or choose the documented advanced route. If an existing agent is detected, inspect its configuration and ownership before planning an upgrade or replacement. If the certificate step fails after the local service is installed, follow the recovery path for that installed service rather than starting a second enrollment. If Verify and connect fails, check the expected address, certificate trust, pairing token and persistent identity. Each case has a different cause, and repeating the entire sequence can make the state less clear.
Keep sensitive diagnostics private while retaining enough information to explain the failure. Save the hostname, stage, non-secret error and observed service state; avoid copying token values or private environment files into a support note. When another administrator takes over, tell them whether a local agent exists and whether the workspace connection was completed. That small distinction prevents duplicate installation and accidental credential replacement. After recovery, repeat the identity and fresh-sample checks that define completion. The useful success criterion is not that the terminal stopped printing errors. It is that the correct workspace can reach the intended agent and display current evidence from the intended server.
Plan ordinary maintenance after first connection
Certificate renewal and agent software upgrades have different purposes. The quick path configures certificate maintenance for the route it creates, while software releases remain explicit operator actions. There is no installed CI/CD pipeline, Git deployment trigger or background application updater. The server owner should still know how the service starts after reboot, where protected configuration lives and which recovery material needs backup. Store the runbook with the team that administers the host. A one-command installation is a useful beginning, but operational simplicity over the next year depends on making the ongoing responsibilities as clear as the initial command.
Finish by reviewing the connected server from the surfaces the team will actually use. The web console and native app should show the same identity, role and recent measurements. An authorized MCP assistant should find the node and its real service placements without inventing unsupported controls. Cloud entitlement should belong to the intended workspace; a private installation should show its license model without a Cloud upsell. Once these facts agree, the installation has produced something dependable: a server the team can identify, observe and operate through the configured capabilities. The full step-by-step connection guide remains available for the next server, including advanced setup and recovery when the simple path does not fit.
Use the guided Name → Install → Verify flow on a supported host. Finish by checking the intended workspace, persistent server identity, HTTPS route and recent measurements.