# LoopX Configuration Options: Complete Guide to CLI Flags, Constants, and Environment Variables

> Master LoopX configuration options using CLI flags constants and environment variables. This guide covers all settings for efficient operation and customization.

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

---

**LoopX configuration options span three layers: CLI flags for runtime overrides, `DEFAULT_*` constants in [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py) for operational defaults, and environment variables for secrets and external service endpoints.**

LoopX is a highly configurable benchmark platform. Understanding its configuration surfaces is essential for customizing benchmark runs, tuning timeouts, and integrating with external services. This guide covers all LoopX configuration options with direct references to the source code in `huangruiteng/loopx`.

## CLI Flags for Benchmark Scripts

LoopX entry-point scripts expose standardized `--<name>` flags through `argparse.ArgumentParser`. These flags reference constants defined elsewhere, creating a consistent interface across the codebase.

### Dataset and Model Selection Flags

```python

# From scripts/terminal_bench_no_upload_smoke.py

parser.add_argument(
    "--dataset",
    default=TERMINAL_BENCH_DEFAULT_DATASET,
    help="Benchmark dataset identifier"
)
parser.add_argument(
    "--task-id",
    default=TERMINAL_BENCH_DEFAULT_TASK,
    help="Specific task within the dataset"
)
parser.add_argument(
    "--model",
    default=TERMINAL_BENCH_DEFAULT_MODEL,
    help="Model to evaluate"
)

```

### Mirror and Network Configuration Flags

```python

# From scripts/terminal_bench_task_image_bootstrap.py

parser.add_argument(
    "--apt-mirror",
    default=DEFAULT_APT_MIRROR,  # https://mirrors.tuna.tsinghua.edu.cn/debian

    help="Debian package mirror URL"
)
parser.add_argument(
    "--security-mirror",
    default=DEFAULT_SECURITY_MIRROR,  # https://mirrors.tuna.tsinghua.edu.cn/debian-security

    help="Debian security updates mirror"
)

```

### Timeout and Round Limits

| Flag | Default Value | Source Constant | Purpose |
|------|-------------|-----------------|---------|
| `--timeout-sec` | `7200` | `DEFAULT_TIMEOUT_SEC` | Global benchmark timeout (seconds) |
| `--max-rounds` | `16` | `DEFAULT_MAX_ROUNDS` | Maximum evaluation turns |

Defined in [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py) and consumed by test scripts.

### Reverse Tunnel Supervisor Flags

```python

# From scripts/skillsbench_reverse_tunnel_supervisor.py

parser.add_argument(
    "--remote-forward",
    default=DEFAULT_REMOTE_FORWARD,  # "127.0.0.1:18180:127.0.0.1:18180"

    help="SSH -R style port forwarding specification"
)
parser.add_argument(
    "--test-host",
    default=DEFAULT_TEST_HOST,  # "chatgpt.com"

    help="Host for connectivity validation"
)
parser.add_argument(
    "--test-port",
    type=int,
    default=DEFAULT_TEST_PORT,  # 443

    help="Port for connectivity validation"
)

```

### Output Formatting

- **`--pretty`** — Boolean flag (default: `False`) enabling human-readable JSON output across multiple scripts including [`terminal_bench_no_upload_smoke.py`](https://github.com/huangruiteng/loopx/blob/main/terminal_bench_no_upload_smoke.py).

## Default Constants in skillsbench_runner_constants.py

The file [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py) serves as the central hub for LoopX operational defaults. These constants define paths, timeouts, mirrors, and quotas used throughout the system.

### HTTP Endpoint Path Constants

```python

# Status server endpoints

DEFAULT_STATUS_PATH = "/status"
DEFAULT_REWARD_DRY_RUN_PATH = "/reward-dry-run"
DEFAULT_REWARD_APPEND_PATH = "/reward-append"
DEFAULT_CONFIGURE_GOAL_DRY_RUN_PATH = "/configure-goal-dry-run"
DEFAULT_CONFIGURE_GOAL_APPLY_PATH = "/configure-goal-apply"

# Extension endpoints

DEFAULT_EXTENSION_PRESENTATION_SURFACES_PATH = "/extension-presentation"
DEFAULT_EXTENSION_PROJECTION_PATH = "/extension-projection"

```

These paths are validated in [`tests/test_status_server_extension_projection.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_status_server_extension_projection.py).

### Timeout and Grace Period Constants

| Constant | Value | Use Case |
|----------|-------|----------|
| `DEFAULT_HOST_LOCAL_CODEX_BRIDGE_IDLE_TIMEOUT_SEC` | `3600` | Local CodeX bridge idle timeout |
| `DEFAULT_HOST_LOCAL_CODEX_TASK_OUTPUT_QUIET_TIMEOUT_SEC` | `600` | Quiet output detection for CodeX tasks |
| `DEFAULT_LOOPX_TURN_TERMINAL_FAILURE_GRACE_SEC` | `30` | Grace period after terminal failure |
| `DEFAULT_VERIFIER_PREP_TIMEOUT_SEC` | `120` | Verifier preparation timeout |
| `DEFAULT_SOFT_VERIFIER_TIMEOUT_SEC` | `600` | Verifier execution soft timeout |
| `DEFAULT_BENCHMARK_EGRESS_PROXY_PREFLIGHT_TIMEOUT_SEC` | `8.0` | Proxy preflight check timeout |

### Mirror and Repository Constants

```python

# Debian/Ubuntu mirrors

DEFAULT_UBUNTU_APT_MIRROR_BASE = "..."
DEFAULT_DEBIAN_APT_MIRROR_BASE = "https://mirrors.tuna.tsinghua.edu.cn/debian"
DEFAULT_DEBIAN_SECURITY_MIRROR_BASE = "https://mirrors.tuna.tsinghua.edu.cn/debian-security"

# Build artifact mirrors

DEFAULT_DOCKER_APACHE_ARCHIVE_MIRROR_BASE = "https://mirrors.huaweicloud.com/apache"
DEFAULT_DOCKER_MAVEN_MIRROR_URL = "https://repo.huaweicloud.com/repository/maven"
DEFAULT_DOCKER_PIP_INDEX_MODE = "mirror"
DEFAULT_DOCKER_APT_SOURCE_MODE = "mirror"

```

### Proxy and Network Bypass

```python
DEFAULT_BENCHMARK_EGRESS_NO_PROXY = (
    # Tuple of hosts bypassing egress proxy

    "localhost",
    "127.0.0.1",
    # ... additional internal hosts

)

```

## Environment Variable Configuration

LoopX reads environment variables for secrets and service endpoints, optionally loading from a `.env` file. The pattern is implemented across utility scripts including [`skills/loopx-pr-program/scripts/diff_snapshot.py`](https://github.com/huangruiteng/loopx/blob/main/skills/loopx-pr-program/scripts/diff_snapshot.py).

### Core Environment Variables

| Variable | Typical Purpose |
|----------|---------------|
| `LOOPX_API_KEY` | Authentication token for LoopX API |
| `LOOPX_DB_URL` | Database connection string |
| `LOOPX_REDIS_HOST` / `LOOPX_REDIS_PORT` | Redis cache server configuration |
| `LOOPX_S3_BUCKET` | Artifact storage bucket name |
| `LOOPX_SECRET` | Generic service secret |

### Environment Override Pattern

```python
import os
from loopx.status import DEFAULT_STATUS_PATH

# Environment takes precedence over code default

status_path = os.getenv("LOOPX_STATUS_PATH", DEFAULT_STATUS_PATH)

```

This pattern appears throughout [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) and related modules.

## Typed Configuration Objects

Higher-level LoopX modules wrap parsed arguments into dataclasses for type-safe configuration management.

### SkillsBenchTurnRuntimeConfig

```python
from loopx.benchmark_adapters.skillsbench_turn_runtime import (
    SkillsBenchTurnRuntimeConfig,
)

runtime_cfg = SkillsBenchTurnRuntimeConfig(
    max_turns=8,                           # Override default 16

    sequence_baseline_path="/data/baseline.json",
    terminal_policy="fixed-n",
)

```

Defined in [`loopx/benchmark_adapters/skillsbench_turn_runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/benchmark_adapters/skillsbench_turn_runtime.py), this dataclass consolidates benchmark runtime parameters.

### Quota Configuration

```python

# From loopx/quota.py

DEFAULT_COMPUTE_QUOTA = 1.0      # Float: compute units per window

DEFAULT_WINDOW_HOURS = 24        # Quota reset interval

DEFAULT_SLOT_MINUTES = 1         # Minimum reservation granularity

```

### Extension-Specific Configurations

The Lark Kanban extension demonstrates UI-specific configuration:

```python

# From loopx/extensions/lark/presentation/kanban.py

@dataclass
class LarkKanbanConfig:
    webhook_url: str
    app_id: Optional[str] = None
    encrypt_key: Optional[str] = None

```

## Configuration Resolution Order

LoopX applies a three-tier fallback system:

1. **CLI flags** — Highest priority, passed via `argparse`
2. **Environment variables** — Checked via `os.getenv()` when flags are omitted
3. **Default constants** — Final fallback to `DEFAULT_*` values in [`skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/skillsbench_runner_constants.py)

This layered approach ensures every setting can be overridden without code modification.

## Practical Configuration Examples

### Customizing a Benchmark Run

```python

# scripts/skillsbench_automation_loop.py pattern

import argparse
from loopx.runtime import RuntimeConfig

parser = argparse.ArgumentParser()
parser.add_argument("--max-rounds", type=int, default=16)
parser.add_argument("--timeout-sec", type=int, default=7200)

args = parser.parse_args()

cfg = RuntimeConfig(
    max_rounds=args.max_rounds,
    timeout_seconds=args.timeout_sec
)

```

### Docker Build with Custom Mirrors

```bash

# Override mirror defaults via CLI

python scripts/terminal_bench_task_image_bootstrap.py \
    --apt-mirror "https://deb.debian.org/debian" \
    --security-mirror "https://deb.debian.org/debian-security"

```

### Environment-Based Status Path

```python

# Export LOOPX_STATUS_PATH=/custom/status before execution

export LOOPX_STATUS_PATH="/api/v2/status"
python -m loopx.status

```

## Key Source Files

| File | Configuration Role |
|------|-------------------|
| [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py) | Central `DEFAULT_*` constant definitions |
| [`scripts/terminal_bench_no_upload_smoke.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/terminal_bench_no_upload_smoke.py) | Dataset/model CLI flags |
| [`scripts/terminal_bench_task_image_bootstrap.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/terminal_bench_task_image_bootstrap.py) | Apt/security mirror flags |
| [`scripts/skillsbench_reverse_tunnel_supervisor.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_reverse_tunnel_supervisor.py) | Network/tunnel configuration |
| [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Compute quota defaults |
| [`loopx/benchmark_adapters/skillsbench_turn_runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/benchmark_adapters/skillsbench_turn_runtime.py) | `SkillsBenchTurnRuntimeConfig` dataclass |
| [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | HTTP endpoint path constants |
| [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py) | Extension-specific config example |
| [`tests/test_status_server_extension_projection.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_status_server_extension_projection.py) | Path constant validation |

## Summary

- **CLI flags** in LoopX scripts provide runtime overrides with defaults referencing shared constants
- **[`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py)** contains all operational defaults: timeouts, mirrors, paths, and quotas
- **Environment variables** handle secrets and service endpoints, loadable from `.env` files
- **Typed dataclasses** like `SkillsBenchTurnRuntimeConfig` consolidate configuration for type-safe consumption
- **Resolution order**: CLI flags → environment variables → default constants

## Frequently Asked Questions

### How do I change the default timeout for benchmark runs?

Override `DEFAULT_TIMEOUT_SEC` by passing `--timeout-sec` to any benchmark script, or set the environment variable before execution. The constant is defined in [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py) with a default of **7200 seconds** (2 hours).

### Where are the Docker mirror configurations defined?

Mirror URLs for apt, Maven, PyPI, and Apache archives are defined as `DEFAULT_DOCKER_*` and `DEFAULT_*_MIRROR_BASE` constants in [`scripts/skillsbench_runner_constants.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_runner_constants.py). Override via CLI flags like `--apt-mirror` or environment variables depending on the specific script.

### Can LoopX configuration be loaded from a file?

LoopX supports `.env` file loading for environment variables, though it does not ship with a default configuration file. Create a `.env` file with variables like `LOOPX_API_KEY` and `LOOPX_DB_URL` in your working directory, and the platform will read these values at runtime.

### What is the difference between RuntimeConfig and SkillsBenchTurnRuntimeConfig?

`RuntimeConfig` provides general execution parameters like timeouts and round limits, while `SkillsBenchTurnRuntimeConfig` in [`loopx/benchmark_adapters/skillsbench_turn_runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/benchmark_adapters/skillsbench_turn_runtime.py) specializes in benchmark-specific settings including terminal policies and baseline sequence paths.