# How to Deploy LoopX Applications: Complete Installation and Setup Guide

> Deploy LoopX applications with our comprehensive guide. Install the CLI, connect your project, and run the autonomous loop. Follow our easy steps for a successful setup.

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

---

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

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/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.

```bash
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

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

```

This generates:
- [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.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:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/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:

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

```

This consults [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) to determine if the scheduler permits a turn based on compute eligibility and policy constraints.

### Full Turn Cycle

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) module orchestrates this cycle, translating between the **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)) and the kernel's durable state.

### Inspecting Loop Status

```bash
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.

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Compute eligibility, scheduling hints, safe-fallback policies |
| **Runtime** | [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) | Turn orchestration, bridge coordination |
| **Release Manifest** | [`loopx/release_manifest.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/release_manifest.py) | Tracks snapshot vs. canary vs. custom archive |
| **State Refresh** | [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) | Append-only state updates, dry-run support |

## Deployment Verification Checklist

Run this sequence after any fresh **LoopX application deployment**:

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh) (stable) or [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/./scripts/install-local.sh) for canary deployments. The [`loopx/release_manifest.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/release_manifest.py) module tracks which channel is active to enable this diagnosis.