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

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 downloads a signed release archive, verifies its SHA‑256 checksum, and extracts the runtime without leaving a repository checkout on your machine.

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, enabling loopx doctor to report install freshness and detect stale deployments.

Contributor Install (Checkout‑Based)

For developers modifying LoopX itself, scripts/install-local.sh creates a canary wrapper that points to a live Git checkout.

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 or 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 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 plus registry

Example guided connection:

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. Each goal receives its own subdirectory (.codex/goals/<goal-id>/) containing:

• ACTIVE_GOAL_STATE.md — the durable goal description
• 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 decides if, when, and what type of turn may execute.

Check Quota Eligibility

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:

# 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, which coordinates:

• Agent Runtime Bridges (loopx/worker_bridge.py, loopx/visible_multi_agent_launcher.py) — translate external agents (Codex, Claude, OpenCode, Pi) into bounded turns
• State Refresh (loopx/state_refresh.py) — appends run entries without mutating the goal
• Heartbeat Prompts — scheduled via loopx heartbeat-prompt

Monitor Loop Status

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.

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

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
State Kernel	Durable JSON store for goals, todos, gates, and evidence	.loopx/ hierarchy managed by loopx/registry.py
Release Manifest	Records whether CLI points to release, canary, or custom archive	loopx/release_manifest.py
Turn	Atomic execution unit: Agent → Capability → Provider → Kernel	Orchestrated in loopx/runtime.py
Public/Private Boundary	Guarantees only sanitized artifacts leave the host	Documented in docs/public-private-boundary.md

Summary

• Install via scripts/install-from-github.sh (clean) or 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 again; it fetches the latest release archive and refreshes the wrapper. For checkout‑based installs, pull the repository and rerun 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 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.

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