# How to Set Up a Development Environment for LoopX: A Step-by-Step Guide to Installing and Running the Autonomous Agent Framework

> Set up your LoopX development environment quickly. Follow this guide to clone, install, verify, and demo the autonomous agent framework. Get started with LoopX today.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: getting-started
- Published: 2026-08-08

---

**To set up a LoopX development environment, clone the repository, run [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) to install dependencies and CLI tools, verify with `loopx doctor`, and confirm functionality with `loopx demo`.**

LoopX is a complex autonomous-agent framework that separates **control-plane** logic, **runtime** adapters, and **presentation** layers. Setting up a proper development environment requires following the repository's canonical workflow to ensure all components are correctly wired. This guide walks through the exact steps documented in the official contribution guidelines, with copy-paste commands and verification steps.

## Prerequisites and Quick Start

Before installing, ensure you have Python, Node.js, and Docker available on your system. The `loopx doctor` command will validate these dependencies after installation.

Run this complete workflow to get started:

```bash

# 1️⃣ Clone the repository

git clone https://github.com/huangruiteng/loopx ~/loopx
cd ~/loopx

# 2️⃣ Execute the official installer

./scripts/install-local.sh
export PATH="$HOME/.local/bin:$PATH"

# 3️⃣ Verify all dependencies are satisfied

loopx doctor

# 4️⃣ Launch the minimal end-to-end demo

loopx demo

```

The [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) script automates environment creation, installs development extras, and adds the LoopX CLI to your `$PATH`【/cache/repos/github.com/huangruiteng/loopx/main/scripts/install-local.sh】.

## Understanding the LoopX Development Environment Structure

LoopX organizes its codebase into distinct architectural layers. Knowing these boundaries helps you navigate the codebase effectively after installation.

### Control-Plane, Runtime, and Presentation Layers

- **Control-plane** – Manages agent state machines and scheduling policies
- **Runtime** – Adapter layer connecting to external execution environments
- **Presentation** – UI and output formatting components

The **Developer Guide** at [`docs/development/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/development/README.md) explains how to locate the relevant bounded context for your work【/cache/repos/github.com/huangruiteng/loopx/main/docs/development/README.md#L1-L25】.

### Key Configuration Files

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md) | Official clone-install-verify steps and quality-gate commands【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】 |
| [`docs/development/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/development/README.md) | Architecture overview and documentation navigation |
| [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) | Automated environment bootstrap |
| `examples/` | Runnable smoke tests and demonstration scripts |

## Installing LoopX for Core Development

For users who plan to modify core components—such as the control-plane state machine, scheduler policies, or presentation UI—additional setup steps are required.

### Install Development and Test Dependencies

```bash
python -m pip install -e ".[test]"

```

This installs the package in editable mode with test dependencies, as specified in the project's [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml) or setup configuration.

### Verify Code Quality

The repository enforces static analysis and type checking. Run these commands before committing changes:

```bash

# Linting with Ruff

python -m ruff check loopx/

# Static type checking with mypy

python -m mypy

```

### Run Smoke Tests and Full Test Suite

Validate your environment with the repository's public smoke tests:

```bash

# Execute control-plane smoke test

python examples/control_plane/cli-output-budget-regression-smoke.py

# Run complete pytest suite

python -m pytest -q

```

These commands are documented in the **Local Development** section of [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md)【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】.

## Using the LoopX CLI for Environment Verification

The `loopx` command-line interface provides diagnostic and demonstration tools essential for development workflow.

### `loopx doctor` – Dependency Validation

Checks that all required external tools (Python, Node, Docker, etc.) are available and that core commands are functional. Run this after any environment change.

### `loopx demo` – End-to-End Verification

Launches a minimal run through the complete stack: control-plane → scheduler → turn → presentation. This confirms that the runtime is correctly wired and all layers communicate properly.

## Troubleshooting Common Setup Issues

If `loopx doctor` reports missing dependencies, verify:

- Python version compatibility with the project's requirements
- Node.js installation for presentation-layer builds
- Docker daemon running for runtime container operations

The [`install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/install-local.sh) script attempts to configure `$PATH` automatically, but you may need to restart your shell or manually export `PATH="$HOME/.local/bin:$PATH"` to access the `loopx` command immediately after installation.

## Summary

- **Clone** the repository to get the full source tree including scripts and examples
- **Run** [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) to bootstrap the environment and install CLI tools
- **Verify** with `loopx doctor` to confirm external dependencies are satisfied
- **Test** with `loopx demo` to validate end-to-end functionality
- **Install** `".[test]"` extras and run `pytest` when modifying core components

Following this workflow creates a LoopX development environment that respects the project's public/private boundary policies and is ready for contribution.

## Frequently Asked Questions

### What is the fastest way to install LoopX locally?

Run [`./scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/./scripts/install-local.sh) from the repository root. This single script creates a virtual environment, installs dependencies, and configures the `loopx` CLI tool in your `$PATH`【/cache/repos/github.com/huangruiteng/loopx/main/scripts/install-local.sh】.

### How do I verify my LoopX installation is working correctly?

Execute `loopx doctor` to check external tool availability, then run `loopx demo` to see a complete control-plane → presentation flow. The demo launches a minimal end-to-end run that confirms the runtime is correctly wired.

### Where are the official LoopX development instructions documented?

The [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md) file contains the canonical clone-install-verify workflow, while [`docs/development/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/development/README.md) provides broader architecture guidance【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】【/cache/repos/github.com/huangruiteng/loopx/main/docs/development/README.md#L1-L25】.

### What tests should I run before submitting a LoopX contribution?

Run `python -m ruff check loopx/` for linting, `python -m mypy` for type checking, and `python -m pytest -q` for the full test suite. Also execute `python examples/control_plane/cli-output-budget-regression-smoke.py` for the public smoke test as documented in the contribution guide【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】.