인프라 프로필 (.llamon/profiles)

배포 환경별 Docker base image · PyPI mirror · 기본 env 를 담은 TOML 설정입니다. prepare-offline 실행 시 선택하면 해당 값이 Dockerfile, wheelhouse, .env 에 자동 주입됩니다.

TL;DR

목적	액션
내장 프로필 확인	`prepare-offline` 실행 시 선택 UI 에 `prod`, `stage` 표시
커스텀 프로필 추가	`.llamon/profiles/<name>.toml` 파일 생성
내장 프로필을 내 값으로 덮어쓰기	`.llamon/profiles/prod.toml` 에 같은 `name` 으로 작성
프로필 변경 반영	`prepare-offline` 다시 실행 (SDK 재빌드 불필요)

내장 프로필

SDK 번들 (단일 소스): llamon_agent/cli/profiles/{prod,stage}.toml

프로필	용도
`prod`	운영 환경 기본 프로필
`stage`	스테이지 환경 기본 프로필

선택 UI 는 prepare-offline 호출 시 자동으로 뜨며, 같은 이름의 프로젝트 프로필이 있으면 그것이 우선 적용됩니다.

TOML 스키마 (5 필드)

name        = "prod"                          # [필수] 선택 UI 표시명, 재정의 매칭 키
description = "운영 환경 기본 프로필"          # [선택] 선택 UI 부가 설명

python_base_image = "<internal-registry>/python:3.14-slim"    # [필수] Dockerfile FROM
pypi_index_url    = "http://<nexus-host>/repository/pypi/simple/"  # [필수] wheelhouse 다운로드 index

[env]                                          # [선택] 런타임 .env 에 주입할 기본값
LLAMON_REGISTRY_HOST      = "http://<registry-host>:7860"
TRACE_BACKEND             = "langfuse"          # langfuse | relay | none
LANGFUSE_PUBLIC_KEY       = "pk-lf-..."
LANGFUSE_SECRET_KEY       = "sk-lf-..."
LANGFUSE_BASE_URL         = "http://<langfuse-host>:3001"
LANGFUSE_RELAY_BASE_URL   = "http://<relay-host>:8008"  # TRACE_BACKEND=relay 일 때 사용

필드	역할
`name`	선택 UI 에 표시되며 재정의 매칭 기준. 필수
`description`	선택 UI 우측에 부가 설명으로 노출
`python_base_image`	폐쇄망 production `Dockerfile` 의 `FROM` 대상
`pypi_index_url`	`vendor-deps` 단계에서 wheel 을 다운로드할 index URL
`[env]`	런타임 환경변수 파일(`.env` 등)에 주입할 key/value — 주입 방식은 아래 동작 설명 참고

[env] 키는 자유롭게 추가할 수 있어요

정해진 키 목록은 없습니다. LANGFUSE_* 같은 예시 외에도 원하는 환경변수를 마음대로 넣으면 됩니다.

단, 값은 반드시 큰따옴표로 감싼 문자열이어야 합니다. 따옴표 없는 숫자·불리언은 조용히 무시됩니다.

[env]
PORT  = 8080      # ❌ 숫자 → 무시됨 (에러도 안 남)
DEBUG = true      # ❌ 불리언 → 무시됨
PORT  = "8080"    # ✅ 이렇게 문자열로
DEBUG = "true"    # ✅

커스텀 프로필 작성

.llamon/profiles/ 디렉토리에 <프로필명>.toml 파일을 생성합니다.

mkdir -p .llamon/profiles
cat > .llamon/profiles/dev.toml <<'EOF'
name        = "dev"
description = "사내 개발 네트워크"

python_base_image = "registry.dev.internal/python:3.14-slim"
pypi_index_url    = "http://pypi.dev.internal/simple/"

[env]
LLAMON_REGISTRY_HOST = "http://registry.dev.internal:7860"
TRACE_BACKEND        = "none"
EOF

다음 prepare-offline 실행부터 선택 UI 에 dev 가 추가됩니다.

덮어쓰기 우선순위

같은 name 이면 프로젝트 프로필이 내장 프로필을 덮어씁니다.

[1] 내장      prod, stage             ← SDK 번들
[2] 프로젝트  .llamon/profiles/*.toml ← 프로젝트 로컬
[3] 병합      같은 name 이면 [2] 가 [1] 을 대체
[4] 순서      내장 프로필 먼저 노출, 이후 커스텀 이름 순서대로

예: 운영 IP 만 바꿔야 할 때 .llamon/profiles/prod.toml 을 작성하면 내장 prod 를 통째로 대체합니다 (부분 재정의는 지원하지 않음 — 전체 필드를 작성해야 함).

`prepare-offline` 에서의 동작

uv run llamon prepare-offline ./my-agent

선택 UI 예시:

? Offline Infra Profile
> prod                                    운영 환경 기본 프로필
  stage                                   스테이지 환경 기본 프로필
  dev   (.llamon/profiles/dev.toml)       사내 개발 네트워크

선택한 프로필은 다음 3 경로로 주입됩니다.

소스	주입 대상
`python_base_image`	폐쇄망 `Dockerfile` 의 `FROM` 라인
`pypi_index_url`	`vendor-deps` 단계의 wheel 다운로드 설정
`[env]` 키/값	프로젝트의 런타임 환경변수 파일(`.env` 등)에 기록 — 같은 키가 이미 있어도 프로필 값으로 교체(아래 설명)

`[env]` 주입은 “관리형 덮어쓰기 + 자동 복원”

[env] 주입은 단순히 빈 키만 채우는 방식이 아닙니다. 프로필의 키는 SDK 가 추적하며 다음처럼 동작합니다.

프로필을 선택하면 [env] 의 모든 키가 .env 에 기록됩니다. 같은 이름의 기존 값이 있으면 프로필 값으로 교체됩니다.
교체 직전의 원래 값은 SDK 가 메타에 저장해 둡니다.
다른 프로필로 바꾸거나, 새 프로필에 그 키가 없으면 → 저장해 둔 원래 값으로 자동 복원됩니다.

즉 프로필 전환은 안전하게 되돌릴 수 있지만, 활성 프로필의 [env] 값이 기존 .env 값보다 우선합니다. 특정 키를 프로필이 건드리지 않게 하려면, 그 프로필 [env] 에서 해당 키를 빼면 됩니다.

문제 해결

증상	원인	해결
커스텀 프로필이 선택 UI 에 안 뜸	파일 위치/확장자 오류	`.llamon/profiles/<name>.toml` 경로·확장자 확인
`profile 이름이 없습니다` 에러	TOML 최상단 `name = "..."` 누락	`name` 필드 추가 (필수)
내장 프로필을 재정의했는데 값이 반영 안 됨	`name` 이 내장 프로필 이름과 다름	정확히 `prod` 또는 `stage` 로 작성
`[env]` 값이 `.env` 에 전혀 반영 안 됨	`.env` 파일이 없거나, 값에 따옴표 누락(숫자·불리언)	`.env` 를 먼저 생성하고, 값을 `"..."` 문자열로 작성 후 재실행
내 `.env` 값이 프로필 값으로 바뀜	정상 동작 — 활성 프로필이 같은 키를 덮어씀	프로필 `[env]` 에서 해당 키 제거 (다른 프로필로 바꾸면 원래 값 자동 복원)