# How to Test LoopX Locally: A Complete Guide to Installation and Validation

> Learn how to test LoopX locally with this complete guide. Install the control plane, validate with loopx doctor, and run smoke tests from examples.

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

---

**You can test LoopX locally by installing the lightweight Python-based control plane via a one-liner curl script, validating the installation with `loopx doctor`, connecting to a project directory, and running the built-in smoke tests from the `examples/` folder.**

LoopX is a lightweight, **state-kernel control-plane** for long-running AI agents. Because the core of LoopX lives in pure Python and only depends on the standard library, testing it locally is straightforward. This guide walks you through every step to verify your LoopX installation and validate its core capabilities.

---

## Install LoopX Locally

The easiest way to test LoopX locally starts with the official one-liner installer. No repository clone is required.

```bash
curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

```

This script places the `loopx` CLI in `~/.local/bin/`. The install snippet is documented in [`README.md`](https://github.com/huangruiteng/loopx/blob/main/README.md) at the root of the repository.

---

## Validate the Installation with `loopx doctor`

Before testing any functionality, confirm that your environment meets LoopX's requirements.

```bash
loopx doctor

```

The `doctor` command validates:
- Python runtime availability
- Required OS utilities (`curl`, `tar`)
- A clean working directory for state operations

This health check is implemented in [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py), which serves as the entry point for all CLI commands.

---

## Connect LoopX to a Local Project

To test LoopX's state-kernel behavior, bind it to an existing project directory.

```bash
cd /path/to/your-project
loopx connect
loopx status

```

The `connect` flow initializes LoopX in your project. Running `loopx status` displays:
- Current **goal**
- Active **gates**
- Next **todo** item

This validates that the state kernel is properly tracking project context. The connection flow is documented in the "Getting Started" section of [`README.md`](https://github.com/huangruiteng/loopx/blob/main/README.md).

---

## Run Built-In Smoke Tests from the `examples/` Directory

The LoopX repository ships with self-contained smoke tests under `examples/`. Each script exercises a specific capability and asserts expected output with no external dependencies.

```bash
python examples/worker-bridge-install-contract-smoke.py
python examples/visible-multi-agent-launcher-smoke.py
python examples/terminal-bench-loopx-cli-bridge-runner-smoke.py

```

These smokes deliberately avoid external dependencies, making them ideal for local CI pipelines. Key files include:

| Smoke Test File | Capability Validated |
|-----------------|----------------------|
| [`examples/worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/worker-bridge-install-contract-smoke.py) | Worker-bridge contract installation |
| [`examples/visible-multi-agent-launcher-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/visible-multi-agent-launcher-smoke.py) | Visible multi-agent launcher flow |
| [`examples/terminal-bench-loopx-cli-bridge-runner-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/terminal-bench-loopx-cli-bridge-runner-smoke.py) | Terminal-bench CLI bridge integration |

Each smoke test imports core modules like `loopx.runtime` and `loopx.quota` to verify control-plane primitives.

---

## Run the Repository-Wide Quality Check

LoopX includes a `check` command that scans source, documentation, and examples for boundary violations and quality gate compliance.

```bash
loopx check \
  --scan-path README.md \
  --scan-path docs/ \
  --scan-path examples/

```

Passing this check confirms your local environment complies with the repository's **public-safe policies**. The check logic resides in [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) alongside other CLI implementations.

---

## Write Custom Tests with pytest (Optional)

For deeper validation, you can extend LoopX's testing with custom **pytest** suites. Because the core library is pure Python, any module is importable for unit testing.

First, install pytest:

```bash
pip install pytest

```

Then create a test file that exercises LoopX internals:

```python

# tests/test_quota.py

import pytest
from loopx.quota import should_run

def test_quota_should_run():
    # Simulate a minimal goal-state fixture

    result = should_run(goal_id="demo", agent_id="test-agent")
    assert result is True

```

Run your custom suite:

```bash
pytest tests/

```

The official testing strategy is documented in [`docs/development/testing-and-quality.md`](https://github.com/huangruiteng/loopx/blob/main/docs/development/testing-and-quality.md). Core modules available for testing include:
- `loopx.quota` — quota enforcement logic
- `loopx.status` — status reporting for `loopx status` CLI output
- `loopx.runtime` — runtime management primitives

---

## Summary

- **Install LoopX locally** with a one-liner curl script that requires no clone
- **Verify installation** using `loopx doctor` to check Python runtime and OS dependencies
- **Connect to projects** with `loopx connect` and inspect state with `loopx status`
- **Run smoke tests** from `examples/` to validate worker bridge, multi-agent launcher, and CLI bridge capabilities
- **Execute quality checks** with `loopx check` to enforce repository policies
- **Extend with pytest** by importing pure-Python modules like `loopx.quota` and `loopx.runtime`

---

## Frequently Asked Questions

### Does LoopX require Docker or external services to test locally?

No. LoopX is implemented in pure Python with only standard library dependencies. All local testing—from installation verification to smoke tests—runs without Docker, databases, or external APIs. The `examples/` smoke tests are self-contained and assert expected output directly.

### Where are the official test files located in the LoopX repository?

The primary test files live in `examples/` at the repository root. Files like [`worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/worker-bridge-install-contract-smoke.py) and [`visible-multi-agent-launcher-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/visible-multi-agent-launcher-smoke.py) serve as both documentation and executable validation. For pytest-style unit tests, see [`docs/development/testing-and-quality.md`](https://github.com/huangruiteng/loopx/blob/main/docs/development/testing-and-quality.md) for templates using `loopx.quota` and other core modules.

### What does `loopx doctor` actually check?

`loopx doctor` validates your local environment has: a compatible Python runtime, required OS utilities (`curl`, `tar`), and a clean working directory suitable for LoopX state operations. It is implemented in [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) and runs before any project connection to prevent configuration errors.

### Can I run LoopX tests in CI without installing the full repository?

Yes. The install script `curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash` works in CI environments. After installation, running the smoke tests from `examples/` provides fast, dependency-free validation. The smoke tests require no repository clone and exit with clear pass/fail status codes suitable for CI pipelines.