로컬 실행/점검 + 폐쇄망 준비

개발 반복 → 폐쇄망 준비가 한 줄로 이어집니다. 개발이 끝나기 전에도 폐쇄망 준비를 미리 검증할 수 있어, 단계별로 끊어서 진행해도 됩니다.

llamon run        →    llamon prepare-offline
(개발 반복)            (폐쇄망 산출물 한 번에)

prepare-offline은 내부적으로 doctor → vendor-deps → doctor → package를 순서대로 실행하므로 따로 호출할 필요가 없습니다.

개요

명령	역할
`llamon run`	로컬 `docker compose` 실행/정리 (개발 반복)
`llamon doctor`	단독 진단 (실패 원인 파악할 때만 사용)
`llamon prepare-offline`	폐쇄망 산출물 한 번에 생성
`llamon restore-online`	폐쇄망 Dockerfile을 온라인용으로 되돌림

vendor-deps, package는 prepare-offline 내부 단계입니다. 별도 호출은 거의 필요하지 않으며, 필요하면 --help로 확인하세요.

1) 로컬 실행 (`llamon run`)

# 기본: up --build -d 후 ps 출력
uv run llamon run ./my-agent

# foreground 실행
uv run llamon run ./my-agent --no-detach

# foreground 종료 후 자동 down
uv run llamon run ./my-agent --no-detach --down-after

# 정리만 수행
uv run llamon run ./my-agent --down

# 예정 명령 확인
uv run llamon run ./my-agent --dry-run

llamon run은 docker-compose.local.yml 기준으로 docker compose up/down/ps를 감싼 명령입니다. 기본값은 up --build -d 뒤 ps까지 확인하는 흐름입니다.

2) 실행 전 점검 (`llamon doctor`)

평소엔 prepare-offline이 자동 실행하므로 직접 부르지 않아도 됩니다. 실패 원인을 따로 보고 싶을 때만 사용하세요.

uv run llamon doctor ./my-agent
uv run llamon doctor ./my-agent --output json

doctor가 점검하는 항목:

명령어: python, uv, docker, docker compose
필수 파일: main.py, .env.example, .env, docker-compose.local.yml
플로우 프로젝트: nodes.py, graph.py, agent_card.py 존재 여부와 TODO 노드 잔존 여부
코드 자리표시자: <YOUR_...> 형태의 미교체 값
포트 충돌: .env의 포트 키가 이미 사용 중인지 확인
URL 연결성: LLAMON_REGISTRY_HOST, OLLAMA_BASE_URL, LANGFUSE_BASE_URL
오프라인 필수 파일: SDK wheel, checksum, uv.lock, wheelhouse/, wheelhouse.sha256
폐쇄망 점검: 내부 Registry 주소 여부, 외부 URL 잔존 여부, base image 기본값

실패 항목이 있으면 종료 코드 1로 끝납니다.

3) 폐쇄망 준비 (`llamon prepare-offline`)

폐쇄망 배포에 필요한 모든 산출물(wheelhouse/, 무결성 파일, tar.gz 아카이브, base image 스크립트)을 한 번에 만듭니다.

# 기본: doctor → vendor-deps → doctor → package
uv run llamon prepare-offline ./my-agent --clean

# 대상 플랫폼/ABI 지정 (교차 컴파일)
uv run llamon prepare-offline ./my-agent --clean \
  --python-platform <platform-tag> \
  --python-version 3.14 \
  --implementation cp \
  --abi cp314

# 오프라인 Dockerfile base image 태그 지정
uv run llamon prepare-offline ./my-agent --clean \
  --python-base-image registry.internal/base/python:3.14-slim

내부 동작 순서: doctor → vendor-deps → doctor → package. uv.lock이 없으면 먼저 uv lock을 자동 실행합니다.

성공 후 함께 생성되는 파일:

dist/<agent>-YYYYmmdd-HHMMSS.tar.gz — 배포 아카이브
wheelhouse/, wheelhouse.sha256 — 의존성 wheel + 무결성
deploy/export_base_image.sh, deploy/load_base_image.sh (+ PowerShell 변형)
폐쇄망 체크리스트

# 온라인 환경: base image를 tar로 추출
./deploy/export_base_image.sh ./python-base-image.tar

# 폐쇄망 환경: base image 로드
./deploy/load_base_image.sh ./python-base-image.tar

load_base_image.sh는 현재 Docker 엔진에 이미지를 load하고 내부용 태그를 붙입니다.
내부 registry로 자동 push하지는 않습니다. 필요하면 별도 docker push.

3-1) 윈도우용 wheelhouse 분리 수집

prepare-offline은 Linux Docker 배포(linux/amd64)를 전제로 manylinux 휠만 받습니다. 윈도우 환경에 직접 pip install로 깔아야 한다면 vendor-deps를 별도로 호출해 보조 wheelhouse를 만드세요.

# 1) Linux용 — 기존대로
uv run llamon prepare-offline . --clean

# 2) Windows용 — 별도 디렉토리, 같은 uv.lock 기준
uv run llamon vendor-deps . \
  --wheelhouse wheelhouse-win \
  --python-platform win_amd64 \
  --python-version 3.14 \
  --implementation cp \
  --abi cp314 \
  --abi abi3

# 3) 윈도우 폐쇄망에서 설치
pip install --no-index --find-links wheelhouse-win -r requirements.txt

4) SDK 버전 업데이트

새 llamon_agent-*.whl을 받으면 아래 순서로 갱신합니다.

A. 자동 (권장) — `update_sdk_wheel.sh`

cd my-agent

# 1. 새 wheel 적용 (sha256 + pyproject.toml 자동 갱신, uv lock + sync 포함)
./update_sdk_wheel.sh .

# 2. 폐쇄망 산출물 다시 만들기
uv run llamon prepare-offline . --clean

update_sdk_wheel.sh는 모든 템플릿 프로젝트에 포함되어 있습니다.
./update_sdk_wheel.sh .는 새 wheel이 현재 프로젝트 루트에 이미 있을 때 사용합니다.

다른 경로에 있다면:

./update_sdk_wheel.sh --wheel /path/to/llamon_agent-X.Y.Z-py3-none-any.whl .

여러 프로젝트 일괄:

./update_sdk_wheel.sh --wheel llamon_agent-X.Y.Z-py3-none-any.whl ./agent-a ./agent-b

B. 수동 (스크립트가 동작 안 할 때)

스크립트가 실패하거나 사용할 수 없는 환경에서는 아래 4단계로 동일한 결과를 만들 수 있습니다.

cd my-agent
NEW_WHEEL=llamon_agent-X.Y.Z-py3-none-any.whl   # 새 파일명으로 교체

1. 기존 wheel/sha256 삭제 후 새 wheel 복사

rm -f llamon_agent-*.whl llamon_agent-*.whl.sha256
cp /path/to/$NEW_WHEEL .

2. sha256 재생성 (macOS는 shasum, Linux는 sha256sum)

# macOS
shasum -a 256 "$NEW_WHEEL" > "$NEW_WHEEL.sha256"

# Linux
sha256sum "$NEW_WHEEL" > "$NEW_WHEEL.sha256"

3. pyproject.toml의 wheel 파일명 교체

# 변경 전
llamon-agent = { path = "llamon_agent-0.1.1-py3-none-any.whl" }
# 변경 후 (파일명만 새 버전으로)
llamon-agent = { path = "llamon_agent-X.Y.Z-py3-none-any.whl" }

4. lock 갱신 + 동기화

uv lock --upgrade-package llamon-agent   # uv.lock이 있을 때
# uv.lock이 없으면: uv lock
uv sync --frozen --no-dev

5. 폐쇄망 산출물 재생성 (배포 대상이 폐쇄망인 경우)

uv run llamon prepare-offline . --clean

5) 폐쇄망 Dockerfile 되돌리기 (`llamon restore-online`)

prepare-offline이 만든 오프라인 Dockerfile을 원래의 온라인 버전으로 복원합니다.

uv run llamon restore-online ./my-agent

일반 개발 환경으로 다시 작업할 때 사용
prepare-offline을 다시 실행하면 다시 오프라인 Dockerfile로 갱신됩니다

주요 플래그

`llamon run`

플래그	설명
`source`	실행 대상 경로 (기본: 현재 디렉토리)
`--compose-file`	로컬 compose 파일명
`--no-build`	`up` 시 `--build` 생략
`--detach / --no-detach`	백그라운드 / foreground 실행
`--down`	`docker compose down --remove-orphans`만 실행
`--down-after`	`--no-detach` 종료 후 자동 down
`--dry-run`	실제 실행 없이 예정 명령 출력
`--format text\|json`	dry-run 출력 형식 (`json`은 `--dry-run`과 함께 사용)

`llamon doctor`

플래그	설명
`source`	진단 대상 경로 (기본: 현재 디렉토리)
`--output text\|json`	결과 출력 형식

`llamon prepare-offline`

플래그	설명
`source`	준비 대상 경로 (기본: 현재 디렉토리)
`--wheelhouse`	wheelhouse 출력 디렉토리 (기본: `<source>/wheelhouse`)
`--clean`	기존 wheelhouse의 `.whl`과 manifest 정리 후 재생성
`--python-platform`	대상 플랫폼 지정
`--python-version`	대상 Python 버전 지정
`--implementation`	대상 Python implementation 지정
`--abi`	대상 ABI 지정 (반복 가능)
`-o, --output`	최종 아카이브 출력 경로
`--python-base-image`	오프라인 Dockerfile에 쓸 Python base image 태그
`--no-wheelhouse`	wheelhouse 단계 스킵 (이미 만들어진 경우)
`--force`	같은 파일명 덮어쓰기
`--dry-run`	실제 실행 없이 단계만 출력

vendor-deps, package 플래그는 --help로 확인하세요. 일반 흐름에서는 직접 호출하지 않습니다.

다음 단계

폐쇄망 배포: 원격 배포
자주 발생하는 오류: 문제 해결

로컬 실행/점검 + 폐쇄망 준비

개요

1) 로컬 실행 (llamon run)

2) 실행 전 점검 (llamon doctor)

3) 폐쇄망 준비 (llamon prepare-offline)