Pitfalls to avoid

Read this page before each stage of the deployment. Every row names what you see when the pitfall bites, how to avoid it, and the page that holds the full procedure. The first five rows of the start page are the ones that stall the most deployments.

Before your organization arrives

Pitfall	What you see	Avoid it	Details
An egress rule that allows the console but forgets the install-time destinations	The install fails before the client ever reaches the console, and it looks like a broken product rather than a closed route	Allow the package registry or your mirror, openlatch.ai for the install scripts, and github.com for an install through npm	Network requirements
Allowlisting by IP address	The route works for a while, then breaks	There is no static address range. Allowlist app.openlatch.ai by name and SNI	Network requirements
An NTLM-only proxy	The client cannot authenticate to the proxy on any machine	NTLM is not supported, by design. Plan a Kerberos (Negotiate) or unauthenticated path for the client before the first wave	Network requirements
A proxy auto-config file on Linux	The install refuses the auto-config route	Set the route explicitly on Linux. Auto-config is evaluated by the operating system on Windows and macOS only	Network requirements
Model endpoints buffered or stream-inspected by a proxy	The agent appears to stall, then prints everything at once	Keep the endpoints your agents already reach exempt from response buffering and streaming inspection	Network requirements
An unsupported platform in the wave	The install has no package for the machine	Windows on ARM64 and musl-based Linux distributions such as Alpine are not supported. Check the floors in the checklist	Prerequisites checklist
A shared machine treated as one install	Only the person who installed is covered	Install and local state are per user. Each user of a shared machine runs an install of their own	Prerequisites checklist

When your organization arrives

Pitfall	What you see	Avoid it	Details
Signing in for the first time without the invitation, or from another address	The console walks you through creating a new organization instead of opening yours	Open the invitation link, from the address you gave your OpenLatch contact	First steps in the console
An administrator’s browser cannot reach challenges.cloudflare.com	The sign-in check fails every time	Allow it for the browsers that sign in to the console. No machine running the client needs it	Network requirements
Waiting for the setup wizard to appear	The invited owner of an organization OpenLatch created never sees it on their own	Open it from Home › Reopen setup	First steps in the console
Trusting the single sign-on connection test alone	The test passes, and people still cannot sign in	The test only checks that the identity provider’s metadata URL or sign-on URL answers. Save first, then test, then sign in through SAML yourself in a private window before you invite anyone	First steps in the console
Allowed email domains set too broadly	People you did not invite register into the organization	Keep the domains narrow, and admit everyone else by invitation	First steps in the console
Enrolling a fleet with a personal key	A personal key cannot hold host:enroll, only its owner can see it, and it stops working when that person leaves	Create an organization key from Host enrollment on Settings › API keys, one per wave	First steps in the console
Turning off Collect identity signals from endpoints	No agent is ever matched to an owner	Leave the switch on wherever you want agents attributed to a person	First steps in the console
Leaving audit retention at its default	Records past the window are purged every 24 hours once auto-purge is on	Set the retention window and auto-purge before the rollout starts	First steps in the console

Rolling out

Pitfall	What you see	Avoid it	Details
Revoking a wave’s key before its machines run the current client	A machine on an earlier client still authenticates with the key: it stops collecting updates, and the console refuses its key (OL-1201)	The current client trades the key for a host credential of its own and no longer uses it once enrolled. Let the wave update before you revoke its key	Plan the rollout
A key passed on a command line	The client refuses it	Supply it from your secret store as a key file, through --api-key-file or OPENLATCH_API_KEY_FILE, or through the environment as OPENLATCH_API_KEY. Treat a deployment script’s body as readable	Deploy the client
A proxy route held only in the installing shell’s variables	The machine goes direct after the next restart	The client starts with the user’s session and inherits none of the shell’s variables. Let the install record the route, or hand it over with openlatch init --proxy	Deploy the client
A proxy password inside the proxy URL	The client refuses the URL	Supply the credential through OPENLATCH_PROXY or the prompt, which moves it into an encrypted file readable only by its owner	Deploy the client
A proxied host without a loopback bypass	The agent’s calls to the client leave for the corporate proxy, which answers with an error	Export NO_PROXY=127.0.0.1,localhost in the shell that launches the agent, where the agent does not receive the entry at install	Deploy the client
Installing the client before the agents	An agent installed afterwards is not connected	Install the agents first, or run openlatch init again afterwards. A repeat is never destructive	Deploy the client
An unattended install without --yes, or without a key	The enrollment cannot prompt, and stops with OL-1600	Run openlatch init --yes with an enrollment key: --api-key-file, OPENLATCH_API_KEY_FILE or OPENLATCH_API_KEY. Name the organization with --org where the account belongs to several	Deploy the client
Deploying through browser sign-in	Every machine waits for a person with a console account at a terminal, and an unattended install stops with OL-1600	Deploy with an organization key, the pilot included. Browser sign-in is for trying OpenLatch, or for one person on their own machine	Deploy the client
A key typed on a command line for a hand install	The key lands in your shell history	Read it into OPENLATCH_API_KEY without typing it on the line, and clear the variable after the install	Deploy the client
Intune treated like an interactive installer	Machines are skipped or installed days later	Run a user-context script that fetches the key itself, expect assignments over days, and use the Win32 app where a machine gets its first agent after the script’s retries end	Deploy the client
A Jamf policy that runs as root	A Jamf policy normally runs its scripts as root, so the client installs and enrolls for root instead of the developer	Resolve the user logged in at the console and run the install and the enrollment as that user, with launchctl asuser and sudo -u. Exit with an error when nobody is logged in, so the next check-in retries	Deploy the client
Widening a wave too early	Problems found in wave 1 repeat across fifty machines	Widen only once a wave meets its exit criteria, and run a managed install against a sample before the full run	Plan the rollout

Verifying

Pitfall	What you see	Avoid it	Details
A machine that is running and covering nothing	The client is up and the console holds a record, but one agent was never wired	Count a machine as done only when openlatch doctor reports no problem	Verify each machine and wave
An agent still waiting for its developer	The agent is connected on paper and not in practice	Some agents ask the developer to confirm the connection once. Chase those before closing a wave	Verify each machine and wave
Expecting the machine in the console at once	The machine is missing right after install	It appears within 24 hours, and within minutes on a healthy network. A last-seen time that stops moving points at the route	Verify each machine and wave
Following a sign-in remedy on a deployed machine	openlatch doctor names openlatch system auth login, and the person on the machine has no console account	Run openlatch init --yes with an organization key instead	Deploy the client
Expecting an owner with no directory connected	The agent is recorded as unattributed	Connect a directory, or have an editor name the owner by hand	First steps in the console

Operating

Pitfall	What you see	Avoid it	Details
Updating the files without restarting the client	The machine reports a version mismatch	End the maintenance window with openlatch restart, or the sign-out and sign-in your estate already schedules	Operate
Pinning the version and turning off the check too	Machines stop reporting that a newer version exists	Pin with OPENLATCH_AUTO_UPDATE=false and leave OPENLATCH_UPDATE_CHECK on	Operate
A long outage	Past the 100 MB cap, the oldest unsent records are dropped, with an OL-1204 warning in the log	Restore the route before the cap is reached; the policies keep deciding meanwhile	Operate
Treating a purge as a removal	The installed files and the PATH line stay on the machine	openlatch uninstall --purge removes the state directory and the stored credential. Delete the installed files separately	Uninstall
Deleting an agent in the console before uninstalling	The agent comes back with the next event	Remove the client from the machine first	Uninstall
A scheduled re-run of the install on a host you cut off	Endpoint management that reruns the install enrolls the host again, and it counts again	Guard the recipe so that it enrolls once: it leaves a marker and skips the enrollment when it finds one. Otherwise take the machine out of the policy’s scope, or revoke the key it enrolls with, before you choose Cut it off	Deploy the client
Blocking telemetry at the network	The machine loses the console too	Telemetry and crash reports travel with the client’s own traffic. Turn them off on the client instead	Data handling and security
The relay certificate bundle on a public URL, in a repository or in an image layer	Nothing at first; anyone holding it can intercept every machine that trusts it	Keep the bundle in your secret store; import it at run time in containers	Use your organization’s relay certificate
The bundle, with its private key, pushed by device management	The profile installs, and the key reaches every machine’s management channel	Push only relay-ca.cer, the public certificate	Use your organization’s relay certificate
An EC key written with explicit curve parameters, the LibreSSL default on macOS	The install exits 8 with OL-2111	Use the RSA 3072 recipe, or a named P-256 or P-384 curve	Use your organization’s relay certificate
The install run as root or SYSTEM	The relay CA is trusted for the wrong account, and the person at the machine still sees the dialog	Run the install as the machine’s user	Use your organization’s relay certificate
A configuration profile opened by hand on macOS 13 or later	The certificate is not trusted, and the install shows the dialog	Deliver it through device management at computer level, then check with openlatch doctor	Use your organization’s relay certificate