# How to Deploy LoopX: Complete Installation Guide for the Local‑First Control Plane

> Deploy LoopX, a local-first control plane, with our complete installation guide. Install via a single script and connect to any project directory.

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

---

**LoopX is a local‑first control plane that installs via a single shell script, connects to any project directory, and runs autonomously through a quota‑gated execution loop.**

Deploying LoopX means bringing three components onto your host: the **CLI wrapper** (which downloads or symlinks the runtime), the **state kernel** (JSON‑based registry and goal storage), and the **quota engine** that governs every turn. This guide walks through each stage using the exact source paths and commands defined in `huangruiteng/loopx`.

## Install the LoopX CLI

LoopX offers two installation paths controlled by scripts in `scripts/`. Both place a wrapper at `~/.local/bin/loopx` and validate the environment via `loopx doctor`.

### No‑Clone Install (Recommended)

The [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh) downloads a signed release archive, verifies its SHA‑256 checksum, and extracts the runtime without leaving a repository checkout on your machine.

```bash
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

```

This approach keeps the host clean and is the default for operators running LoopX in production. The wrapper records its provenance in [`loopx/release_manifest.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/release_manifest.py), enabling `loopx doctor` to report **install freshness** and detect stale deployments.

### Contributor Install (Checkout‑Based)

For developers modifying LoopX itself, [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) creates a **canary** wrapper that points to a live Git checkout.

```bash
git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

```

Promote the canary to the default wrapper by setting `LOOPX_PROMOTE_DEFAULT=1` during installation. This lets you test changes in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) or [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) before committing them.

## Connect LoopX to a Project

LoopX maintains all state locally under `.loopx/` and `.codex/goals/`. To initialize a new **goal**—the atomic unit LoopX governs—run one of three entry points from your project root:

| Command | Purpose | Creates |
|---------|---------|---------|
| `loopx connect --goal-id <id>` | Link an existing goal to this directory | [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) entry |
| `loopx bootstrap` | Scaffold a fresh goal with defaults | Goal directory under `.codex/goals/` |
| `loopx start-goal --guided` | Interactive wizard for goal definition | [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md) plus registry |

Example guided connection:

```bash
cd /path/to/your-project
loopx start-goal --guided --project . --goal-text "Refactor legacy authentication to OAuth2"

```

The registry schema is defined in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py). Each goal receives its own subdirectory (`.codex/goals/<goal-id>/`) containing:
- [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md) — the durable goal description
- [`todos.json`](https://github.com/huangruiteng/loopx/blob/main/todos.json) — claimable work items
- `evidence/` — artifacts produced by completed turns

## Run the LoopX Execution Loop

Once connected, LoopX operates through **quota‑gated turns**. The quota engine in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) decides *if*, *when*, and *what type* of turn may execute.

### Check Quota Eligibility

```bash
loopx quota should-run --goal-id my-project-goal

```

Returns `true` only when the scheduler permits a turn based on:
- Elapsed time since last run
- User‑defined gates (manual approval flags)
- Safe‑fallback policy for error recovery

### Claim and Execute Work

A typical turn sequence:

```bash

# 1. Claim the highest‑priority todo

loopx todo claim --goal-id my-project-goal

# 2. Materialize the next state

loopx refresh-state --goal-id my-project-goal

# 3. Spend a quota slot and execute

loopx quota spend-slot --goal-id my-project-goal --slots 1 --source heartbeat --execute

```

The `--execute` flag commits the turn; omit it for dry‑run validation. Runtime orchestration lives in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), which coordinates:
- **Agent Runtime Bridges** ([`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py), [`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py)) — translate external agents (Codex, Claude, OpenCode, Pi) into bounded turns
- **State Refresh** ([`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py)) — appends run entries without mutating the goal
- **Heartbeat Prompts** — scheduled via `loopx heartbeat-prompt`

### Monitor Loop Status

```bash
loopx status

```

Produces a compact summary: goal health, pending todos, quota balance, and last execution timestamp.

## Optional: Deploy the LoopX Dashboard

LoopX ships a **local‑only React dashboard** for visual inspection. It is strictly a view layer—the CLI remains the authoritative source.

```bash

# Terminal 1: JSON backend

loopx serve-status --port 8765

# Terminal 2: React UI

cd ~/loopx/apps/presentation/dashboard
npm install && npm run dev

```

Dashboard configuration is documented in [`apps/presentation/dashboard/README.md`](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/README.md).

## Key Architectural Concepts

Understanding these primitives ensures reliable LoopX deployment:

| Concept | Definition | Source Location |
|---------|------------|-----------------|
| **Quota Contract** | Policy binding compute eligibility to scheduler hints and fallback modes | [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) |
| **State Kernel** | Durable JSON store for goals, todos, gates, and evidence | `.loopx/` hierarchy managed by [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) |
| **Release Manifest** | Records whether CLI points to release, canary, or custom archive | [`loopx/release_manifest.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/release_manifest.py) |
| **Turn** | Atomic execution unit: Agent → Capability → Provider → Kernel | Orchestrated in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) |
| **Public/Private Boundary** | Guarantees only sanitized artifacts leave the host | Documented in [`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md) |

## Summary

- **Install** via [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh) (clean) or [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) (development)
- **Connect** projects using `loopx connect`, `loopx bootstrap`, or `loopx start-goal --guided`
- **Run** autonomous turns gated by `loopx quota should-run` and `loopx quota spend-slot`
- **Verify** deployment health anytime with `loopx doctor`
- **Extend** with the optional React dashboard at `apps/presentation/dashboard/`

All state remains local; no external control plane is required.

## Frequently Asked Questions

### What operating systems does LoopX support?

LoopX targets Unix‑like environments where Python 3 and Bash are available. The install scripts in `scripts/` use standard POSIX utilities (`curl`, `tar`, `sha256sum`) and place the wrapper in `~/.local/bin/`. Windows users may run LoopX under WSL2.

### How do I upgrade an existing LoopX installation?

Re‑run the original installation command. For no‑clone installs, execute [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh) again; it fetches the latest release archive and refreshes the wrapper. For checkout‑based installs, pull the repository and rerun [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh). Always validate with `loopx doctor` afterward.

### Can I run multiple LoopX goals on the same machine?

Yes. The registry in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) supports multiple goal entries. Each goal maintains isolated state under its own `.codex/goals/<goal-id>/` directory. Use `loopx connect --goal-id <id>` to switch the active context for a project directory, or run `loopx` commands with explicit `--goal-id` arguments from any location.

### What happens if a turn fails or the host restarts?

LoopX is **resumable by design**. The state kernel persists all progress to `.loopx/` JSON files before marking a turn complete. On restart, `loopx quota should-run` re‑evaluates eligibility; `loopx refresh-state` rebuilds the runtime view from disk. No in‑memory state is required for recovery.