배포하기
마켓플레이스에 플러그인을 등록하거나, Git 저장소나 폴더로 직접 배포하기.
플러그인을 사람들에게 전하는 방법은 두 가지입니다. 어느 쪽을 쓸 수 있는지는 플러그인 종류에 따라 다릅니다.
| 마켓플레이스 | 소스가 공개된 WebAssembly 모듈. 플러그인 → 마켓플레이스에 표시되고 한 번에 설치되며 체크섬으로 검증됩니다. |
| 직접 배포 | 프로그램으로 실행되는 것까지 포함한 모든 플러그인. 이용자가 직접 고른 Git 저장소나 폴더에서 설치합니다. |
마켓플레이스#
Agentty-Marketplace가 Agentty가 읽는 목록입니다. 플러그인은 풀 리퀘스트로 추가합니다. Agentty 자체 플러그인도 같은 조건으로 그곳에 있고, 앱에 내장된 플러그인은 없습니다.
목록에 오르는 플러그인은 소스가 공개된 WebAssembly 모듈입니다. 규칙은 이것뿐이고 양쪽 모두가 중요합니다.
- WebAssembly여야 합니다. Agentty가 직접 실행하므로 프로토콜이 허용한 것만 건드립니다. 프로그램으로 실행되는 플러그인은 여러분과 똑같은 권한을 갖습니다. 그래서 Agentty는 그런 플러그인을 인터넷 목록에서 설치하지 않습니다.
- 소스가 공개돼야 합니다. 목록의 모듈은 바이너리이기 때문입니다. 누구나 무엇으로 빌드했는지 읽고 다시 빌드해 볼 수 있어야 합니다.
설치할 때 일어나는 일#
- Agentty가 HTTPS로
index.json을 읽습니다. 이때 id, 문구, 권한, 모듈을 받아 오는 호스트까지 모든 항목을 다시 검사합니다. 통과하지 못한 항목은 표시하지 않고 목록에서 뺍니다. - 플러그인 페이지에 플러그인 소개, 소스 위치, 라이선스, 모듈 크기와 체크섬이 나옵니다. 무엇을 할 수 있는지는 권한 아래에 온전한 문장으로 보여 줍니다.
- 설치를 누르면 Agentty가 모듈을 내려받아 그 체크섬과 대조합니다. 일치하기 전에는 플러그인 폴더에 아무것도 들어가지 않습니다.
등록하기#
모듈을 빌드하고 공개합니다. 보통은 플러그인 저장소의 GitHub 릴리스입니다.
bashcargo build --release --target wasm32-unknown-unknown cp target/wasm32-unknown-unknown/release/your_plugin.wasm your-plugin.wasm shasum -a 256 your-plugin.wasm wc -c your-plugin.wasm항목을 작성합니다.
plugins/_template.json을plugins/<플러그인-id>.json으로 복사하세요. id는 파일 이름과agentty-plugin.json의id와 같아야 합니다.json{ "id": "hello-world", "name": "Hello World", "version": "0.1.0", "publisher": "Your Name", "description": "One sentence about what it does.", "icon": "sparkles", "license": "MIT", "source": "https://github.com/you/agentty-hello-world", "build": { "repository": "https://github.com/you/agentty-hello-world", "rev": "3f2b1c9e4a7d05b8c6e1f0a2d4b83c7e9015d6af", "path": ".", "toolchain": "1.98.1", "artifact": "target/wasm32-unknown-unknown/release/hello_world.wasm" }, "keywords": ["example"], "apiVersion": 1, "surface": "sidebar", "mode": "push", "permissions": [], "module": { "url": "https://github.com/you/agentty-hello-world/releases/download/v0.1.0/hello-world.wasm", "sha256": "…64자리 16진수…", "size": 93292 } }검사한 뒤 풀 리퀘스트를 엽니다. CI도 같은 검사를 실행합니다. 항목, 항목이 가리키는 모듈, 소스를 새로 빌드한 결과가 모두 일치해야 통과합니다.
bashpython3 scripts/validate.py # 모든 항목의 형식·호스트·권한·빌드 블록 python3 scripts/validate.py --download # 각 모듈을 내려받아 체크섬까지 확인 python3 scripts/validate.py --source # 소스를 누구나 읽을 수 있는지까지 확인 python3 scripts/verify_build.py # 소스를 다시 빌드해 체크섬과 대조
verify_build.py에는 Docker가 필요합니다. 다이제스트로 고정한 rust 이미지 안에서 모듈을 빌드하므로 빌드한 기계에 따라 바이트가 달라지지 않습니다. 그래서 CI도 여러분과 같은 체크섬을 얻습니다.
항목의 필드#
| 필드 | |
|---|---|
id | 2~40자의 a-z 0-9 -. 파일은 plugins/<id>.json |
name, version, description | Agentty에 표시됨. name은 60자, description은 300자까지. version은 major.minor.patch |
publisher, license | 만든 사람과 라이선스 |
source | 모듈을 빌드한 공개 저장소 — 필수. github.com, gitlab.com, codeberg.org, git.sr.ht 중 하나면 되고, GitHub일 필요는 없습니다. build.repository와 같은 저장소여야 합니다 — 항목이 가리키는 코드가 실제로 배포되는 코드여야 하기 때문입니다 |
build | 필수 — 그 모듈을 다시 빌드하는 방법. repository(클론 주소), rev(40자 전체 커밋. 태그나 브랜치는 나중에 옮겨질 수 있어 안 됩니다), path(저장소 안 플러그인 디렉터리, 또는 .), toolchain(마켓플레이스가 쓰는 Rust 버전), artifact(빌드가 만드는 .wasm, path 기준 상대 경로). 어느 것도 명령이 아닙니다 — 무엇을 실행할지는 scripts/verify_build.py에 고정되어 있습니다 |
homepage, keywords, icon | 선택. 아이콘은 Agentty 아이콘 집합의 이름 |
apiVersion | 모듈이 대상으로 한 플러그인 프로토콜. 1이면 생략 |
surface | 아이콘 위치: sidebar, pane(기본), status |
mode | 패널이 열리는 방식: push(기본), overlay, window, full |
permissions | 요청하는 권한. 설치 전에 표시되고, 더 요구하는 업데이트에서 다시 표시됩니다 |
agents | 선택. 동작하는 AI 에이전트 — ["claude"], ["codex"] 또는 ["claude", "codex"]. 생략하면 Claude Code. 카드에 사용 가능한 AI로 표시됩니다 |
module.url | github.com, raw.githubusercontent.com, objects.githubusercontent.com 중 하나의 https:// 주소. 경로에 버전을 넣어 두면 릴리스를 몰래 바꿔치기할 수 없습니다 — 검사 항목이 아니라 관례입니다 |
module.sha256 | 체크섬. 일치하지 않는 다운로드는 거부되고, 일치하더라도 WebAssembly 모듈이 아닌 바이트는 거부됩니다 |
module.size | 바이트 단위의 정확한 길이. 최대 8MB. 상한이 아니라 정확한 값입니다 — 길이가 다른 다운로드는 거부되며, 이 값은 빌드할 때마다 바뀝니다 |
등록된 플러그인은 엔트리에 로고를 담지 않습니다. 아이콘 대신 이미지를 쓰고 싶다면 모듈의 agentty.logo 섹션에 넣으세요. 그러면 다른 내용과 마찬가지로 module.sha256으로 검증되고, 누가 플러그인을 설치해도 게시자 서버로는 요청이 나가지 않습니다. 로고 참고.
거부되는 경우#
build.repository를build.rev에서 다시 빌드해도 CI가 같은 바이트에 도달하지 못하는 모듈이거나, 아무도 읽을 수 없는 저장소인 경우.build.path의 매니페스트가 항목과 어긋나는 경우 — id·버전·apiVersion·권한 목록이 다른 경우.- 체크섬이 URL이 제공하는 것과 다른 경우.
- 쓰지 않는 권한을 요청하거나, 그 권한으로 무엇을 하는지 설명에 없는 경우.
- 다른 플러그인, 다른 배포자, 또는 Agentty 자체인 척하는 경우.
업데이트#
version, module.url, module.sha256, module.size를 바꾸고 풀 리퀘스트를 다시 엽니다. 설치한 모든 사람에게 업데이트가 제안됩니다.
설치된 버전보다 더 많은 권한을 요구하는 업데이트는 추가되는 권한을 보여 주고, 한 번 더 눌러야 적용됩니다. 모두 업데이트는 이런 업데이트를 몰래 적용하지 않고 건너뛴 뒤 몇 개를 남겼는지 알려 줍니다. 그러니 권한을 늘리면 다시 확인하지 않는 이용자는 놓치게 됩니다. 이용자가 확인해 볼 마음이 들도록 설명을 쓰세요.
새 버전이 최신 Agentty에만 있는 기능을 쓴다면 apiVersion도 함께 올리세요. 구버전 Agentty 이용자는 실행할 수 없는 모듈을 받지 않고 기존 버전을 유지하며, 앱을 업데이트하라는 안내를 받습니다. Agentty는 실행할 수 없는 버전을 설치된 플러그인의 업데이트로 치지 않습니다.
항목을 지우면 Agentty가 그 플러그인을 더 이상 제공하지 않습니다. 이미 설치한 사람에게는 남아 있고, 플러그인 페이지에서 직접 삭제할 수 있습니다.
목록을 작성하는 동안에는 AGENTTY_MARKETPLACE_INDEX로 Agentty가 다른 목록을 읽게 할 수 있습니다. 모듈은 저장소의 릴리스나, 목록과 같은 호스트에서 제공될 수 있습니다.
직접 배포하기#
플러그인을 쓰는 데 위 과정이 꼭 필요하지는 않습니다. 혼자 쓰거나 회사 안에서만 쓰는 플러그인은 마켓플레이스 목록을 거칠 필요가 없습니다.
Git 저장소로#
agentty-plugin.json을 저장소 루트에 두세요. 이용자는 직접 만들기 아래에 https:// 주소를 붙여넣고 Git에서 설치를 누릅니다.
your-plugin/
├── agentty-plugin.json
├── main.mjs
├── agentty-plugin.mjs 번들된 SDK
├── README.md
└── LICENSESDK와 node_modules를 포함해 실행에 필요한 모든 것을 번들하세요. Agentty는 npm install을 실행하지 않고, 진입점을 있는 그대로 시작합니다. 번들하지 않은 의존성이 있으면 이용자 컴퓨터에서 실행에 실패하고 로그에 module-not-found 오류가 남습니다.
되도록 의존성 없는 코드를 쓰세요. SDK에 의존성이 하나도 없는 것도 바로 이 때문입니다.
폴더로#
폴더에서 설치… 는 폴더를 ~/.agentty/plugins/로 복사합니다. 올바른 이름의 폴더로 풀리는 zip도 같은 방식으로 동작합니다. 폴더 이름은 매니페스트의 id와 같아야 합니다.
버전 관리#
version은 major.minor.patch입니다. 공개할 때마다 올리세요. Agentty가 이 값을 비교해 설치된 플러그인에 업데이트가 있는지 판단합니다.
매니페스트와 코드를 함께 유지하세요. 더 이상 쓰지 않는 권한은 매니페스트에서도 빼고, 이름을 바꾼 명령이 contributes에 남아 있지 않게 하세요.
다음으로#
- Rust와 WebAssembly — 모듈 빌드하기
- 매니페스트 레퍼런스 · 권한