How to Deploy LoopX Applications: Complete Installation and Setup Guide

Deploy LoopX by installing the CLI via no-clone script or local checkout, connecting a project to create the state registry, and running the quota-governed autonomous loop.

LoopX is a local-first control-plane for AI-assisted development that lives entirely on your host machine. This guide walks through the three core stages of LoopX application deployment: installing the CLI, connecting a project to establish goal state, and running the autonomous turn-based loop.

Installation Methods

LoopX provides two officially supported installation paths depending on your use case.

No-Clone Install (End Users)

The recommended approach downloads a signed release archive without requiring a repository checkout. This keeps your host environment clean and uses the stable release channel.

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

The scripts/install-from-github.sh script performs three operations: downloads the release archive, validates its SHA-256 checksum, and installs the wrapper binary to ~/.local/bin/loopx. Running loopx doctor verifies the installation freshness and confirms the CLI points to a release snapshot.

Contributor Install (Development)

For testing new features or contributing to LoopX, use the checkout-based installer that creates a "canary" wrapper pointing to your live source tree.

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

This installs loopx-canary alongside the stable wrapper. Promote the canary to default by re-running with LOOPX_PROMOTE_DEFAULT=1 ./scripts/install-local.sh.

Connecting a Project to LoopX

With the CLI installed, the next deployment stage initializes LoopX state for your target repository. This creates the kernel state (JSON files under .loopx/) and registers a goal in the global registry.

Basic Connection

cd /path/to/your-project
loopx connect --goal-id my-project-goal

This generates:

• .loopx/registry.json — the global registry entry tracking this project
• .codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md — the durable goal state file

Guided Goal Creation

For first-time setup, use the interactive bootstrap flow:

loopx start-goal --guided --project . --goal-text "Your long-running objective"

Alternatively, loopx bootstrap combines connection with initial state seeding. See docs/guides/getting-started.md for the full operator walkthrough.

Running the Autonomous Loop

The third deployment stage activates the turn-based runtime governed by LoopX's quota engine. Each turn represents a bounded unit of agent work: claiming a todo, executing capabilities through provider bridges, and updating kernel state.

Quota-Gated Turn Execution

Before running work, verify quota availability:

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

This consults loopx/quota.py to determine if the scheduler permits a turn based on compute eligibility and policy constraints.

Full Turn Cycle

# Claim the highest-priority todo

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

# Materialize the next state from agent output

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

# Spend a quota slot and execute

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

The loopx/runtime.py module orchestrates this cycle, translating between the Agent Runtime Bridges (loopx/worker_bridge.py, loopx/visible_multi_agent_launcher.py) and the kernel's durable state.

Inspecting Loop Status

loopx status

Displays compact runtime information: current goal, active todo, quota balance, and last heartbeat timestamp.

Optional Dashboard Deployment

LoopX includes a React-based dashboard for visualizing loop state. Note that the dashboard is read-only; the CLI remains the authoritative control interface.

# Start the JSON status backend

loopx serve-status --port 8765

# In a separate terminal

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

The dashboard consumes the local-only API exposed by loopx serve-status and presents goal progress, todo backlog, and quota utilization.

Architecture Overview for Deployers

Understanding these components helps troubleshoot deployment issues:

Component	Files	Responsibility
Kernel	.loopx/*.json, .codex/goals/**	Durable state for goals, todos, evidence, quota
Quota Engine	loopx/quota.py	Compute eligibility, scheduling hints, safe-fallback policies
Runtime	loopx/runtime.py	Turn orchestration, bridge coordination
Release Manifest	loopx/release_manifest.py	Tracks snapshot vs. canary vs. custom archive
State Refresh	loopx/state_refresh.py	Append-only state updates, dry-run support

Deployment Verification Checklist

Run this sequence after any fresh LoopX application deployment:

# 1. Verify CLI installation

loopx doctor | grep -E "(install_freshness|release_channel)"

# 2. Confirm project connection

ls -la .loopx/registry.json .codex/goals/*/ACTIVE_GOAL_STATE.md

# 3. Test quota system

loopx quota should-run

# 4. Execute dry-run turn

loopx refresh-state --goal-id your-goal --dry-run

# 5. Check final status

loopx status

Summary

• Install LoopX via scripts/install-from-github.sh (stable) or scripts/install-local.sh (development) — both validate integrity and configure the PATH wrapper
• Connect projects using loopx connect or loopx start-goal --guided to establish kernel state in .loopx/ and .codex/
• Run the autonomous loop through quota-gated turns: should-run → todo claim → refresh-state → spend-slot
• Monitor with loopx status or the optional React dashboard; always treat the CLI as the source of truth
• Maintain deployment health by re-running loopx doctor after upgrades to verify install freshness

Frequently Asked Questions

What is the difference between loopx connect and loopx bootstrap?

loopx connect registers an existing goal ID with the current project directory, creating only the registry entry. loopx bootstrap performs a full initialization including goal creation, state seeding, and first-time setup scaffolding. According to docs/guides/getting-started.md, use connect when the goal already exists and bootstrap for greenfield projects.

Can I deploy LoopX on a remote server or container?

LoopX is architected as a local-first control-plane with state stored in host filesystem paths (.loopx/, .codex/). While you can technically run it in a container, the design assumes direct host access for agent bridges and file observation. Remote deployment would require mounting state directories and reimplementing bridge layers for your environment.

How does LoopX quota management work?

The quota system in loopx/quota.py implements a policy contract that decides if a turn may execute and what type of turn is permitted. Quota slots are consumed via spend-slot commands with --source attribution (heartbeat, manual, scheduled). The runtime.py module enforces these checks before allowing agent bridges to invoke providers.

What happens if loopx doctor reports stale installation?

Stale freshness indicates the wrapper binary and source tree have diverged. Re-run your original installer to synchronize: curl ... | bash for release channel users, or ./scripts/install-local.sh for canary deployments. The loopx/release_manifest.py module tracks which channel is active to enable this diagnosis.

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