RuntimeConfig — 런 하나를 통째로 기술하는 단일 계약

시뮬레이션 한 번(run)을 실행하려면 정해야 할 게 많습니다 — 어떤 환경에서, 어떤 로봇 몇 대를, 어떤 시나리오로, 어떤 센서를 켜고, 어떤 옵션으로. 이 모든 걸 하나의 선언적 객체로 묶은 게 RuntimeConfig입니다. 런의 "주문서"인 셈입니다.

무엇을 vs 어떻게

RuntimeConfig의 핵심 설계는 "무엇을 돌릴지(선언)"와 "어떻게 돌릴지(엔진)"를 분리하는 것입니다.

도식 렌더링 중…

사용자/API는 "무엇을"만 적습니다. "어떻게"(어느 GPU 노드, 어떤 프로세스, 물리 스텝)는 오케스트레이터·워커·러너가 알아서 합니다. 이 분리 덕분에 같은 주문서가 어느 노드에서든 동일하게 실행됩니다.

RuntimeConfig가 담는 주요 항목:

항목	내용
환경	어떤 USD 환경/맵
로봇	어떤 매니페스트의 로봇 몇 대, 초기 위치
시나리오	어떤 OSC 시나리오
센서	LiDAR/카메라/IMU 구성
옵션	스트리밍·녹화·오버레이 on/off

옵션은 기본 OFF — 시간 낭비 방지

옵션 설계엔 원칙이 하나 있습니다.

💡 무거운 옵션은 기본 OFF — 미션 오버레이, 영상 export 같은 무거운 부가 기능은 명시적으로 켤 때만 켜야 합니다. 모든 런에서 기본으로 켜두면, 정작 필요 없는 검증 런에서 GPU·시간을 낭비합니다. "기본은 가볍게, 필요하면 명시적으로"가 계약의 기본값 철학입니다.

⚠️ 테스트는 이 계약을 통해서만 — 런을 ssh로 러너를 직접 띄워 테스트하면, RuntimeConfig 경로를 우회해 실제 프로덕션 경로와 다른 동작을 검증하게 됩니다. 검증은 반드시 이 계약(POST /runs)을 통해, 프로덕션과 같은 경로로 해야 의미가 있습니다.

왜 단일 계약인가

런을 기술하는 방법이 여러 갈래로 흩어지면(절반은 API, 절반은 환경변수, 절반은 코드 기본값) 재현이 안 됩니다. RuntimeConfig라는 단일 진입점이 있으면, "이 주문서"만 있으면 누구든 같은 런을 똑같이 재현할 수 있습니다 — 이것이 self-containment 철학이 런 실행에 적용된 모습입니다.

한 줄 정리

📌 RuntimeConfig는 환경·로봇·시나리오·센서·옵션을 하나로 묶어 런을 기술하는 단일 계약이다. "무엇을 돌릴지(선언)"와 "어떻게 돌릴지(엔진)"를 분리하고, 무거운 옵션은 기본 OFF이며, 검증은 반드시 이 계약(프로덕션 경로)을 통해 한다.