Documentation Index
Fetch the complete documentation index at: https://doc.heex.io/llms.txt
Use this file to discover all available pages before exploring further.
This page is the canonical reference for status semantics across Heex resources, used by CLI, GraphQL, and MCP integrations. End users browsing the web UI should refer to the per-page status sections in the Web Interface which use the UI labels directly.
Overview
Heex resources progress through five distinct status fields. Some fields reuse the same enum but in different contexts (entity-level vs per-system).
| Resource scope | GraphQL field | Enum | Driven by |
|---|
| System (entity-level) | System.status | SystemStatus | Configuration completion and Heex Agent OTA pull |
| Trigger (entity-level) | Trigger.status | TriggerStatus | API, reflects configuration completeness |
| Trigger on a system | SystemTrigger.status | TriggerStatus (reused) | Heex Agent OTA pull on the target machine |
| Implementation (developer page) | Implementation.status | ImplementationStatus | Manual, developer marks Ready when the binary is built |
| Implementation on a system, per signal | SystemSignal.status | ImplementationStatus (reused) | Heex Agent OTA pull on the target machine |
The same enum value can carry different operational meaning depending on the field it appears in. Always interpret a status in the context of its GraphQL field. The TO_DEPLOY to READY transition on System.status, SystemTrigger.status, and SystemSignal.status requires the Heex Agent installed and connected on the target machine; the Heex SDK does not drive it. See Heex Installer Mode. System.status
System.status reflects the overall configuration and deployment state of a system.
| API value | Meaning | UI label |
|---|
TO_CONFIGURE | The system is missing required datasources, triggers, or implementations | To Configure |
REQUESTED | The system has been requested, configuration is in progress | Requested |
TO_CODE | The configuration references implementations that are not yet Ready on the developer page | To Code |
TO_DEPLOY | Configuration is complete and valid, the Heex Agent has not yet pulled it on this machine | To Deploy |
READY | Configuration is present on the Heex Agent running on this system | Deployed |
The terminal value is READY in the API but labeled Deployed in the web UI. This is the only place in Heex where the terminal label differs from the enum name.
Trigger.status
Trigger.status describes the trigger as a configuration entity, independent of any system.
| API value | Meaning | UI label |
|---|
TO_CONFIGURE | No monitoring condition defined, or referenced signals are invalid | Not Ready |
REQUESTED | Trigger creation in progress, not yet complete | Not Ready |
TO_CODE | The trigger references implementations not yet Ready on the developer page (rarely shown at this level) | Not Ready |
TO_DEPLOY | Configuration complete but not yet observed deployed anywhere (rarely shown at this level) | Not Ready |
READY | Configuration is complete and the trigger can be attached to any compatible system | Ready |
READY into a single Not Ready label. The detailed reason is only available through the API.
SystemTrigger.status
SystemTrigger.status describes the deployment progress of a trigger on a specific system. The enum is the same as Trigger.status but only the values below are reachable per-system (TO_CONFIGURE belongs to the entity level).
| API value | Meaning | UI label |
|---|
REQUESTED | The trigger has been attached to the system but the configuration is incomplete | Requested |
TO_CODE | One or more implementations required by the trigger are not yet Ready | To Code |
TO_DEPLOY | All implementations are Ready, the Heex Agent has not yet pulled the configuration on this machine | To Deploy |
READY | The trigger is deployed on the system, the Agent has it and can generate events | Ready |
Trigger.status) but To Deploy on a specific system. This is expected and simply means the Heex Agent on that machine has not yet pulled the latest configuration.
Implementation.status
This field is special because the transition to READY is not automatic; it reflects a deliberate handover from development to operations.
The enum naming for ImplementationStatus is inconsistent: only the first value carries the IMPLEMENTATION_STATUS_ prefix, all others use bare names. This is kept for backward compatibility and is purely a wire-format detail.
| API value | Meaning | UI label |
|---|
IMPLEMENTATION_STATUS_TO_CONFIGURE | Implementation declared but signal mapping not yet provided | Not Ready |
REQUESTED | The system administrator has requested this implementation, the binary is not yet built | Requested |
TO_DEPLOY | Rarely shown on the developer page, included for completeness | To Deploy |
READY | The developer marked the implementation as ready for deployment | Ready |
RUNNING | Reserved, the developer page does not surface this value | (not shown) |
The Ready transition is manual. Either the developer flips it from the developer page, or runs heex implementation validate from the CLI. Unlike other Heex statuses, this one does not progress automatically. See the Implementation CLI command. SystemSignal.status
Per-system implementation status is tracked per (signal, conditionType) pair, not per implementation. Each SystemSignal entry binds a signal, a conditionType (MONITOR or RECORDER), the source implementation, and its deployment status on this system.
| API value | Meaning | UI label |
|---|
IMPLEMENTATION_STATUS_TO_CONFIGURE | Signal mapping incomplete on this system | Not Ready |
REQUESTED | The implementation is not yet Ready on the developer page | Requested |
TO_DEPLOY | Implementation is Ready on the developer page; the Heex Agent has not yet pulled it on this machine | To Deploy |
READY | The implementation is present in the Heex Agent running on this system | Ready |
RUNNING | The implementation is deployed and actively executing on the Agent | Running |
Terminal-state naming convention
The terminal state is named READY in TriggerStatus, ImplementationStatus, and SystemStatus. The web UI labels it as Ready in the Trigger and Implementation contexts, and as Deployed in the System context. All three refer to the same enum value, READY.
| GraphQL field | API terminal value | UI label |
|---|
System.status | SystemStatus.READY | Deployed |
Trigger.status | TriggerStatus.READY | Ready |
SystemTrigger.status | TriggerStatus.READY | Ready |
Implementation.status | ImplementationStatus.READY | Ready |
SystemSignal.status | ImplementationStatus.READY | Ready |
SystemSignal.status | ImplementationStatus.RUNNING | Running |
Driving transitions from the CLI
The transitions you typically drive manually:
# Mark an implementation as Ready (manual transition on Implementation.status)
heex implementation validate --implementation-id <IMPLEMENTATION_ID>
# Check the per-system status of triggers and signals
heex system get --system-id <SYSTEM_ID>
# Verify the Heex Agent installed on a system (resolves stuck TO_DEPLOY on System, SystemTrigger, SystemSignal)
heex agent list --system-id <SYSTEM_ID> --active
See also
