4.4. 스쿼드 템플릿 카탈로그¶

스쿼드 템플릿 카탈로그를 사용하면 GitHub 기반 카탈로그에 게시된 미리 제작된 스쿼드 템플릿을 찾아 설치할 수 있습니다. 이는 개별 에이전트 프로필을 배포하는 것과 동일한 다중 소스 레지스트리를 사용합니다. 카탈로그는 바로 사용할 수 있는 팀 레시피(예: "오픈소스 코드 리뷰 크루" 또는 "한국어 번역 팀")를 제공하므로, 처음부터 구성할 필요 없이 완전히 구성된 스쿼드를 추가할 수 있습니다.

카탈로그 템플릿은 로컬에 설치된 후 다른 사용자 템플릿과 똑같이 동작합니다. 적용, 내보내기, 삭제가 가능합니다. 내장 템플릿은 읽기 전용으로 유지됩니다.

카탈로그 둘러보기¶

사이드바에서 카탈로그 페이지를 엽니다.
스쿼드 템플릿 탭을 선택합니다.
각 카드에는 템플릿의 아이콘, 이름, 카테고리, 설명, 태그, 작성자, 버전, 출처 소스가 표시됩니다.

레지스트리 소스를 두 개 이상 구성한 경우, 필터 칩을 사용해 그리드를 단일 소스로 좁힐 수 있습니다. 새로고침을 사용하면 로컬 캐시를 무시하고 최신 인덱스를 다시 가져옵니다.

스쿼드 템플릿과 에이전트 프로필은 하나의 공유 레지스트리 소스 목록을 통해 배포됩니다. 설정 → 레지스트리 소스에서 소스를 추가, 제거, 활성화 또는 비활성화하면 커뮤니티(에이전트) 탭과 스쿼드 템플릿 탭에 동시에 적용됩니다. 스쿼드 템플릿을 위한 별도의 소스 목록은 없습니다.

템플릿 설치하기¶

카드에서 설치를 클릭합니다. Backend.AI GO가 소스에서 템플릿 JSON을 가져와 콘텐츠를 검증하고(콘텐츠 검증 참조) 스키마 버전을 검증한 뒤 로컬 squad-templates 디렉터리에 기록합니다. 설치가 완료되면:

카드에 설치가 아닌 설치됨과 함께 검증 배지(검증됨 / 미검증)가 표시됩니다.
템플릿이 템플릿 갤러리(스쿼드 → 새 스쿼드)에 카탈로그에서 설치됨 배지와 함께 내장 및 로컬 생성 템플릿과 나란히 나타납니다.

소스가 검증을 요구하는데 템플릿에 유효한 체크섬이나 서명이 없거나, 체크섬/서명이 일치하지 않으면 설치가 차단되고 아무것도 기록되지 않습니다.

설치된 템플릿이 참조하는 모델¶

카탈로그 템플릿은 각 에이전트의 모델 설정을 담고 있습니다. 설치된 템플릿이 로컬에 없는 모델을 참조하는 경우, 해당 에이전트는 자동으로 설정 → 모델에서 지정한 기본 모델로 대체됩니다. 따라서 설치된 템플릿은 선호 모델을 다운로드하기 전에도 항상 사용할 수 있습니다. 스쿼드 템플릿 탭은 그리드 위에 이 동작에 대한 안내를 표시합니다.

템플릿 제거하기¶

카탈로그 템플릿은 설치되면 사용자 템플릿이 되므로, 다른 사용자 템플릿을 제거하는 것과 동일한 방식으로 제거합니다.

템플릿 갤러리(스쿼드 → 새 스쿼드)에서 템플릿 카드의 삭제 동작을 사용하고 확인합니다.

내장 템플릿은 삭제할 수 없습니다. 설치된 카탈로그 템플릿을 삭제하면 로컬 사본만 제거되며, 언제든지 카탈로그에서 다시 설치할 수 있습니다.

스쿼드 템플릿을 카탈로그에 게시하기¶

카탈로그를 작성하는 것은 순수한 데이터 작업입니다. 앱 릴리스나 백엔드 서비스가 관여하지 않습니다. 카탈로그는 raw.githubusercontent.com을 통해 제공되는 GitHub 저장소일 뿐입니다.

1. 템플릿 JSON 작성하기¶

직접 만든 스쿼드를 내보내거나(템플릿으로 저장 후 갤러리에서 내보내기) 템플릿 JSON 스키마를 따라 직접 작성하여 올바른 템플릿 JSON을 얻습니다. 카탈로그 저장소의 안정적인 경로에 배치합니다. 예:

your-catalog/
├── index.json
├── code-assistants/
│   └── python-expert.json        # 에이전트 프로필
└── squad-templates/
    └── code-review-crew.json     # 스쿼드 템플릿

스쿼드 템플릿의 관례적인 위치는 최상위 squad-templates/ 디렉터리이지만, 인덱스가 가리키기만 하면 어떤 상대 경로든 동작합니다.

2. `index.json`에 `kind: "squad_template"`로 나열하기¶

카탈로그의 index.json은 에이전트 프로필과 스쿼드 템플릿 모두에 대한 요약 항목을 하나의 목록에 담습니다. 각 스쿼드 템플릿 항목을 "kind": "squad_template"로 표시합니다.

{
  "version": 1,
  "updatedAt": "2026-05-28T00:00:00Z",
  "profiles": [
    {
      "path": "code-assistants/python-expert.json",
      "name": "Python Expert",
      "category": "code_assistant",
      "kind": "agent_profile"
    },
    {
      "path": "squad-templates/code-review-crew.json",
      "name": "Code Review Crew",
      "description": "Security, performance, and style reviewers as one team.",
      "category": "review",
      "author": "your-org",
      "icon": "🔐",
      "tags": ["review", "code-quality"],
      "version": "1.0.0",
      "kind": "squad_template"
    }
  ]
}

인덱스 형식은 추가적이며 하위 호환됩니다.

kind 필드가 없는 항목은 agent_profile로 기본 설정되므로, 기존 에이전트 전용 카탈로그(예: lablup/agent-catalog)는 변경 없이 계속 동작합니다.
squad_template을 이해하지 못하는 이전 앱 버전도 새 인덱스를 계속 파싱하며, 처리할 수 없는 종류는 단순히 무시합니다.

인덱스 항목은 카드 표시를 위한 요약 필드만 담습니다. 전체 에이전트 구성, 프롬프트, 도구, 모델 설정은 path에 있는 템플릿 JSON에 있으며, 사용자가 설치할 때만 가져옵니다.

3. 앱에서 소스 추가하기¶

설정 → 레지스트리 소스를 열고 저장소(소유자, 저장소, 브랜치, 레이블)를 추가하면, 앱이 저장소에 올바른 index.json이 포함되어 있는지 검증합니다. 그러면 스쿼드 템플릿이 스쿼드 템플릿 탭에 나타납니다. 소스 목록이 공유되므로, 에이전트 프로필이 있다면 동일한 소스에서 커뮤니티 탭에 나타납니다.

콘텐츠 검증 (체크섬과 서명)¶

Backend.AI GO는 설치 전에 카탈로그 리소스의 무결성(바이트가 변경되지 않음)과, 선택적으로 진위성(신뢰할 수 있는 작성자가 게시함)을 검증할 수 있습니다. 동일한 검증 경로가 에이전트 프로필과 스쿼드 템플릿을 모두 다루므로, 하나의 체계가 카탈로그 전체를 보호합니다.

검증은 부가적이며 하위 호환됩니다. 기존의 서명되지 않은 카탈로그는 계속 동작합니다. 소스는 사용자가 켤 때만 검증을 강제합니다 (소스별 검증 요구 참조).

검증된 리소스 게시하기¶

각 리소스에 대해 카탈로그 index.json 항목에 체크섬(그리고 선택적으로 서명)을 기록합니다.

체크섬(무결성). 항목이 가리키는 리소스 파일의 정확한 바이트에 대한 sha256:<hex> 다이제스트입니다. 제공되는 파일 그대로 계산합니다.

printf 'sha256:%s\n' "$(sha256sum squad-templates/code-review-crew.json | cut -d' ' -f1)"

결과를 항목의 checksum 필드에 넣습니다.

서명(진위성, 선택). 동일한 바이트에 대한 분리형 Ed25519 서명을 base64로 인코딩하여 항목의 signature 필드에 넣습니다. 일치하는 base64 공개 키를 앱에서 소스의 신뢰 앵커로 설정합니다(설정 → 레지스트리 소스 → 검증 설정 → 서명 공개 키). 서명과 신뢰 앵커가 모두 있으면 서명이 검증되며, 불일치 시 설치가 차단됩니다.

{
  "path": "squad-templates/code-review-crew.json",
  "name": "Code Review Crew",
  "kind": "squad_template",
  "checksum": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "signature": "QmFzZTY0LWVuY29kZWQgRWQyNTUxOSBzaWduYXR1cmU="
}

리소스는 체크섬만, 서명만, 둘 다, 또는 둘 다 없이 가질 수 있습니다.

소스별 검증 요구¶

각 소스에는 설정 → 레지스트리 소스 → 검증 설정 아래에 콘텐츠 검증 필수 토글이 있습니다.

꺼짐(기존 소스 및 공개 GitHub 소스의 기본값). 서명되지 않은 리소스는 설치되지만 카탈로그에서 미검증으로 표시됩니다(절대 녹색 "검증됨" 체크가 아님). 체크섬/서명을 가진 리소스는 여전히 검증되며, 이 토글과 관계없이 불일치는 항상 설치를 차단합니다.
켜짐. 이 소스에서의 모든 설치는 검증을 통과해야 합니다. 체크섬이나 서명이 없는 리소스는 명확한 현지화된 오류와 함께 차단되며, 체크섬/서명 불일치도 마찬가지입니다.

이는 기본적으로 안전합니다. 체크섬이나 서명이 일치하지 않는 리소스는 절대 설치되지 않으며, "콘텐츠 검증 필수"를 켜는 것은 소스별 관리자의 명시적 작업입니다.

배지의 의미¶

설치 후 카탈로그 카드에 검증 배지가 표시됩니다.

검증됨 — 콘텐츠의 체크섬(그리고 신뢰 앵커가 설정된 경우 서명)이 일치했습니다.
미검증 — 리소스가 전송 신뢰만으로 설치되었습니다(체크섬/서명 없음, 소스가 검증을 요구하지 않음).
미검증 — 신뢰할 수 있는 소스 — 소스가 전송 신뢰 소스(인증된 전송을 통해 완전히 제어하는 자체 호스팅 카탈로그 — 자체 호스팅 카탈로그 인증 참조)이므로 검증이 의도적으로 우회되었습니다. 이 우회는 명시적이고 기본적으로 안전하며 감사 로그에 기록됩니다. 녹색 "검증됨" 체크로 표시되지 않습니다.

템플릿이 "단순한 구성"이어도 중요한 이유¶

스쿼드 템플릿은 순수한 구성(시스템 프롬프트, 도구 플래그, 모델 설정)이므로 가져오기 시 임의의 코드를 실행할 수 없으며, 설치는 항상 로컬 가져오기와 동일한 콘텐츠 검증 및 제한(크기 상한, 에이전트 수, 필드 길이 검사)을 다시 수행하고 내장이 아닌 사용자 템플릿으로 강제합니다. 하지만 구성이 전적으로 무해한 것은 아닙니다. 변조된 시스템 프롬프트나 도구 권한 집합은 에이전트를 안전하지 않은 동작으로 유도할 수 있고, 타이포스쿼팅되거나 침해된 소스가 정상적인 TLS를 통해 악성 콘텐츠를 제공할 수 있습니다. 무결성(그리고 가능하면 진위성)을 검증하면 그 간극이 메워집니다.

자체 호스팅 (Go Enterprise) 카탈로그 인증¶

공개 lablup/agent-catalog는 GitHub TLS를 통해 익명으로 가져옵니다. 온프레미스 / 자체 호스팅 "Go Enterprise" 카탈로그는 보통 접근 경계(베어러 토큰, API 키, mTLS 또는 사설 CA) 뒤에 있습니다. Backend.AI GO는 이러한 서버를 대상으로 하여 자격 증명을 제시할 수 있습니다. 에이전트 프로필과 스쿼드 템플릿이 하나의 소스 목록을 공유하므로 이 기능은 양쪽에 동일하게 적용됩니다.

자체 호스팅 소스 추가하기¶

설정 → 레지스트리 소스 → 소스 추가를 열고 자체 호스팅 카탈로그 서버를 켭니다. owner/repo/branch 대신 서버의 전체 기본 URL(예: https://catalog.corp.internal/)을 입력합니다. 소스를 추가한 후 전송 인증 패널을 펼쳐 나머지를 구성합니다.

소스별 인증 방법¶

소스에서 인증 방법을 선택합니다.

없음(익명) — 기본값이며 자격 증명을 보내지 않습니다. 개방형 인트라넷 미러에 사용하세요.
베어러 토큰 — Authorization: Bearer <token>을 보냅니다.
API 키 헤더 — 구성 가능한 헤더(예: X-API-Key: <value>)를 보냅니다.
기본 인증 — Authorization: Basic …을 보냅니다(사용자 이름은 여기, 비밀번호는 키체인에 저장).
클라이언트 인증서(mTLS) — PKI 기반 기업을 위해 PEM 클라이언트 ID(인증서 + 개인 키)를 제시합니다.

사용자 지정 CA와 프록시¶

기업 사설 CA 뒤에 있는 서버의 경우, 소스의 사용자 지정 CA 인증서 경로(.pem/.crt 번들)를 설정하거나 전역 설정 → 일반 → 사용자 지정 CA 인증서 경로를 사용합니다. 선택적 프록시 URL은 송신 프록시를 통해 가져오기를 라우팅합니다. "TLS 검증 건너뛰기" 옵션은 의도적으로 없습니다. 항상 올바른 CA 번들을 사용하세요.

자격 증명 저장 위치¶

소스별 비밀(베어러 토큰, API 키 값, 기본 인증 비밀번호, mTLS 클라이언트 ID)은 운영체제 키체인에만 저장됩니다(헤드리스 모드에서는 암호화된 파일로 대체). 이들은 sources.json에 절대 기록되지 않으며, 로그에 남거나 UI로 다시 전송되지 않습니다. 설정 패널은 자격 증명이 현재 설정되어 있는지 여부만 표시하며, 교체하거나 지울 수 있게 합니다.

전송 신뢰 소스를 위한 서명 검증 우회¶

카탈로그 서버와 전송(사설 네트워크의 mTLS 또는 인증된 리버스 프록시)을 모두 완전히 제어하는 기업은 리소스별 서명이 중복이라고 판단할 수 있습니다. 이 경우 콘텐츠 검증 필수를 꺼서 소스를 운영할 수 있습니다("전송 신뢰, 미서명"). 이 우회는 다음과 같습니다.

기본적으로 안전 — 새로 추가된 자체 호스팅 소스는 검증이 필수로 생성됩니다. 끄는 것은 의식적인 관리자 작업입니다.
표시됨 — 우회된 설치는 카탈로그에 "미검증 — 신뢰할 수 있는 소스"로 표시되며, 녹색 "검증됨" 체크는 절대 아닙니다.
감사 로그 기록 — 우회가 기록됩니다.

권장 방식은 우회하지 않는 것입니다. 소스의 서명 공개 키(신뢰 앵커)를 설정하고 검증을 켜 두면 전송 인증과 콘텐츠 진위성을 모두 얻을 수 있습니다.

카탈로그 엔드포인트 자체 보안¶

자체 호스팅 카탈로그는 index.json과 리소스 JSON을 제공하는 정적 호스트일 뿐입니다. Backend.AI GO 자체 관리 API로 이를 제공하는 경우, BGO의 인바운드 인증은 기본적으로 개방되어 있으며 0.0.0.0 바인딩은 경고만 한다는 점에 유의하세요. 카탈로그 엔드포인트는 자체 인바운드 인증(관리 API 토큰, 리버스 프록시 인증 또는 네트워크 ACL)을 반드시 적용해야 합니다. "내부용"이라는 이유만으로 누구나 읽을 수 있게 두어서는 안 됩니다.

작동 방식¶

둘러보기는 에이전트 프로필에 이미 사용되는 공유 집계 레지스트리 인덱스, HTTP 가져오기 + 캐시 계층, 다중 소스 저장소를 재사용합니다. 스쿼드 전용 부분은 인덱스 항목의 kind 판별자, 스쿼드 템플릿 저장 계층을 통해 템플릿을 설치하는 설치 핸들러, 그리고 스쿼드 템플릿 탭뿐입니다. 데스크톱(Tauri)과 헤드리스(REST) 빌드 모두 전체 둘러보기 및 설치 흐름을 지원합니다. REST 엔드포인트는 POST /api/v1/squad-registry/install입니다.