Indicates that a new or existing Link Agent instance has been started up
Request body
UUID for this Link Agent instance
Time at which the Link Agent was created
The principal that registered this Link Agent — normally the API key the agent runs under. Server-set from the authenticated caller; supplying it is ignored. Activity feed attribution reads this, so an agent without it is reported as having been registered by mabl itself.
Time at which the Link Agent record last changed
The principal behind the most recent change to this Link Agent — the API key for a status change reported by the agent, or the user who started or ended a maintenance window. Server-set from the authenticated caller; supplying it is ignored.
Time at which the Link Agent was stopped or removed
Time at which the Link Agent last sent a heartbeat
The version of the Link Agent software that this instance is running
Which Link Agent distribution an instance is — the Java Link Agent (java) or the mabl-cli Link Agent (mabl_cli).
Whether a newer Link Agent release than this agent's version is available for download. Computed for the Java distribution only — the mabl-cli distribution self-updates via its own channels and its version is not comparable to Java releases. Server-computed on read; absent when it cannot be determined (the mabl-cli distribution, an unknown or unparseable agent version, or the release inventory being unavailable).
The newest released Link Agent version, present whenever update_available is computed
The user-provided label for this Link Agent instance
Optional point of contact (a name or email address) for this Link Agent, supplied by the operator via config file or command-line at startup. Surfaced so support can tell who to contact about a given Agent. Free-form — not validated as an email.
Flag indicating whether the agent was started with SSL verification disabled
DEPRECATED - Not used as of Link 2.0
The Link Agent instance's local hostname
Opaque persisted per-machine identity — a mabl-minted UUID stored in the standard OS-specific mabl config directory — required when announcing a personal (user-owned) tunnel. The server derives the tunnel's label from it (SHA-256 of machine_identity ":" link_infrastructure_key, lowercase hex, truncated to the 24-char label limit), so one machine keeps one stable tunnel identity per cluster across restarts, reboots, and hostname changes. Not used for workspace- or company-owned agents.
Personal (user-owned) announces only. On request: the explicit placement choice when the user's workspace associations resolve to more than one link infrastructure — the ambiguous announce fails with an error naming the candidate keys, and the shared cluster's key is always a valid choice. Omit when the associations are unambiguous. On response: the resolved placement recorded for this agent's tunnel. Ignored for workspace- and company-owned agents, whose placement derives live from the owning company.
The Link Agent instance's local IP address
Value of the 'java.version' Java system property
Value of the 'java.vm.name' Java system property
Value of the 'os.arch' Java system property
Value of the 'os.name' Java system property
Value of the 'os.version' Java system property
Number of CPU cores available to the Agent host — the headroom denominator for CPU utilization.
Total physical memory on the Agent host, in bytes — the headroom denominator for memory utilization.
Protocol the Link Agent uses to reach the mabl side. Legacy values (pre-mablnet): - wss: WebSocket over TLS to a Link Server (the only one of the three that shipped — ssl and https are historical placeholders).
- ssl, https: never implemented; kept in the enum for backwards compatibility with serialized records that captured them.
New values (mablnet): - mablnet_wss: WSS carrier to a mablnet Router (the production default for mablnet-capable Agents). Goes through the Application LB on :443.
- mablnet_quic: UDP/QUIC carrier. Reserved for future use; not externally exposed in v1 (the Router's UDP carrier is loopback-only for the in-process operator-tenant Host). Defined here so the enum is stable when UDP carriers ship.
The set of protocols this Link Agent is currently attempting to keep connections open for. Successor to the singular protocol field. A dual-stack Agent during the mablnet migration reports both wss (legacy Link Tunnel) and one of the mablnet_* values; mabl ops watches this set to determine which accounts are migration-eligible.
Optional behaviors this Link Agent supports. Reported by the Agent at startup. Operator endpoints that depend on Agent-side handling (POST /link/agents/{id}/maintenance, etc.) reject requests when the relevant capability is missing — older Agents that predate the capability simply omit it.
DEPRECATED: legacy single-protocol connection state. Agents reporting protocols populate endpoints with per-protocol connection state; this field stays populated as true if any of the per-protocol states are connected.
DEPRECATED: legacy single-Link-Server binding. Mablnet Agents are not bound to a single Server — they multi-home across Routers. Stays populated for legacy Agents.
DEPRECATED: legacy single-endpoint field. Use endpoints[wss].address for the same value; the legacy field stays populated for pre-mablnet Agents that don't yet understand the endpoints map.
Per-protocol endpoint the Link Agent should connect to, keyed by protocol name (matches LinkAgentProtocolEnum). Legacy Link Tunnel Agents only see (and need) the wss entry, which mirrors current_link_server_endpoint. Mablnet-capable Agents additionally see mablnet_wss and (when UDP/QUIC is exposed externally) mablnet_quic, pointing at the Application LB FQDN for this environment. api-set and read-only from the client perspective: the value flows api → Agent. Per-protocol connection health flowing the other direction (Agent → api) is reported via connection_status. Computed on every read from the LinkLabel + workspace migration flags + deployment config (com.mabl.mablnet.domain + the owner's link infrastructure key); NOT persisted on the LinkAgent itself. A feature-flag flip, FQDN change, or LinkLabel-level update propagates to running Agents on their next poll (≈ 10 s), with no agent restart and no backfill cron. Downstream consumers that need the same view (BigQuery, Pub/Sub) should read via the api rather than the raw DAO entity.
Per-protocol connection health, keyed by protocol name (same keys as endpoints). Reported by the Agent on heartbeat and merged in.
Denormalised view of LinkLabel.mablnet_tenant_id for this Agent's label. Computed on every read alongside endpoints (see that field's description for the full server-set-fields contract); NOT persisted on the LinkAgent. Tenant ids themselves are immutable for a LinkLabel's lifetime, so the value is stable across reads in practice.
Zero-padded 8-character lowercase hex form of mablnet_tenant_id, e.g. bee85e2b. Provided for log/grep/observability ergonomics; the numeric and hex forms always agree (both computed together). Same lifecycle as mablnet_tenant_id — computed on every read, not persisted.
The current status of the Link Agent
The workspace that owns this Link Agent, for workspace-owned tunnels. Unset for company-owned agents (mablnet-only) — read owner_type/owner_id for the canonical scope.
The kind of entity a mablnet tunnel is scoped to — its "owner". workspace is the classic scope: one tunnel per workspace. company scopes a single tunnel to an entire company, so every workspace under that company shares one mablnet tenant (and one Link Agent fleet) instead of needing a tunnel each. user is a personal tunnel scoped to a single user, private to that user — its egress is the user's own machine, used to route a cloud test run through it. All three are mablnet-only: legacy Link Tunnel is always workspace-scoped.
The id of the owning entity — equals workspace_id for workspace-owned agents, the company id for company-owned agents.
Response
Complete information about the Link Agent that was started
UUID for this Link Agent instance
Time at which the Link Agent was created
The principal that registered this Link Agent — normally the API key the agent runs under. Server-set from the authenticated caller; supplying it is ignored. Activity feed attribution reads this, so an agent without it is reported as having been registered by mabl itself.
Time at which the Link Agent record last changed
The principal behind the most recent change to this Link Agent — the API key for a status change reported by the agent, or the user who started or ended a maintenance window. Server-set from the authenticated caller; supplying it is ignored.
Time at which the Link Agent was stopped or removed
Time at which the Link Agent last sent a heartbeat
The version of the Link Agent software that this instance is running
Which Link Agent distribution an instance is — the Java Link Agent (java) or the mabl-cli Link Agent (mabl_cli).
Whether a newer Link Agent release than this agent's version is available for download. Computed for the Java distribution only — the mabl-cli distribution self-updates via its own channels and its version is not comparable to Java releases. Server-computed on read; absent when it cannot be determined (the mabl-cli distribution, an unknown or unparseable agent version, or the release inventory being unavailable).
The newest released Link Agent version, present whenever update_available is computed
The user-provided label for this Link Agent instance
Optional point of contact (a name or email address) for this Link Agent, supplied by the operator via config file or command-line at startup. Surfaced so support can tell who to contact about a given Agent. Free-form — not validated as an email.
Flag indicating whether the agent was started with SSL verification disabled
DEPRECATED - Not used as of Link 2.0
The Link Agent instance's local hostname
Opaque persisted per-machine identity — a mabl-minted UUID stored in the standard OS-specific mabl config directory — required when announcing a personal (user-owned) tunnel. The server derives the tunnel's label from it (SHA-256 of machine_identity ":" link_infrastructure_key, lowercase hex, truncated to the 24-char label limit), so one machine keeps one stable tunnel identity per cluster across restarts, reboots, and hostname changes. Not used for workspace- or company-owned agents.
Personal (user-owned) announces only. On request: the explicit placement choice when the user's workspace associations resolve to more than one link infrastructure — the ambiguous announce fails with an error naming the candidate keys, and the shared cluster's key is always a valid choice. Omit when the associations are unambiguous. On response: the resolved placement recorded for this agent's tunnel. Ignored for workspace- and company-owned agents, whose placement derives live from the owning company.
The Link Agent instance's local IP address
Value of the 'java.version' Java system property
Value of the 'java.vm.name' Java system property
Value of the 'os.arch' Java system property
Value of the 'os.name' Java system property
Value of the 'os.version' Java system property
Number of CPU cores available to the Agent host — the headroom denominator for CPU utilization.
Total physical memory on the Agent host, in bytes — the headroom denominator for memory utilization.
Protocol the Link Agent uses to reach the mabl side. Legacy values (pre-mablnet): - wss: WebSocket over TLS to a Link Server (the only one of the three that shipped — ssl and https are historical placeholders).
- ssl, https: never implemented; kept in the enum for backwards compatibility with serialized records that captured them.
New values (mablnet): - mablnet_wss: WSS carrier to a mablnet Router (the production default for mablnet-capable Agents). Goes through the Application LB on :443.
- mablnet_quic: UDP/QUIC carrier. Reserved for future use; not externally exposed in v1 (the Router's UDP carrier is loopback-only for the in-process operator-tenant Host). Defined here so the enum is stable when UDP carriers ship.
The set of protocols this Link Agent is currently attempting to keep connections open for. Successor to the singular protocol field. A dual-stack Agent during the mablnet migration reports both wss (legacy Link Tunnel) and one of the mablnet_* values; mabl ops watches this set to determine which accounts are migration-eligible.
Optional behaviors this Link Agent supports. Reported by the Agent at startup. Operator endpoints that depend on Agent-side handling (POST /link/agents/{id}/maintenance, etc.) reject requests when the relevant capability is missing — older Agents that predate the capability simply omit it.
DEPRECATED: legacy single-protocol connection state. Agents reporting protocols populate endpoints with per-protocol connection state; this field stays populated as true if any of the per-protocol states are connected.
DEPRECATED: legacy single-Link-Server binding. Mablnet Agents are not bound to a single Server — they multi-home across Routers. Stays populated for legacy Agents.
DEPRECATED: legacy single-endpoint field. Use endpoints[wss].address for the same value; the legacy field stays populated for pre-mablnet Agents that don't yet understand the endpoints map.
Per-protocol endpoint the Link Agent should connect to, keyed by protocol name (matches LinkAgentProtocolEnum). Legacy Link Tunnel Agents only see (and need) the wss entry, which mirrors current_link_server_endpoint. Mablnet-capable Agents additionally see mablnet_wss and (when UDP/QUIC is exposed externally) mablnet_quic, pointing at the Application LB FQDN for this environment. api-set and read-only from the client perspective: the value flows api → Agent. Per-protocol connection health flowing the other direction (Agent → api) is reported via connection_status. Computed on every read from the LinkLabel + workspace migration flags + deployment config (com.mabl.mablnet.domain + the owner's link infrastructure key); NOT persisted on the LinkAgent itself. A feature-flag flip, FQDN change, or LinkLabel-level update propagates to running Agents on their next poll (≈ 10 s), with no agent restart and no backfill cron. Downstream consumers that need the same view (BigQuery, Pub/Sub) should read via the api rather than the raw DAO entity.
Per-protocol connection health, keyed by protocol name (same keys as endpoints). Reported by the Agent on heartbeat and merged in.
Denormalised view of LinkLabel.mablnet_tenant_id for this Agent's label. Computed on every read alongside endpoints (see that field's description for the full server-set-fields contract); NOT persisted on the LinkAgent. Tenant ids themselves are immutable for a LinkLabel's lifetime, so the value is stable across reads in practice.
Zero-padded 8-character lowercase hex form of mablnet_tenant_id, e.g. bee85e2b. Provided for log/grep/observability ergonomics; the numeric and hex forms always agree (both computed together). Same lifecycle as mablnet_tenant_id — computed on every read, not persisted.
The current status of the Link Agent
The workspace that owns this Link Agent, for workspace-owned tunnels. Unset for company-owned agents (mablnet-only) — read owner_type/owner_id for the canonical scope.
The kind of entity a mablnet tunnel is scoped to — its "owner". workspace is the classic scope: one tunnel per workspace. company scopes a single tunnel to an entire company, so every workspace under that company shares one mablnet tenant (and one Link Agent fleet) instead of needing a tunnel each. user is a personal tunnel scoped to a single user, private to that user — its egress is the user's own machine, used to route a cloud test run through it. All three are mablnet-only: legacy Link Tunnel is always workspace-scoped.
The id of the owning entity — equals workspace_id for workspace-owned agents, the company id for company-owned agents.