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

> Integrate LoopX with external services using value-connector capabilities for safe, reproducible workflows. Explore the runtime connector catalog and uniform CLI surface.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/huangruiteng/loopx/blob/main/loopx/host_mode_planner.py) (lines 55-86), the planner implements this validation logic:

```python

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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:

```bash

# 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:

```python
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:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 66-67) | Registers top-level `value-connectors` sub-command and dispatches to capability handler |
| [`loopx/capabilities/value_connectors/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/value_connectors/cli.py) | Parses connector-specific flags and invokes appropriate handler |
| [`loopx/capabilities/value_connectors/source_map.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/value_connectors/source_map.py) | Defines schema for connector source-map packets and runtime binding logic |
| [`loopx/host_mode_planner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/host_mode_planner.py) (lines 55-86) | Validates connectors against runtime catalog and injects into Turn host plan |
| [`loopx/presentation/public_safety.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/host_mode_planner.py) and executed through [`value_connectors/cli.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.