How Codex App and Host Integrations Connect to the LoopX Control Plane Without Per-Host State Machines

LoopX eliminates per-host state machines by treating integrations like Codex App as stateless surfaces that emit immutable activation packets via thin CLI commands, centralizing all persistence in the goal registry.

Managing distributed state across hundreds of host integrations typically requires complex state machines on each client. The LoopX control plane solves this architectural challenge by defining a minimal, immutable contract called host-loop-activation that lets Codex App and other integrations connect without maintaining local runtime history. According to the huangruiteng/loopx source code, this approach shifts all mutable state to the control plane while hosts remain thin, ephemeral clients.

The Stateless Host Architecture

Traditional automation platforms require resident daemons or local databases to track integration state. LoopX inverts this model by specifying that host integrations are stateless surfaces—they possess no long-running processes, no local storage of activation history, and no per-host state machines. Instead, each integration stores only immutable identifiers and a single activation flag, pushing all runtime state to the control plane's central goal registry. This architecture allows Codex App to function as a transient client that invokes short-lived CLI commands rather than maintaining persistent connections.

The Host-Loop-Activation Contract

The contract between host and control plane centers on a fixed JSON schema that defines exactly what information a host must transmit to participate in the automation mesh.

Schema Definition in host_loop_activation.py

In loopx/host_loop_activation.py, the system defines SCHEMA_VERSION = "loopx_host_loop_activation_v1" which serves as the immutable contract for all integration packets. This schema resides in the main LoopX repository and provides the validation rules that the control plane uses to accept or reject incoming host registrations. By versioning the schema explicitly, LoopX ensures backward compatibility across different host integration versions without requiring simultaneous updates to per-host logic.

Building Activation Packets

When a host needs to register or update its surface, it calls build_host_loop_activation_packet() from the same module. This function constructs a packet containing three critical fields: agent_id (immutable identifier), host_surface (e.g., "codex-app"), and activated (boolean flag). Line 1288 of loopx/host_loop_activation.py generates a fresh packet on every invocation, ensuring that no mutable runtime history leaks into the host's execution context.

The Thin CLI Bridge

Host integrations communicate with the control plane through ephemeral CLI invocations rather than persistent sockets or background services.

Command Execution via upgrade.py

The file loopx/upgrade.py handles the thin "heartbeat-prompt" commands that Codex App executes locally. For example, running loopx heartbeat-prompt --thin triggers the activation routine defined at lines 497-514, which constructs the activation packet and transmits it to the control plane API. This command returns immediately after posting the packet, leaving no resident process on the host machine.

Control Plane Validation

Upon receipt, the control plane validates the packet against the schema during the onboarding process. In loopx/slash_commands.py, the flag host_loop_activation_required_after_todo_writeback (lines 67-71) ensures that the system checks for a valid activation record before proceeding. The control plane stores the minimal activation data under the goal's host_loop_activation field, making the packet the sole source of truth for that host's state.

Codex App Integration Workflow

The Codex App integration demonstrates the stateless pattern in practice. When a user initiates automation:

1. The App executes loopx heartbeat-prompt --thin locally.
2. The CLI calls build_host_loop_activation_packet() with parameters host_surface="codex-app" and activated=True.
3. The resulting JSON packet is POSTed to the LoopX control plane via the upgrade module.
4. The control plane persists the packet and returns a scheduler hint (e.g., "run every 3 min").
5. Codex App obeys the hint by re-invoking the thin CLI at the indicated cadence, treating each heartbeat as an independent, idempotent request.

Because the activation packet is immutable after creation, the control plane can safely reconcile state without querying the host's local history.

Stateless Interaction and Skill Delivery

Once activated, hosts remain stateless participants in the automation loop, relying entirely on the control plane for coordination.

Routing Verification in doctor.py

Before delivering skills to a host, the system verifies the activation record exists. In loopx/doctor.py (lines 789-791), the routing logic checks for the required host-loop-activation; if absent, it aborts with the message "skill delivery is owned by the selected host integration". This enforcement ensures that stateless hosts cannot receive work without an explicit, validated activation packet on file.

Implementation Example

The following Python code demonstrates how to construct a valid activation packet for the Codex App integration:

from loopx.host_loop_activation import build_host_loop_activation_packet

# Build a Codex-App activation packet

packet = build_host_loop_activation_packet(
    agent_id="codex-app-001",
    host_surface="codex-app",
    activated=True,
)

# The packet is sent to the control-plane API via the thin CLI wrapper

# defined in loopx/upgrade.py. No local state is persisted.

print(packet)

This JSON output matches the loopx_host_loop_activation_v1 schema and represents the complete state required for the host to participate in the control plane.

Summary

• LoopX treats integrations like Codex App as stateless surfaces with no per-host state machines.
• The host-loop-activation contract in loopx/host_loop_activation.py defines an immutable JSON schema for registration packets.
• build_host_loop_activation_packet() constructs packets containing only agent_id, host_surface, and activated fields.
• Thin CLI commands in loopx/upgrade.py transmit packets without leaving resident processes.
• The control plane owns all mutable state, storing activation records in the global goal registry.
• Skill delivery is gated by activation checks in loopx/doctor.py, ensuring security without host-side state.

Frequently Asked Questions

What prevents Codex App from losing synchronization with the control plane?

The control plane maintains the authoritative state in the goal registry. Because Codex App sends immutable activation packets and receives scheduler hints in response, each CLI invocation is idempotent and self-contained. The control plane reconciles any timing differences using the immutable fields in the latest packet.

Where is the host activation state stored?

All activation state persists in the control plane's goal registry under the host_loop_activation field. As implemented in huangruiteng/loopx, hosts store zero local state; they rely entirely on the packet they transmit to loopx/slash_commands.py during onboarding.

How does LoopX handle host failures without local state machines?

Since no state machine runs on the host, failure handling occurs entirely within the control plane. If a host misses heartbeats, the control plane detects the absence of fresh packets and adjusts scheduling hints accordingly. The next successful CLI invocation from any host simply updates the activation record with a new timestamp.

Can multiple host surfaces share the same agent ID?

No. The build_host_loop_activation_packet() function requires unique combinations of agent_id and host_surface to prevent collisions in the global registry. The control plane validates these identifiers during packet ingestion to ensure isolation between different integration types like Codex App and VS Code Codex.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}