Identifiers

Use this page to read an OpenLatch identifier: what it names, how it is made, where it appears, and which changes to a machine give it a new one.

Hosts, agents, sessions and events

Below your organization, OpenLatch knows three entities and the events they produce. Each has one identifier, with one name and one format wherever it appears: in the console, in the public REST API, in the events the client sends and in the client’s output.

Entity	Prefix	What it names	How it is made
Host	hst_	One operating system in your organization, one container life, or one clone of a machine image. Hosts are what your license counts	Derived on the machine from its operating-system identifier, or chosen at random where there is none to trust
Agent	agt_	One agent product, such as Claude Code or Codex CLI, used by one operating system user on one host, and each profile registered there. Sessions in parallel in one profile stay one agent	Derived from the organization, the host and the agent product, plus an instance identifier for every user but the host’s first and for a registered profile, so the client and the platform compute the same value
Session	ses_	One conversation of one agent	Derived from the agent and the session identifier the agent itself gave
Event	evt_	One event the client sends	Chosen at random by the client. The platform stores an event once per identifier

Each agent fetches the policies of its own Autonomy Zone, so two agents on one host can run under different zones and each is decided with its own.

Agents on a shared machine

The first operating system user to report from a host keeps the Agent ID they had, in their default profile, and every earlier client keeps working on that agent. Every other user of the host, and every registered profile, gets an Agent ID of its own.

Rule	Detail
Instance identifier	The events of such an agent carry an olinstance attribute: a pseudonym derived from the operating system user and, for a profile, from its directory. It holds no name and no path, but it is keyed by a constant shipped in every client, so it is not anonymized. It is sent with identity signal capture off too
Check	The platform derives the Agent ID again from the attribute and refuses a request whose Agent ID does not match, or that names another user than its host credential’s, with HOST_MISMATCH
Who is first	The platform decides which user is the host’s first, once, and the answer never changes. Until the client has that answer, its events stay on the default agent, and openlatch doctor shows it as pending with OL-1257
No user name	A client that can read no operating system user name stays on the default agent, and openlatch doctor reports it with OL-1305
Test variable	OPENLATCH_TEST_OS_USER overrides the operating system user, and so the agent and its zone. openlatch doctor reports it whenever it is set, with OL-1306

Format

Every identifier is a three-letter prefix, an underscore and 26 characters of lowercase base32: the digits and the letters other than i, l, o and u. The prefix says what the identifier names.

agt_01jbz3q7x2k9m4n5p6r7s8t9v0

Rule	Detail
Display	The console shows an identifier in full, or shortened to its prefix and first eight characters; its copy button always copies the full value
A malformed identifier	A request that passes an identifier with the wrong prefix for its field, the wrong length or a character outside the alphabet is refused with INVALID_ID, which names the field
An unknown identifier	A well-formed identifier that does not exist, or that belongs to another organization, gets the same not-found answer either way
Not a secret	Host, agent and session identifiers are computed from what they name, so they are never credentials. An API key is a secret: it begins with openlatch_ or, in the newer format, olk_, and the platform accepts both

Where each identifier appears

Entity	Field in the public REST API	Attribute of an event the client sends
Host	host_id	hostid
Agent	agent_id	agentid
Session	session_id	subject
Event	event_id	id

The console labels the host and agent identifiers Host ID and Agent ID.

The agent product is platform in the public REST API, such as claude-code or codex-cli, and the grouping your organization gives an agent is its category. In the public REST API, where a field holds an identifier the agent itself gave, its name says so: native_session_id is the agent’s own session identifier. Your organization never appears in an event: the platform takes it from the credential that sent the event.

What gives a host a new identifier

A host keeps its identifier for as long as its operating system and its organization stay the same. These changes to a machine decide whether it keeps its host, and its agents and sessions follow their host.

Change	Host	History in the console
Uninstall, then reinstall	Same	Continuous
Uninstall with --purge, then reinstall	Same on a machine with an operating-system identifier; new on a host whose identifier was chosen at random	Continuous when the host stays the same; otherwise it stays under the old host
Operating system reinstalled, or a new machine identifier	New	Stays under the old host
Switch to another organization	One host per organization; switching back reuses that organization’s host	Each organization keeps its own
Clone of a machine image that was prepared	New for every clone, on its first start	Each clone starts empty
Clone of a machine image that was not prepared	Shared with the original until both run at the same time; the later one then gets a new host, and the host shows Possible duplicate for a while	The original keeps it; the clone starts empty
Container that keeps no state directory	New every time the container starts	Each start begins empty

Prepare a machine before you capture it as an image with openlatch system prepare-image; see Deploy the client. Inside a container the client ignores the machine identifier, because an image can carry one baked in. Toolbx, Distrobox, Flatpak and the Windows Subsystem for Linux share the machine’s identifier and count as the machine itself. A second install on the same machine with its own state directory, set by OPENLATCH_DIR, gets a host of its own, and its agents never merge into the machine’s.

A host that is no longer seen stops counting toward your licensed hosts after 30 days, and its history stays in the console; see Read licensing and usage.

Clients older than these identifiers

A client older than version 0.10.0 is no longer supported. The platform refuses its events as client_too_old and its other requests with HOST_ID_REQUIRED, and it keeps enforcing the policies it already holds. Reinstall the client on that machine with one of the install commands; see Install the client.

When a machine moves to a supported client, the client reports the machine’s previous identity once, before it sends any event, and OpenLatch moves the machine’s agents, with their owners, zones and history, to the new identifiers. Until that report is accepted, events wait on the machine and the policies it holds keep being enforced, and openlatch doctor shows the report as pending with OL-1253.