SDK 설정 및 확장 관리

sima-cli sdk setup을 실행할 때 선택적 SDK 서비스, 브라우저 VS Code 확장 및 Model Compiler 설치 원본을 선택합니다.

명령 참조: sima-cli sdk setup

컨테이너 이미지 빌드 및 공유

DevKit과 함께 SDK 3.0 이상을 설정하면 sima-cli는 작은 로컬 컨테이너 레지스트리 생성을 제안합니다. 레지스트리는 호스트에 이미지를 저장하므로 SDK 컨테이너가 교체되어도 이미지를 계속 사용할 수 있습니다.

레지스트리는 포트 5050에서 시작합니다. 해당 포트를 이미 사용 중이면 sima-cli가 자동으로 다음 사용 가능한 포트를 선택하고 선택한 주소를 표시합니다.

설정은 SDK 셸 안에서 사용할 수 있는 두 주소도 제공합니다.

• SIMA_CONTAINER_REGISTRY는 SDK가 이미지를 푸시하는 데 사용하는 주소입니다.
• SIMA_DEVKIT_CONTAINER_REGISTRY는 DevKit이 동일한 이미지를 풀하는 데 사용하는 주소입니다.

Dockerfile에 애플리케이션을 정의한 다음 SDK 안에서 ARM64 이미지를 빌드하고 푸시합니다.

docker buildx build \
  --platform linux/arm64 \
  --tag "${SIMA_CONTAINER_REGISTRY}/hello-neat:develop" \
  --push \
  .

dk container deploy를 사용하여 동일한 레지스트리에서 이미지를 다운로드하고 연결된 DevKit에서 실행합니다.

dk container deploy hello-neat:develop \
  --detach \
  --name hello-neat \
  --network host

짧은 이미지 이름만으로 충분합니다. dk는 sima-cli가 설정한 DevKit 레지스트리 주소를 사용합니다. 먼저 명시적으로 이미지를 갱신하지 않고 시작하려면 dk container run hello-neat:develop ...를 사용합니다.

레지스트리는 로컬 개발 네트워크에서 HTTP를 사용합니다. SDK용 루프백과 DevKit 방향 네트워크 경로에만 레지스트리를 공개하며, 호스트의 모든 인터페이스에 공개하지 않습니다.

macOS에서 설정은 물리 LAN 경로와 Cloudex 또는 기타 라우팅된 터널을 구분합니다. 물리 경로에서는 Colima 브리지 주소를 사용합니다. utun, WireGuard 또는 이와 유사한 터널은 Ethernet 브리지를 전달할 수 없으므로, 설정은 Colima를 공유 모드로 유지하고 대신 network.hostAddresses를 활성화합니다. 그러면 SDK 컨테이너가 Mac의 터널 경로를 따르면서 DevKit이 사용하는 Mac 터널 주소에 레지스트리를 공개할 수 있습니다. Colima는 일반적으로 터널의 서브넷 접두사도 복사하므로, 설정은 VM의 로컬 라우팅 테이블에서 넓은 서브넷 경로를 제거하고 Mac 주소를 /32 로컬 경로로 유지합니다. 그렇지 않으면 VM이 DevKit 피어를 로컬 주소로 잘못 판단할 수 있습니다. 이 복구 설정은 Colima를 다시 시작해도 유지됩니다. 활성 프로필이 이전에 물리 연결용 브리지 모드로 구성된 경우, 설정은 보호된 프로필 재생성 절차를 사용하여 검증된 별도 Docker 데이터 디스크를 보존하면서 공유 모드로 전환합니다. Kubernetes가 활성화된 프로필 등 안전하게 재생성할 수 없는 프로필은 변경하지 않습니다. 터널의 호스트 주소가 변경되면 터널에 다시 연결한 후 설정을 다시 실행하십시오.

SDK 설정은 DevKit에 Docker를 설치하거나 구성하지 않습니다. 첫 번째 dk container 명령이 필요한 Docker 설치를 처리하고 로컬 레지스트리를 사용하도록 Docker를 구성하며, 레지스트리 설정이 변경된 경우에만 Docker를 다시 시작합니다. 따라서 컨테이너 배포를 사용하지 않는 사용자에게 Docker는 완전히 선택 사항으로 유지됩니다. Docker 설치에는 명시적인 승인과 Docker의 Debian 저장소에 대한 인터넷 연결이 필요합니다. 비밀번호 없는 sudo는 사전 요구 사항이 아닙니다. sima-cli가 설정 중에 DevKit 사용자에 대해 이를 구성합니다.

이 단계를 건너뛰려면 --no-container-registry를 사용합니다. 기존 레지스트리를 중지하거나 제거하지는 않습니다. 다른 포트를 선택하려면 --container-registry-port <port>로 설정을 다시 실행합니다. 포트가 변경되어도 기존에 저장된 이미지는 유지됩니다.

Edgematic Studio

Neat SDK 이미지에서는 설정이 질문 없이 Edgematic Studio를 설치하고 포트를 공개한 뒤 시작합니다. -y와 --noninteractive에도 동일하게 적용됩니다. 요약의 Edgematic Studio 패널에 Studio URL이 표시됩니다. Studio는 호스트 포트 8088을 사용하며, 8088이 사용 중이면 다른 사용 가능한 포트를 사용합니다.

첫 채팅 전에 Studio 설정에서 코딩 에이전트에 로그인하세요. Studio는 컨테이너와 함께 다시 시작되지 않습니다. URL이 더 이상 열리지 않으면 SDK 컨테이너 셸에서 activate-edgematic-studio를 실행하세요.

Studio를 건너뛰고 포트를 공개하지 않으려면 --no-edgematic-studio를 사용합니다. 나중에 수동으로 설치하기 위해 포트만 공개하려면 --edgematic-studio-port를 사용합니다. --minimal과 --no-insight도 Studio를 건너뜁니다. Docker 포트 매핑은 나중에 변경할 수 없으므로 이 선택은 컨테이너를 만들 때 적용됩니다.

Studio 설치가 실패해도 설정은 계속되며, 나중에 SDK 컨테이너 셸에서 설치할 수 있는 명령을 출력합니다.

브라우저 VS Code 확장 선택

Neat는 확인 없이 현재 SDK 사용자에게 자동으로 설치됩니다. 새 SDK 이미지에는 확장이 포함되어 있으며 설정 시 로컬로 복사합니다. 이전 이미지는 기존 다운로드 설치 방식을 사용합니다. --minimal은 확장 설정을 건너뜁니다.

대화형 설정에서는 선택적 Codex 및 Claude 확장을 제공합니다. Space로 선택하고 Enter로 확인합니다. 처음에는 둘 다 선택되지 않습니다. 아무것도 선택하지 않으면 코딩 에이전트 설치를 건너뛰며, 선택하지 않은 기존 확장은 유지됩니다.

자동화 시에는 체크리스트 없이 코딩 에이전트를 설치합니다:

sima-cli sdk setup --noninteractive --all-extensions

--all-extensions는 확장 선택만 건너뜁니다. 다른 질문도 건너뛰려면 --noninteractive를 사용합니다. 기존 SDK 컨테이너를 재사용할 때도 확장을 설치합니다. 이 옵션이 없으면 이전 SIMA_CLI_INSTALL_CODEX_EXTENSION 설정이 설치를 요청하지 않는 한 -y와 --noninteractive는 선택적 확장을 건너뜁니다. --all-extensions는 --minimal과 함께 사용할 수 없으며 Edgematic Studio 또는 Model Compiler 선택을 변경하지 않습니다.

브라우저 VS Code 확장 버전

code-server(SDK 3.0 이상)에서 Codex는 기본적으로 사용 가능한 최신 릴리스를 설치하며 버전을 고정하지 않습니다. 버전을 명시적으로 지정하면 해당 버전으로 고정합니다. 이전 OpenVSCode 이미지는 Codex 호환성 고정 버전을 유지합니다. Claude는 계속 정확한 버전으로 고정됩니다. 정확한 버전을 선택한 경우 설정을 다시 실행하면 다른 버전을 교체하며, 일치하는 버전은 다시 다운로드하지 않고 유지하여 고정합니다. SDK 이미지는 /etc/sima-neat/vscode-extensions.json에 검증된 버전을 선언할 수 있습니다:

{
  "schema_version": 1,
  "extensions": {
    "openai.chatgpt": "26.5825.51511",
    "anthropic.claude-code": "2.1.266"
  }
}

매니페스트 자체는 설치 동의를 의미하지 않습니다. 스키마 버전 1은 두 ID 모두에 정확한 버전을 요구합니다. 매니페스트가 없는 이전 이미지는 호환성 대체 버전으로 Codex 26.5825.51511 및 Claude 2.1.266을 사용합니다. 읽을 수 없거나 잘못된 매니페스트는 오류를 보고하고 코딩 에이전트 설치를 건너뛰지만 나머지 설정은 계속합니다. Codex 또는 Claude 설치 명령이 실패하면 선택한 대상과 정상 TLS 검증을 사용하여 최대 세 번 시도합니다.

환경 변수 재정의가 우선합니다:

변수	동작
SDK_SKIP_CODING_AGENT_INSTALL	1, true, yes 또는 on으로 설정하면 프롬프트와 --all-extensions를 포함해 Codex 및 Claude 확장 설치를 건너뜁니다. Neat 설정은 계속하며 기존 에이전트는 제거하지 않습니다.
SIMA_CLI_CODEX_EXTENSION_ID	publisher.extension@exact-version으로 Codex를 재정의합니다. 값이 비어 있으면 --all-extensions를 사용하지 않는 한 비활성화합니다.
SIMA_CLI_CLAUDE_EXTENSION_ID	publisher.extension@exact-version으로 Claude를 재정의합니다. 값이 비어 있으면 --all-extensions를 사용하지 않는 한 비활성화합니다.
SIMA_CLI_INSTALL_CODEX_EXTENSION	체크리스트 없이 확장 설치를 자동 선택합니다.

code-server에서는 버전 없는 Codex ID(또는 openai.chatgpt@latest)가 최신 릴리스를 사용합니다. 다른 버전 없는 기본 제공 ID는 SDK/기본 고정 버전을 사용하고, 그 외 ID에는 명시적인 버전이 필요합니다. --minimal은 선택적 확장 설치를 건너뜁니다. 설정은 설치된 버전을 검증하고 선택한 각 확장의 metadata.pinned 플래그(최신 Codex는 false)를 기록한 뒤 브라우저 VS Code를 다시 시작합니다. 이후 열려 있는 브라우저 탭을 새로 고칩니다.

Model Compiler 설치 원본

설정은 SDK 컨테이너 아키텍처에 따라 현재 작업 디렉터리에서만 model-compiler-arm64.zip 또는 model-compiler-amd64.zip을 찾습니다. 압축을 푼 폴더, 상위 디렉터리, 워크스페이스 ZIP 및 다른 아키텍처는 검색하지 않습니다.

유효한 로컬 ZIP이 있으면 로컬, 온라인 또는 건너뛰기를 제공합니다. 유효한 ZIP이 없으면 온라인 또는 건너뛰기를 제공하며, Enter 기본값은 건너뛰기입니다.

플래그	로컬 ZIP 있음	유효한 로컬 ZIP 없음
--noninteractive	로컬 설치	건너뛰기
--noninteractive -y	로컬 설치	온라인 설치
-y	로컬 설치	온라인 설치

온라인 무인 설치에는 -y가 필요합니다. 이전 SDK 원본의 경우 호스트에서 sima-cli login으로 인증합니다. --minimal, --no-model-compiler 및 --no-model-sdk는 항상 설치를 건너뜁니다.

공식 ZIP은 루트에 install_modelsdk_wheels.sh, source.json, manifest.txt 및 패키지 페이로드를 포함해야 하며, SDK에 선택된 컴파일러 버전과 일치해야 합니다. 아카이브를 호스트 임시 저장소에 압축 해제한 뒤 Linux 컨테이너 임시 저장소로 복사하므로 두 복사본을 위한 공간을 확보합니다. 성공 또는 실패 후 임시 데이터를 삭제하며 원본 ZIP은 유지합니다. 로컬 설치 실패 시 온라인으로 전환하지 않습니다. 시스템 패키지와 Python 필수 구성 요소에는 여전히 네트워크 접근이 필요할 수 있습니다.