실행과 배포

프로젝트를 만든 뒤에는 대상 환경에 맞는 경로 하나를 고릅니다.

환경	명령	결과
로컬 개발	`llamon run`	`docker compose` 실행·정리
SSH 접근 가능한 서버	`llamon deploy`	전송, 압축 해제, 원격 compose 기동
외부 네트워크가 없는 폐쇄망	`llamon prepare-offline`	wheelhouse와 반입용 `tar.gz`
기존 산출물의 환경값만 변경	`llamon profile apply`	이미지·PyPI·런타임 env 갱신

deploy와 prepare-offline은 다른 경로입니다. SSH로 접속할 수 있어도 런타임 외부 통신이 막혔다면 폐쇄망 산출물을 만들어 반입하세요.

로컬 실행과 진단

llamon run은 compose.yml을 기준으로 docker compose up/down/ps를 감쌉니다.

# 이미지를 빌드하고 백그라운드로 실행한 뒤 상태를 봅니다.
uv run llamon run ./my-agent

# foreground 종료 뒤 컨테이너까지 정리합니다.
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 --format json

코드 수정이 이미지에 반영되지 않으면 --no-cache로 다시 빌드합니다. --no-build와 함께 쓰면 캐시 옵션은 무시됩니다.

llamon doctor는 평소 prepare-offline이 자동으로 실행합니다. 실패 원인을 따로 볼 때 직접 사용하세요.

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

진단 범위는 다음과 같습니다.

Python·uv·Docker·Compose 명령과 필수 프로젝트 파일
Flow graph·node와 남은 자리표시자
포트 충돌, Registry·모델·관측 백엔드 URL
SDK wheel·checksum·uv.lock·wheelhouse 무결성
폐쇄망에 남은 외부 URL과 base image 설정

차단 항목이 있으면 종료 코드 1을 반환합니다.

SSH 원격 배포

llamon deploy는 프로젝트를 압축해 scp로 보내고 원격 서버에서 압축을 푼 뒤 docker compose up을 실행합니다. 폐쇄망 반입 도구는 아닙니다.

흐름	Dockerfile	실행 방식
`llamon run`	`Dockerfile.compose`	로컬 `compose.yml`
`llamon deploy`	`Dockerfile.compose`	원격 `compose.yml`
`prepare-offline` 산출물	production `Dockerfile`	`docker build`·`docker run`

Dockerfile.compose·compose.yml은 예전에 Dockerfile.local·docker-compose.local.yml이었고, 배포 프로파일 compose는 local-compose였습니다. 옛 이름은 기한 없이 계속 지원합니다 — 기존 프로젝트에서 llamon run·deploy·doctor는 있는 파일을 그대로 찾아 쓰므로 파일명을 바꾸지 않아도 됩니다. --deploy-profile local-compose도 계속 받습니다. 신·구 compose 파일이 함께 있으면 compose.yml이 우선합니다.

compose.yml은 Docker Compose가 자동으로 찾는 기본 파일명이라, 프로젝트 루트에서 -f 없이 docker compose up을 실행해도 이 파일이 잡힙니다. 이때는 LLAMON_ENV_FILE이 지정되지 않아 .env가 쓰이므로, 다른 환경 파일을 쓴다면 LLAMON_ENV_FILE=.env.prod docker compose up처럼 함께 넘기세요.

# 기본 원격 경로는 /opt/<project-name>입니다.
uv run llamon deploy ./my-agent --target ubuntu@<원격주소>

# 경로, SSH 키와 포트를 지정합니다.
uv run llamon deploy ./my-agent \
  --target ubuntu@<원격주소> \
  --remote-dir /srv/llamon/my-agent \
  --identity-file ~/.ssh/prod.pem \
  --port 2222

# 기존 아카이브를 쓰거나 실행 계획만 확인합니다.
uv run llamon deploy ./my-agent \
  --target ubuntu@<원격주소> \
  --artifact ./dist/my-agent.tar.gz
uv run llamon deploy ./my-agent \
  --target ubuntu@<원격주소> \
  --dry-run --format json

로컬에는 ssh·scp·uv, 원격에는 docker·docker compose·bash·tar가 필요합니다. 전송과 압축 해제만 하려면 --no-up, 원격 이미지 재빌드를 생략하려면 --no-build를 사용합니다.

원격 서버가 PyPI에 접근하지 못한다면 전송 전에 uv run llamon vendor-deps ./my-agent로 wheelhouse를 만드세요. 외부 네트워크가 전혀 없는 환경은 아래 폐쇄망 경로를 사용합니다.

서버 리소스 권장

배포 단위는 Starlette ASGI 기반 agent 컨테이너입니다. 상태 backend가 PostgreSQL일 때만 postgres 사이드카가 함께 뜹니다. 대부분 LLM API·A2A·MCP·HTTP 응답을 기다리는 I/O 작업이며 GPU나 로컬 추론 자원은 필요하지 않습니다.

서비스	예약	상한	조건
`agent`	CPU 0.5 / 512MiB	CPU 1 / 1GiB	기본 운영 출발점
`postgres`	CPU 0.1 / 256MiB	CPU 0.5 / 512MiB	postgres backend일 때

동시 in-flight 호출이 32개 안팎이면 1GiB/2GiB, 64개 이상이거나 payload가 크면 2GiB/3~4GiB를 출발점으로 삼아 측정하세요. FANOUT_MAX_CONCURRENCY나 HTTP pool을 올릴 때 CPU·메모리와 파일 descriptor 상한도 함께 조정합니다. 512MiB는 예약값으로는 적절하지만 운영 상한으로 두면 fan-out 부하에서 OOM이 날 수 있습니다.

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

prepare-offline은 doctor → vendor-deps → doctor → package를 실행합니다. uv.lock이 없으면 먼저 생성하며 필요한 wheel과 무결성 파일, 반입 아카이브와 base image helper를 한 번에 준비합니다.

# 기본 준비
uv run llamon prepare-offline ./my-agent --profile prod --clean

# 대상 플랫폼과 ABI를 고정하는 교차 준비
uv run llamon prepare-offline ./my-agent --clean \
  --python-platform manylinux_2_17_x86_64 \
  --python-version 3.14 \
  --implementation cp \
  --abi cp314 \
  --abi abi3

성공하면 다음 산출물이 생깁니다.

산출물	용도
`dist/<project>-*.tar.gz`	폐쇄망 반입 아카이브
`wheelhouse/`·`wheelhouse.sha256`	의존성 wheel과 무결성
`deploy/export_base_image.*`	온라인 구간에서 base image 추출
`deploy/load_base_image.*`	폐쇄망 Docker에 image load
배포 체크리스트	내부 Registry·Nexus·실행 순서 확인

helper는 이미지를 load하고 내부용 tag를 붙이지만 Registry에 자동 push하지 않습니다.

다른 OS용 wheelhouse

production 패키지는 Linux Docker 배포를 전제로 합니다. Windows에 직접 설치할 wheel이 필요하면 별도 디렉터리를 사용하세요.

uv run llamon vendor-deps . \
  --wheelhouse wheelhouse-win \
  --python-platform win_amd64 \
  --python-version 3.14 \
  --implementation cp \
  --abi cp314 \
  --abi abi3

vendor-deps --clean은 대상 디렉터리의 기존 wheel을 지웁니다. Linux와 Windows 산출물을 같은 wheelhouse에 섞지 마세요. wheelhouse-win/은 기본 package와 doctor 범위 밖이므로 별도로 압축해 검증하세요.

SDK wheel 갱신

새 SDK wheel을 프로젝트 루트에 둔 뒤 제공되는 스크립트로 checksum, pyproject.toml과 lock을 함께 갱신합니다.

cd my-agent
./update_sdk_wheel.sh .
uv run llamon prepare-offline . --clean

다른 경로의 wheel은 --wheel /path/to/llamon_agent-X.Y.Z-py3-none-any.whl로 지정합니다. 수동으로 교체했다면 wheel checksum과 pyproject.toml 파일명, uv.lock을 모두 갱신한 뒤 doctor를 실행하세요.

온라인 개발 파일로 되돌릴 때는 ./deploy/restore-online.sh 또는 .\deploy\restore-online.ps1을 사용합니다. 다음 prepare-offline 실행에서 다시 폐쇄망 설정을 적용합니다.

인프라 프로필

.llamon/profiles/<name>.toml은 환경별 Docker base image, PyPI mirror와 기본 env를 묶습니다. SDK가 prod와 stage를 제공하며 같은 name의 프로젝트 파일이 내장 프로필 전체를 대체합니다. 부분 병합은 하지 않습니다.

name = "prod"
description = "운영 네트워크"
python_base_image = "registry.internal/python:3.14-slim"
pypi_index_url = "http://nexus.internal/repository/pypi/simple/"
pyproject_pypi_index_url = "http://nexus-host/repository/pypi/simple/"

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

필드	역할
`name`	선택 UI와 `--profile`의 필수 식별자
`description`	선택 UI 설명
`python_base_image`	production Dockerfile의 `FROM`
`pypi_index_url`	Docker build가 쓸 PyPI mirror
`pyproject_pypi_index_url`	host에서 `uv`가 쓸 index. 생략하면 위 값을 사용
`[env]`	런타임 env에 넣을 문자열 key/value

[env] 값은 따옴표로 감싼 문자열만 읽습니다. 대상 .env가 없으면 적용을 실패시킵니다.

uv run llamon profile list .

# 기존 wheelhouse와 package를 건드리지 않고 값만 바꿉니다.
uv run llamon profile apply . --profile stage --dry-run
uv run llamon profile apply . --profile stage --yes

# 값 적용 뒤 폐쇄망 산출물까지 다시 만듭니다.
uv run llamon prepare-offline . --profile prod --clean

profile apply는 Dockerfile, pyproject.toml index, 런타임 env와 deploy helper만 갱신합니다. vendor-deps와 package는 실행하지 않습니다. --profile을 생략하면 마지막 선택값, 그마저 없으면 prod를 사용합니다.

프로필이 바꾼 env의 원래 값은 SDK가 기록합니다. 다른 프로필에 같은 키가 없으면 이전 값을 복원합니다. 활성 프로필 값이 현재 .env보다 우선하므로 관리하지 않을 키는 [env]에서 빼세요.

배포 전 확인

llamon doctor .로 프로젝트와 폐쇄망 계약을 확인합니다.
run·deploy는 Dockerfile.compose, 폐쇄망 산출물은 production Dockerfile을 사용합니다.
deploy --dry-run --format json으로 원격 명령을 먼저 검토합니다.
인프라 프로필에는 비밀을 커밋하지 말고 배포 환경의 secret 주입을 사용합니다.
반복되는 오류는 문제 해결에서 진단 코드로 찾습니다.