toki/iop

toki 0d83ef378e 기능: bootstrap 명령을 positional token 방식의 한 줄 UX로 변경한다

사용자가 artifact URL, Edge 주소, token을 환경변수로 직접 설정하던
IOP_* named parameter 방식을 제거하고, curl | bash -s <token> 형태의
단일 positional token UX로 변경한다.

- bootstrap script에서 NODE_TOKEN을 첫 번째 인자로 받도록 변경
- token 누락 시 명확한 에러 메시지 출력
- artifact HTTP를 127.0.0.1 바인딩으로 변경
- docs, rules, roadmap에 one-line bootstrap UX 기준 기록

2026-05-27 17:56:27 +09:00

3.5 KiB

Raw Blame History

Field Bootstrap 작업 가이드

이 문서는 작업자/LLM이 field bootstrap 테스트를 이어갈 때 읽는 재개 가이드다. 사용자에게 그대로 전달하는 문서는 docs/field-bootstrap-user-test.md를 사용하고, 상세 runbook은 docs/deploy-dev.md를 확인한다.

핵심 규칙

Edge-Node 런타임 연결에 외부 공개가 필요한 포트는 19090 하나다.
18080은 bootstrap shell script, iop-node binary, checksum을 내려받는 artifact HTTP 포트다. Edge-Node 런타임 포트가 아니다.
외부 공개를 19090 하나로 제한할 때는 toki-labs.com:18080을 사용자 기본 명령으로 안내하지 않는다.
bootstrap/artifact는 내부망, front/control-plane, CI artifact, 또는 임시 로컬 HTTP 등 별도 채널로 전달한다.
생성되는 node.yaml의 transport.edge_addr만 외부 접속 주소인 toki-labs.com:19090으로 맞춘다.

현재 테스트 값

live version: field-live-20260527-19ddd9bd38b7
node token: iop-field-20260527-7fd4c675
node id: node-silicon-ollama
model: gemma4:26b
edge config 후보: /tmp/iop-edge-field-bootstrap.yaml

위 값은 임시 field 테스트 값이다. 장기 규약으로 고정하지 않는다.

재개 전 확인

stale process가 남아 있는지 먼저 본다.

ps -ef | rg 'python3 -m http.server 18080|go run ./apps/edge/cmd/edge|/tmp/go-build.*/edge serve|iop-edge serve'
netstat -ltnp 2>/dev/null | rg ':(18080|8080|9090)\b|Proto' || true

이전 테스트 프로세스가 남아 있으면 정리한 뒤 새 설정으로 띄운다.

권장 테스트 흐름

Apple Silicon bootstrap artifact를 만들 때 artifact URL과 edge runtime 주소를 분리한다.

VERSION=field-live-20260527-19ddd9bd38b7 \
APPS=node \
TARGETS="darwin/arm64" \
ARTIFACT_BASE_URL="<internal-artifact-url>" \
BOOTSTRAP_EDGE_ADDR="toki-labs.com:19090" \
DIST_DIR=dist/field \
./bin/build/field-binaries.sh

artifact HTTP가 필요하면 내부에서 접근 가능한 경로로만 연다.

python3 -m http.server 18080 --bind 127.0.0.1 -d dist/field/field-live-20260527-19ddd9bd38b7

Edge는 field config로 실행한다.

go run ./apps/edge/cmd/edge serve --config /tmp/iop-edge-field-bootstrap.yaml

기본 확인:

curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/v1/models
nc -vz toki-labs.com 19090

사용자에게 전달하는 bootstrap 명령의 URL은 artifact 전달 채널에 맞춰 작업자가 완성한다. 사용자 명령은 token 값 하나만 인자로 받는다. 사용자에게 <artifact-base-url> 같은 placeholder를 채우게 하지 않는다. 외부 18080을 열지 않는 흐름에서는 bootstrap script 안의 기본 Edge runtime 주소만 19090으로 들어가야 한다.

curl -fsSL <완성된-bootstrap-url> | bash -s iop-field-20260527-7fd4c675

성공 기준

Node host에서 toki-labs.com:19090에 연결할 수 있다.
Edge 로그에 node registered가 나온다.
/v1/models가 gemma4:26b를 반환한다.
OpenAI-compatible 호출에서 비어 있지 않은 응답 또는 SSE delta가 나온다.

주의

curl http://toki-labs.com:18080/... | bash는 외부 18080 공개를 전제로 하므로 기본 안내로 쓰지 않는다.
Cline 전용 감지나 provider별 분기는 만들지 않는다. OpenAI-compatible protocol 차원에서 안정화한다.
기본 configs/*.yaml에 field token이나 임시 host 값을 넣지 않는다.
테스트 후에는 임시 edge와 artifact server를 내려둔다.

3.5 KiB Raw Blame History