IOP

IOP(Inference Operations Platform)는 단순한 모델 라우터나 OpenAI API proxy가 아니다.

IOP는 Control Plane - Edge - Node 계층 구조를 기반으로, 여러 로컬 모델 런타임과 CLI Agent 실행 환경을 통합 관리하는 실행 오케스트레이션 플랫폼을 지향한다. 모델 서빙, CLI Agent 실행, shell/git/docker/code workspace 작업, node maintenance 작업을 같은 실행 파이프라인에서 다룰 수 있도록 만드는 것이 핵심 방향이다.

현재 프로젝트는 완성된 운영 시스템이 아니라 스켈레톤 단계다. 이 README는 현재 구현의 세부 사용법보다, 프로젝트가 향하는 구조와 경계를 명확히 설명한다.

Overview

IOP의 실행 대상은 크게 두 가지다.

• Model Serving
  • Ollama
  • vLLM
  • MLX
  • 그 외 로컬/원격 모델 런타임
• Agent / Automation Execution
  • CLI Agent
  • Shell
  • Git
  • Docker
  • Code workspace 작업
  • NomadCode 계열 자동화 작업

IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다.

Core Concept

IOP의 중심 개념은 adapter + target 기반 실행이다.

• adapter는 실행 방식을 나타낸다.
• target은 해당 adapter 안에서 실행할 구체 대상을 나타낸다.
• execution은 adapter와 target을 해석해 실제 Node에서 수행되는 단위다.

예시는 다음과 같다.

adapter = ollama
target  = qwen3.6

adapter = vllm
target  = gemma4

adapter = cli
target  = cline-dgx

adapter = cli
target  = codex-local

외부 OpenAI API 호환 계층에서는 호환성을 위해 model 필드가 남을 수 있다. 그러나 내부 실행 개념에서는 모델 이름만으로 전체 실행을 설명하지 않고, adapter, target, execution, node adapter, adapter execution 같은 용어를 우선한다.

Architecture

IOP는 Control Plane이 Edge를 통해 시스템을 제어하고, Edge가 자신의 로컬 실행 그룹을 운영하는 구조를 지향한다.

Control Plane
├─ Edge Group A
│  ├─ Node 1
│  ├─ Node 2
│  └─ Node 3
└─ Edge Group B
   ├─ Node 4
   └─ Node 5

Control Plane은 Node에 직접 연결하지 않는다. 전체 시스템 제어는 Edge를 통해 이뤄지고, Edge는 자신이 관리하는 Node와 로컬 런타임 상태의 원본을 가진다.

핵심 문장은 다음과 같다.

Control Plane은 Edge를 통해 시스템을 제어하고, Edge는 자신의 로컬 런타임 상태를 소유하고 운영한다.

Control Plane

Control Plane은 자체 서버와 프론트 페이지를 가진 중앙 관리 계층이다.

주요 책임은 다음과 같다.

• 여러 Edge 연결 관리
• Edge 상태 조회
• Edge 설정 변경
• Edge에 명령 전달
• Edge 이벤트 수신
• 전체 시스템 관찰
• Runtime 영역과 Automation 영역을 나눠 보여주는 운영 화면 제공

Control Plane과 Edge는 소켓 기반 연결을 사용하고, 이벤트, 상태, 명령 결과를 실시간으로 주고받는 구조를 지향한다.

Control Plane은 전통적인 Kubernetes식 중앙 스케줄러가 아니다. 다음 책임은 Control Plane에 두지 않는다.

• Node 직접 연결
• Node 직접 스케줄링
• Edge 내부 DB 대체
• 모든 런타임 상태의 단일 원본화
• 매 요청마다 Node 할당 판단

Edge

Edge는 단순 API gateway가 아니라 백엔드 전용 실행 그룹 컨트롤러다.

하나의 Edge는 여러 Node를 관리하며, 특정 디바이스 그룹, 로컬 모델 그룹, 자동화 실행 그룹을 하나로 묶는 단위가 된다. Edge는 모델 서빙과 CLI Agent 실행을 모두 처리할 수 있어야 한다.

Edge의 핵심 역할은 다음과 같다.

• Node registry
• Node configuration
• Adapter/Profile configuration
• Runtime routing
• Job assignment
• Stream relay
• Session handling
• Local runtime state
• Execution history aggregation
• Event aggregation

Edge는 자신의 데이터를 자체적으로 가진다. Control Plane은 Edge의 데이터를 조회하고 조정하지만, 런타임 데이터의 원본은 Edge다.

Node

Node는 실제 실행자다.

Node는 모델 런타임, CLI Agent, 도구 실행을 담당한다. Node는 Control Plane이 아니라 Edge에 연결되며, Edge가 전달한 실행 요청을 adapter execution으로 수행하고 이벤트와 결과를 되돌려준다.

Node는 가능한 한 단순한 실행 단위로 유지한다. 정책, 전체 시스템 조정, 다중 Edge 운영 판단을 Node에 밀어 넣지 않고, 전달받은 실행을 안정적으로 수행하는 데 집중한다.

Execution Model

Adapter and Target

IOP 내부 실행은 model 중심이 아니라 adapter 중심으로 정리한다.

• adapter: mock, ollama, vllm, cli 같은 실행 구현
• target: adapter 안에서 선택되는 모델, profile, agent, toolchain
• execution: 특정 adapter와 target으로 수행되는 단일 실행
• node adapter: Node 안에 등록되어 실제 실행을 담당하는 adapter
• adapter execution: Node adapter가 수행하는 실행 단위

현재 코드에는 RunRequest, ExecutionSpec, RuntimeEvent, NodeCommandRequest처럼 이 방향을 담기 위한 타입들이 있다. 세부 계약과 schema는 작업을 진행하면서 점진적으로 정리한다.

Runtime Domain

Runtime Domain은 모델 서빙 중심 실행 영역이다.

• OpenAI API 호환 요청
• Ollama, vLLM, MLX 같은 모델 런타임
• 모델 라우팅
• 추론 요청 처리
• 모델 런타임 adapter 확장

이 영역에서도 내부적으로는 adapter + target 개념을 사용한다. 예를 들어 OpenAI 호환 요청의 model 값은 내부에서 특정 adapter와 target으로 해석될 수 있다.

Automation Domain

Automation Domain은 CLI Agent와 도구 실행 중심 영역이다.

• CLI Agent 실행
• Shell, Git, Docker 작업
• code workspace 작업
• Plane 작업과 유지보수 작업
• Claude CLI, Gemini CLI, Codex CLI, OpenCode, Cline 같은 실행 대상

NomadCode는 IOP 안에 완전히 흡수된 제품이 아니라, IOP Automation Domain 위에서 동작할 수 있는 대표 사용처로 본다.

IOP Core
└─ 공통 실행 오케스트레이션 계층

NomadCode
└─ IOP Automation Domain을 활용하는 개발 업무 자동화 도메인

Current Status

현재 go-iop는 스켈레톤 단계다.

• Edge-Node 소켓 기반 구조를 우선 검증 중이다.
• Node 등록, 설정 전달, 실행 요청, 스트리밍 이벤트 흐름이 점진적으로 정리되고 있다.
• CLI adapter 쪽 구현이 먼저 진행되고 있다.
• 현재 실행 이력은 Node local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
• mock adapter와 dummy/TODO 구현은 개발 단계에서 정상적인 구성이다.
• Ollama/vLLM 등 모델 runtime adapter는 단계적으로 확장한다.
• Control Plane은 향후 여러 Edge 관리와 프론트 페이지 제공을 위해 추가된다.

현재 앱 구성은 다음과 같다.

경로	현재 의미
apps/node	Edge에 연결되어 adapter execution을 수행하는 Node agent
apps/edge	Node registry, 설정 전달, routing, stream relay를 담당하는 Edge skeleton
apps/control-plane	향후 여러 Edge를 연결하고 운영 화면을 제공할 중앙 관리 계층
apps/worker	향후 비동기 작업 처리 가능성을 위한 placeholder
packages	설정, 인증, 정책, 작업, 관측성, 버전 등 공통 패키지
proto	앱 간 메시지 계약 원본과 생성물
configs	현재 개발용 설정 예시

Roadmap

Phase 1. Edge-Node execution skeleton

• Edge-Node 소켓 연결
• Node adapter execution
• CLI adapter 검증
• adapter + target 개념 정리

Phase 2. Runtime and Automation unification

• 모델 서빙 adapter 확장
• CLI Agent 실행 안정화
• Runtime / Automation 실행 흐름 공통화
• Node local execution history와 Edge event aggregation 경계 정리

Phase 3. Control Plane

• 자체 서버와 프론트 페이지 제공
• 여러 Edge 연결
• Edge 상태 조회
• Edge 설정 변경
• Edge 명령 전달
• 이벤트 수신

Phase 4. Multi-Edge operations

• 여러 Edge group 관리
• Edge별 runtime/automation 상태 표시
• Edge 단위 실행 이력과 상태 집계
• Edge 단위 작업 실행과 제어

Phase 5. Policy, History, Audit

• 권한, 정책, 이력, 감사 기능 확장
• 상세 설계는 후속 작업에서 결정

Development Notes

• 기존 구조를 우선하며, 세부 구현은 각 작업의 domain rule과 현재 코드 경계를 먼저 확인한 뒤 진행한다.
• 내부 통신은 TCP/protobuf 기반 소켓 흐름을 우선한다.
• gRPC 도입, WebSocket 기본 transport 전환, actor/FSM/plugin framework 도입은 현재 단계의 기본 방향이 아니다.
• OpenAI API 호환 계층은 외부 호환을 위한 표면이며, 내부 실행 모델 전체를 대표하지 않는다.
• 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다.

Non-Goals for Current Stage

이번 단계에서는 다음 내용을 루트 README에서 상세 설계로 확정하지 않는다.

• 상세 DB schema
• 상세 protobuf 설계
• 상세 event schema
• 상세 permission model
• 상세 policy engine 설계
• 상세 audit log 구조
• Edge federation 세부 설계
• mTLS 세부 구현 계획
• Control Plane UI 화면별 상세 기획
• Plane 연동 상세 workflow
• NomadCode 상세 제품 설계