IOP

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

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

IOP는 NomadCode 전용 Agent Shell이 아니라, NomadCode와 외부 agent, 운영 CLI, Client, 자동화 도구가 함께 소비할 수 있는 범용 추론/자동화 운영 엔진이다. NomadCode는 IOP의 중요한 소비자 중 하나지만, IOP의 프로토콜과 운영 계층은 특정 제품 UX에 종속되지 않는다.

모델 선택, 로컬/클라우드 라우팅, 모델별 profile, token/속도/품질 최적화, 모델 호출 로그와 품질 평가는 IOP 책임으로 둔다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 기본 모델 서빙과 부하 라우팅이 가능해진 뒤 확장하는 최적화 계층으로 본다.

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

개요

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

• 모델 서빙
  • OpenAI-compatible model 호출
  • Ollama
  • vLLM
  • MLX
  • 그 외 로컬/원격 모델 런타임
• Agent / Automation 실행
  • CLI Agent
  • Shell
  • Git
  • Docker
  • Code workspace 작업
  • NomadCode 계열 자동화 작업
  • OTO 같은 build/deploy domain agent

IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다. 다만 모든 실행자를 iop-node 하위 프로세스로 흡수하지는 않는다. OTO처럼 자체 도메인과 배포 단위를 가진 자동화 도구는 Edge에 직접 붙는 specialized domain agent로 다룰 수 있다.

핵심 개념

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 같은 용어를 우선한다.

아키텍처

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

Control Plane
├─ Edge Group A
│  ├─ Node 1
│  ├─ Node 2
│  └─ OTO Agent 1
└─ Edge Group B
   ├─ Node 3
   └─ OTO Agent 2

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

핵심 문장은 다음과 같다.

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

운영 표면은 두 층으로 나눈다. iop-edge CLI는 Control Plane 없이도 bootstrap, local config, 진단, node 등록 command 발급, smoke, 단일 Edge 유지보수를 할 수 있는 field/fallback interface로 유지한다. Control Plane은 여러 Edge를 상시 관찰하고 명령, 정책, 감사, 팀 운영 UX를 제공하는 기본 운영면으로 확장한다. 둘 다 필요한 작업은 Edge가 소유한 shared operation으로 분류하고, CLI와 Control Plane이 각각 구현을 복제하지 않는다.

제어면(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
• Domain agent registry
• Edge-managed Node bootstrap/configuration
• Agent bootstrap/enrollment
• Adapter/Profile configuration
• Runtime routing
• Edge service API surface
• Job assignment
• Stream relay
• Session handling
• Local runtime state
• Execution history aggregation
• Event aggregation

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

현재 edge 내에는 edge-local ops console이 있다. ops console의 / 명령은 apps/edge/internal/service를 호출하는 얇은 어댑터이며, 향후 HTTP/API handler도 같은 service를 호출하는 방향이다. HTTP/API를 central/remote management surface로, ops console을 edge-local diagnostic surface로 구분한다. 실행 이벤트와 node lifecycle 이벤트는 apps/edge/internal/events bus를 통해 fanout한다.

새 command나 운영 기능은 먼저 Edge-local 필수, Control Plane 기본, shared operation 중 하나로 분류한다. Edge-local 필수 범위에는 bootstrap/config/env/setup/node register/nodes list/smoke 같은 Control Plane 없는 field 경로가 들어가고, Control Plane 기본 범위에는 multi-edge 관찰, fleet-wide command, 정책/감사, 반복 운영 리포트가 들어간다.

Node

Node는 실제 실행자다.

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

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

도메인 에이전트(Domain Agent)

Domain agent는 특정 자동화 도메인을 자체 바이너리와 자체 실행 모델로 가진 Edge 연결 실행자다.

OTO는 build/deploy domain agent의 대표 후보로 둔다. oto-agent는 iop-node를 통해 터미널 실행되는 하위 프로세스가 아니라, Edge에서 생성된 agent 등록 정보와 bootstrap command를 사용해 설치되고 Edge에 직접 outbound 연결한다. Edge는 OTO agent를 별도 agent type으로 인식하고, build run, cancel, status, capability, artifact, log event를 메시지 기반으로 제어한다.

이 경계에서 iop-node는 generic execution agent이고, OTO는 specialized build/deploy agent다.

Worker 구조

Edge, Node, Control Plane은 별도 iop-worker 앱으로 분리하지 않고, 각 Go 서비스 내부의 공통 Worker 모듈을 사용한다. 공통 처리 모델은 Job Queue, Worker Pool, Job Status, Retry, Timeout, Cancel이며, Worker가 담당하는 역할은 서비스별 책임에 맞춰 분리한다.

• Edge Worker
  • 사용자 요청 처리 흐름에 붙는 짧은 병렬/비동기 작업을 담당한다.
  • intent 분석, history refinement, routing 보조, 응답 validation, fallback 판단, stream 종료 후 usage/log/metric 기록을 처리한다.
• Node Worker
  • 모델 런타임과 로컬 프로세스에 붙는 작업을 담당한다.
  • runtime adapter 처리, model process 상태 감시, local queue 처리, streaming relay 보조, local metric/log flush를 처리한다.
• Control Plane Worker
  • 운영/관리/스케줄 기반 작업을 담당한다.
  • node health 수집, model registry 동기화, policy/config 배포, drain/reload 명령, benchmark/job 실행, 운영 리포트와 cleanup 작업을 처리한다.

실행 모델

어댑터와 대상(Adapter / 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, EdgeNodeEvent처럼 이 방향을 담기 위한 타입들이 있다. RunEvent는 adapter execution stream에, EdgeNodeEvent는 node 연결/해제 같은 edge-node lifecycle과 이후 제어/상태성 이벤트에 사용한다. 세부 계약과 schema는 작업을 진행하면서 점진적으로 정리한다.

런타임 도메인(Runtime Domain)

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

• OpenAI-compatible /v1/models, /v1/chat/completions baseline
• OpenAI-compatible /v1/responses 계획 표면
• Ollama, vLLM, MLX 같은 모델 런타임
• 로컬/클라우드 모델 라우팅
• 모델 profile과 부하 라우팅
• 추론 요청 처리
• usage, 호출 로그, 품질 평가 신호
• 모델 런타임 adapter 확장

이 영역에서도 내부적으로는 adapter + target 개념을 사용한다. 예를 들어 OpenAI 호환 요청의 model 값은 내부에서 특정 adapter와 target으로 해석될 수 있다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 이 기본 serving/load routing 기반이 정리된 뒤 Runtime 최적화 계층으로 확장한다.

자동화 도메인(Automation Domain)

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

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

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

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

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

현재 상태

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

• Edge-Node 소켓 기반 구조를 우선 검증 중이다.
• Node 등록, 설정 전달, 실행 요청, 스트리밍 이벤트 흐름이 점진적으로 정리되고 있다.
• Edge 내부에는 API 전환을 고려한 apps/edge/internal/service와 in-process event fanout인 apps/edge/internal/events가 있다.
• cli adapter(node execution implementation) 쪽 구현이 먼저 진행되고 있다.
• OpenAI-compatible API는 현재 /v1/models, /v1/chat/completions baseline을 기준으로 정리되어 있으며, /v1/responses 호환은 후속 모델 서빙/라우팅 단계의 필수 표면으로 둔다.
• edge-local ops console의 / 명령은 수동 테스트 표면이며, 장기 인터페이스는 별도 HTTP/API 표면으로 추가한다.
• 현재 실행 이력은 Node local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
• mock adapter와 dummy/TODO 구현은 개발 단계에서 정상적인 구성이다.
• Ollama/vLLM 등 모델 runtime adapter는 단계적으로 확장한다.
• Control Plane은 향후 여러 Edge 관리와 Client 제공을 위해 추가된다.
• packages/flutter/iop_console에는 공통 agent_shell 패키지를 사용하는 IopConsoleShell과 IopAgentPanel scaffold가 있다. 이 패키지는 IOP 운영/유지보수 agent 표면의 시작점이며, IOP 단독 앱과 NomadCode 같은 외부 소비자에 임베드되는 UI 모두에서 재사용 가능한 방향으로 둔다.

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

경로	현재 의미
apps/client	IOP Client UI의 기준 구현인 Flutter 애플리케이션. packages/flutter/iop_console을 mount하며 Flutter Web 산출물이 compose web 서비스로 배포된다
packages/flutter/iop_console	IOP-owned embeddable Flutter console package. 좌측 rail shell과 agent_shell 기반 IOP agent panel을 제공한다
apps/node	Edge에 연결되어 adapter execution을 수행하는 Node agent
apps/edge	Node/domain agent registry, 설정 전달, bootstrap, routing, stream relay를 담당하는 Edge skeleton
apps/control-plane	여러 Edge를 연결하고 Client과 통신할 Go 기반 운영 제어 서버 스캐폴드
apps/worker	현재 placeholder이며, Worker 구조는 우선 각 Go 서비스 내부 공통 모듈 방향으로 둔다
packages/go	설정, 인증, 정책, 작업, 관측성, 버전 등 Go 공통 패키지
packages/flutter	Flutter 재사용 패키지 root. 현재 iop_console package를 둔다
proto	앱 간 메시지 계약 원본과 생성물
configs	현재 개발용 설정 예시

Client의 장기 UI 기준은 Flutter 앱이며, 필요한 웹 표면은 Flutter Web 산출물로 제공한다. apps/control-plane은 Go 기반 운영 제어 서버다. 주요 통신은 edge-node에서 사용 중인 proto-socket을 IOP Wire Protocol 기준으로 Client-Control Plane, Control Plane-Edge, Edge-Node 방향으로 확장한다. Client-Control Plane은 앱/브라우저 경계를 고려해 proto-socket WebSocket/WSS를 우선하고, net/http는 health/readiness/bootstrap 같은 보조 endpoint 용도로 유지한다.

가이드

사람이 읽는 최신 실행 가이드는 Edge-local Dev Guide 하나로 유지한다.

로드맵

제품 방향, 단계, 마일스톤, 우선순위의 단일 기준 문서는 agent-roadmap/ROADMAP.md다. 일반 작업에서 AI가 읽어야 하는 현재 작업 기준은 agent-roadmap/current.md가 가리키는 기본 마일스톤 또는 요청에 맞는 활성 마일스톤 문서다.

로드맵의 큰 축은 Edge-Node 실행 기반, Edge input surface, CLI Automation runtime, remote terminal bridge, agent bootstrap/OTO enrollment, 모델 서빙과 부하 라우팅, RAG/web search/MCP/tool policy/검증 최적화, Control Plane/Client, policy/history/audit, multi-edge operations로 관리한다.

개발 메모

• 기존 구조를 우선하며, 세부 구현은 각 작업의 domain rule과 현재 코드 경계를 먼저 확인한 뒤 진행한다.
• Edge-Node 내부 통신은 TCP/protobuf 기반 소켓 흐름을 우선한다.
• Client-Control Plane처럼 앱/브라우저 표면이 필요한 경계는 proto-socket WebSocket/WSS를 사용할 수 있다. Edge-Node 기본 transport를 WebSocket으로 전환하거나 gRPC, actor/FSM/plugin framework를 도입하는 것은 현재 단계의 기본 방향이 아니다.
• OpenAI-compatible API 계층은 외부 모델 호출 호환을 위한 표면이며, 내부 실행 모델 전체를 대표하지 않는다.
• OpenAI-compatible API는 현재 chat completions baseline을 가지며, Responses API 호환 표면까지 지원하는 방향으로 확장한다.
• A2A API 계층은 agent 간 작업 위임과 상태 공유를 위한 표면이며, 단순 모델 호출 호환은 OpenAI-compatible API를 사용한다. NomadCode의 A2A 도입 시점은 아직 강제하지 않는다.
• IOP native protocol은 OpenAI-compatible API나 A2A API를 대체하는 것이 아니라, Edge/Node 운영 제어와 CLI/session/command/event 같은 IOP 고유 기능을 제공하는 병행 표면이다.
• Remote terminal bridge는 Edge/Node 운영 제어 기능으로 분류하며, OpenAI-compatible API가 아니라 IOP native protocol과 정책/audit 계층에서 다룬다.
• 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다.

현재 단계에서 다루지 않는 것

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

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