# How to Configure LoopX: CLI Commands, Environment Variables, and Goal-Level Settings

> Configure LoopX using CLI commands and environment variables. Learn goal-level settings with preview and execute options for effective runtime control.

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

---

**LoopX configuration is performed per-goal using the `loopx configure-goal` CLI command with `--preview` to inspect settings and `--execute` to persist changes, while environment variables like `LOOPX_RUNTIME_ROOT` control runtime behavior.**

Configuring LoopX from the `huangruiteng/loopx` repository involves managing durable, observable settings for long-running AI work through a combination of CLI flags and environment variables. All configuration is stored in the project-local [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) file and is versioned with the goal ID to ensure repeatable runs and safe rollbacks.

## Connecting and Initializing a Project

Before configuring LoopX, you must connect the project to create the hidden `.loopx/` directory and initialize a goal. The `loopx connect` command sets up the necessary state storage, while `loopx start-goal` creates the top-level objective that owns all subsequent configuration.

```bash

# Connect a fresh repository

cd /path/to/your-project
loopx connect

# Create a new goal (interactive)

loopx start-goal --guided --project . --goal-text "Build a multilingual chatbot"

```

These commands establish the `.loopx/` directory structure and the goal context required by the configuration system implemented in [`loopx/configure_goal.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/configure_goal.py).

## Inspecting Current Configuration

Always preview changes before applying them. The `--preview` flag shows the full catalog of settings for a specific goal without mutating the state stored in [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json).

```bash
loopx configure-goal --goal-id my-goal --preview

```

This safe-read operation queries the configuration catalog defined in the **Configure-Goal API contract** ([`docs/status-data-contract.md`](https://github.com/huangruiteng/loopx/blob/main/docs/status-data-contract.md)) and displays the current values for quotas, capabilities, and agent profiles.

## Applying Configuration Changes

To persist modifications, supply the same command with `--execute` or simply omit `--preview`. This updates the goal-level catalog and writes changes to [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)’s managed persistence layer.

```bash

# Enable the Explore capability

loopx configure-goal --goal-id my-goal --enable-explore --execute

# Disable a capability you no longer need

loopx configure-goal --goal-id my-goal --disable-explore --execute

```

All changes are atomic and versioned with the goal ID, allowing you to track the evolution of your LoopX setup over time.

## Common Configuration Options

### Compute Quotas

Control resource consumption per turn using the `--quota-compute` flag. This limits how many slots a goal may spend during each execution cycle.

```bash
loopx configure-goal --goal-id my-goal --quota-compute 5 --execute

```

### Spawn Policies and Capabilities

Enable optional capabilities such as **Explore** or **Auto-Research** using boolean flags. These policies determine which agents LoopX can spawn and what behaviors are permitted.

```bash

# Enable auto-research (adds scheduler hints and quota adjustments)

loopx configure-goal --goal-id my-goal --enable-auto-research --execute

```

Capability-specific options follow the pattern `--<capability>-<option>`, such as `--issue-fix-policy` for the `loopx issue-fix` command.

### Agent Profiles

Map registered peers to role-specific parameters using the `--profile` flag. This creates a mapping between agent IDs and their configuration profiles within the goal context.

```bash
loopx configure-goal --goal-id my-goal --profile agent-123=researcher --execute

```

### Environment Variable Overrides

For advanced scenarios, LoopX reads several environment variables at runtime:

- **`LOOPX_RUNTIME_ROOT`** – Directory where LoopX writes its state (defaults to `.loopx/`)
- **`LOOPX_REGISTRY`** – Path to a JSON file describing the project-wide registry of agents and capabilities
- **`LOOPX_PROMOTE_DEFAULT`** – Set to `1` to enable the installer to promote newly built releases

These variables are processed by the installer scripts ([`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh)) and runtime bridges before the CLI commands execute.

## Validating Your Configuration

After applying changes, verify the installation health and goal state using diagnostic commands:

```bash

# Verify the whole installation

loopx doctor

# Show active goal state and configuration

loopx status

```

Both commands are safe-read operations that surface misconfigurations without modifying state, as documented in the [`docs/guides/getting-started.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/getting-started.md) tutorial.

## Using Presets for Quick Setup

LoopX ships with read-only presets that bundle sensible configuration defaults. These presets provide quick ways to enable complete capability suites without hand-editing the catalog.

```bash

# List available presets

loopx preset list

# View details of the daily-triage preset

loopx preset show daily-triage

# Apply the preset to your goal

loopx preset apply daily-triage --goal-id my-goal

```

Common presets include `daily-triage` and `auto-research`, defined in [`docs/presets/daily-triage.md`](https://github.com/huangruiteng/loopx/blob/main/docs/presets/daily-triage.md) and referenced in [`docs/guides/auto-research-command-path.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/auto-research-command-path.md).

## Summary

- **Initialize** with `loopx connect` and `loopx start-goal` before configuring any settings.
- **Preview** changes using `--preview` and persist them with `--execute` to update [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json).
- **Manage resources** via `--quota-compute`, capabilities via `--enable-<feature>`, and agents via `--profile`.
- **Override** runtime locations using `LOOPX_RUNTIME_ROOT` and `LOOPX_REGISTRY` environment variables.
- **Validate** configurations with `loopx doctor` and `loopx status` to ensure healthy operation.
- **Accelerate** setup using built-in presets like `daily-triage` via `loopx preset apply`.

## Frequently Asked Questions

### What is the difference between `--preview` and `--execute` in LoopX configuration?

The `--preview` flag performs a dry-run that displays the current configuration catalog from [`docs/status-data-contract.md`](https://github.com/huangruiteng/loopx/blob/main/docs/status-data-contract.md) without writing to [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json), while `--execute` (or omitting `--preview`) persists the modifications to the goal-level state.

### Where does LoopX store configuration files?

LoopX stores all configuration in a project-local `.loopx/` directory, specifically within [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json), which is managed by [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) and versioned with the goal ID to support rollbacks and repeatable runs.

### How do I enable the Explore capability in LoopX?

Enable the Explore capability by running `loopx configure-goal --goal-id <your-goal> --enable-explore --execute`, which updates the spawn policy in the configuration catalog to allow the Explore agent to run within that goal context.

### Can I use environment variables instead of CLI flags for LoopX configuration?

Yes, you can set `LOOPX_RUNTIME_ROOT` to change the state directory, `LOOPX_REGISTRY` to specify a custom registry JSON file, and `LOOPX_PROMOTE_DEFAULT` to control release promotion, though goal-specific settings like quotas and capabilities still require the `configure-goal` CLI command.