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

LoopX configuration options span three layers: CLI flags for runtime overrides, DEFAULT_* constants in 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

# 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

# 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 and consumed by test scripts.

Reverse Tunnel Supervisor Flags

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

Default Constants in skillsbench_runner_constants.py

The file 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

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

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

# 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

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.

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

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 and related modules.

Typed Configuration Objects

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

SkillsBenchTurnRuntimeConfig

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, this dataclass consolidates benchmark runtime parameters.

Quota Configuration

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

# 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

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

Practical Configuration Examples

Customizing a Benchmark Run

# 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

# 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

# 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	Central DEFAULT_* constant definitions
scripts/terminal_bench_no_upload_smoke.py	Dataset/model CLI flags
scripts/terminal_bench_task_image_bootstrap.py	Apt/security mirror flags
scripts/skillsbench_reverse_tunnel_supervisor.py	Network/tunnel configuration
loopx/quota.py	Compute quota defaults
loopx/benchmark_adapters/skillsbench_turn_runtime.py	SkillsBenchTurnRuntimeConfig dataclass
loopx/status.py	HTTP endpoint path constants
loopx/extensions/lark/presentation/kanban.py	Extension-specific config example
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 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 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. 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 specializes in benchmark-specific settings including terminal policies and baseline sequence paths.

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