How to Integrate LoopX with Other Services: A Complete Guide to Value-Connector Capabilities

Integrate LoopX with external services using value-connector capabilities that expose a uniform CLI surface and runtime connector catalog for safe, reproducible workflows.

LoopX integration with third-party APIs, SaaS platforms, and custom webhooks centers on its capability-driven architecture. The huangruiteng/loopx repository implements this through value-connector capabilities—modular components that standardize how external services are selected, configured, and executed within the Turn runtime.

The Three-Stage Integration Flow

LoopX service integration follows a predictable pattern: select, configure, and run. Each stage maps to specific source files in the repository.

Select a Connector

Choose a connector matching your target service. LoopX provides connectors for GitHub, finance APIs, Lark, and generic HTTP webhooks. The host-mode planner validates this selection and injects the connector ID into the Turn payload.

In loopx/host_mode_planner.py (lines 55-86), the planner implements this validation logic:

# From loopx/host_mode_planner.py#L55-L86

def validate_and_inject_connector(turn_plan, connector_id):
    """
    Validates connector against runtime catalog and injects into Turn.
    Raises ConnectorNotFoundError if validation fails.
    """
    catalog = get_runtime_catalog()
    if connector_id not in catalog:
        raise ConnectorNotFoundError(f"Unknown connector: {connector_id}")
    turn_plan['connector'] = catalog[connector_id]
    return turn_plan

Configure the Connector

Most connectors accept CLI flags or JSON configuration for connection details—URLs, secrets, query parameters. The centralized CLI entry point resides in loopx/capabilities/value_connectors/cli.py, which registers all connectors under the top-level value-connectors command.

Run the Connector

Invoke via CLI or programmatically through the Turn API. The connector produces a value-connector payload stored in the public-safety projection. As implemented in loopx/presentation/public_safety.py (line 11), raw secrets and private payloads are redacted from persistent storage.

Practical Integration Examples

CLI-Based GitHub Integration

Register and probe a public GitHub issue:

# Register the GitHub public-probe connector

loopx value-connectors github-public-probe \
  --url https://github.com/owner/repo/issues/123 \
  --format json

Programmatic Turn Execution

Execute connectors within Python for multi-step workflows:

from loopx.turn import Turn

turn = Turn()
turn.add_connector('github_public_probe')
turn.run()
payload = turn.get_payload()
print(payload['connector_id'])   # → "github_public_probe"

Host-Mode UI Integration

Surface connector status in external interfaces:

loopx host-mode-plan \
  --host opencode \
  --connector github_public_probe

Combining Connectors with LoopX Features

Value-connectors are first-class capabilities composable with core LoopX features:

• loopx integration-branch — Version-control your integration workflow
• loopx host-mode-plan — Expose connector status in UIs
• loopx periodic-report — Generate human-readable integration status reports
• loopx multi-agent — Hook connectors into multi-agent loops

Key Source Files for Integration

File	Purpose
loopx/cli.py (lines 66-67)	Registers top-level value-connectors sub-command and dispatches to capability handler
loopx/capabilities/value_connectors/cli.py	Parses connector-specific flags and invokes appropriate handler
loopx/capabilities/value_connectors/source_map.py	Defines schema for connector source-map packets and runtime binding logic
loopx/host_mode_planner.py (lines 55-86)	Validates connectors against runtime catalog and injects into Turn host plan
loopx/presentation/public_safety.py (line 11)	Guarantees connector payload redaction from public logs

Security Considerations

LoopX integration design prioritizes public safety by default. The public-safety projection ensures:

• No raw secrets persist in logs or storage
• Connector payloads are sanitized before any persistence operation
• Configuration secrets remain bound to the runtime session only

Summary

• LoopX integrates with external services through value-connector capabilities with uniform CLI and programmatic interfaces
• The three-stage flow—select, configure, run—is validated by host_mode_planner.py and executed through value_connectors/cli.py
• Connectors compose natively with integration-branch, host-mode-plan, periodic-report, and multi-agent features
• Public-safety projection in public_safety.py prevents secret leakage in persistent storage
• All configurations support both CLI flags and JSON files for reproducible, version-controlled workflows

Frequently Asked Questions

What services can LoopX integrate with?

LoopX supports any service wrapped in a value-connector. Built-in connectors cover GitHub, finance APIs, Lark, and generic HTTP webhooks. Custom connectors follow the same interface defined in loopx/capabilities/value_connectors/source_map.py.

How does LoopX protect sensitive connector credentials?

Credentials are never persisted. According to loopx/presentation/public_safety.py line 11, connector payloads undergo redaction before storage. Secrets remain session-bound and excluded from the public-safety projection.

Can LoopX integrations run without manual CLI invocation?

Yes. The Turn API enables fully programmatic execution. Import Turn from loopx.turn, call add_connector() with your connector ID, and execute run()—useful for scheduled jobs or embedded multi-agent workflows.

Where is connector validation implemented?

Connector selection validation resides in loopx/host_mode_planner.py lines 55-86. The host-mode planner checks connector IDs against the runtime catalog before injection into Turn payloads, raising ConnectorNotFoundError for invalid selections.

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