콘텐츠로 이동
PouchiPouchi개발 문서
요금문서EN

배포와 실행

각 구성 요소가 어떤 형태로 나가고, 누가 어디서 실행하는지 정리합니다. 주소는 예시(example.com)입니다. 체인은 Maroo Testnet(chainId 450815)입니다.

배포 구성

섹션 제목: “배포 구성”
구성 만드는 쪽 나가는 형태 실행하는 곳
@shard-lab/nc-waas-react, @shard-lab/nc-waas-sdk Pouchi GitHub Packages (지금), npm (공개 후) 고객 앱 (브라우저, 서버)
@shard-lab/agentpay-service-kit, @shard-lab/create-agentpay-service Pouchi GitHub Packages (지금), npm (공개 후) 각 서비스의 서버
지갑 MCP (apps/remote-mcp) Pouchi Docker 이미지 (APP=remote-mcp) Pouchi가 호스팅. 사용자는 URL 하나만 추가
게이트웨이 (apps/gateway) Pouchi 앱 운영자 Docker 이미지 (APP=gateway) 앱 서버 (지갑 MCP와 같은 네트워크)
서비스 MCP (쇼핑, 금융, 새 서비스) 각 서비스 서비스가 만든 Docker 이미지 각 서비스가 호스팅
개발 문서 (apps/docs) Pouchi 정적 파일 (dist/) 정적 호스팅 (CDN)

1. SDK 패키지

섹션 제목: “1. SDK 패키지”

지금은 shard-lab 조직의 GitHub Packages에만 올립니다. 설치하는 쪽은 read:packages 토큰이 필요합니다.

# .npmrc (토큰은 환경 변수로만)
@shard-lab:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NC_WAAS_PACKAGES_TOKEN}
저장소 준비 명령 결과
nc-waas npm run packages:github:stage -- --pack artifacts/github-packages/ (react, sdk, protocol, client-vault)
agent-pay npm run packages:github:stage -- --pack artifacts/github-packages/ (service-kit, create-agentpay-service)
  • 두 스크립트 모두 게시하지 않습니다. 이름, 버전(0.1.0), file: 의존성, 저장소 밖 import, 비밀값 패턴을 검사하고 npm pack --dry-run까지 합니다.
  • 게시는 별도 승인 후 각 스테이징 디렉터리에서 npm publish로 합니다.
  • npm 공개로 옮길 때: publishConfig.registry를 빼고, .npmrc 안내를 문서에서 지우면 됩니다. 패키지 이름은 그대로입니다.

2. 지갑 MCP 호스팅

섹션 제목: “2. 지갑 MCP 호스팅”

일반 이용자는 에이전트 연결 문서의 호스팅된 URL을 추가합니다. 아래 Docker 명령은 저장소를 직접 호스팅할 때 씁니다. 공개 연결은 OAuth 자동 클라이언트 등록과 authorization code + PKCE를 사용합니다. 지갑 MCP에는 키가 없습니다. 결제 승인은 Pouchi 승인 화면에서만 합니다.

터미널 창
docker build --build-arg APP=remote-mcp -t agentpay-wallet-mcp .
docker run -d -p 9410:9410 -v wallet-mcp-state:/app/.local --env-file wallet-mcp.env agentpay-wallet-mcp
환경 변수 예 설명
REMOTE_MCP_PUBLIC_URL https://wallet-mcp.example.com OAuth issuer, 리소스 주소의 기준. https 필수
AGENT_PAY_WAAS_URL https://api.example.com Pouchi API
AGENT_PAY_GATEWAY_URL http://gateway:9401 게이트웨이 (내부망)
AGENT_PAY_TENANT_ID tenant_agent_pay 앱 운영자
AGENT_PAY_CHAIN_ID, AGENT_PAY_RPC_URL 450815, https://rpc-testnet.maroo.io 체인
REGISTRY_PATH /app/registry/shops.tkrw.json 등록된 서비스 목록
REMOTE_MCP_ALLOWED_ORIGINS (비움) 브라우저에서 직접 부를 때만
  • 상태(사용자 연결, 토큰 해시)는 /app/.local에 저장됩니다. 볼륨을 붙이고, 여러 대로 늘리기 전에 DB로 옮겨야 합니다.
  • 앞단 프록시는 SSE를 버퍼링하지 않아야 합니다 (X-Accel-Buffering: no 응답을 그대로 전달, 읽기 타임아웃 300초 이상).

3. 앱 게이트웨이

섹션 제목: “3. 앱 게이트웨이”
터미널 창
docker build --build-arg APP=gateway -t agentpay-gateway .
docker run -d -p 9401:9401 -v gateway-state:/app/.local --env-file gateway.env agentpay-gateway
환경 변수 설명
WAAS_URL, WAAS_USER_WEB_URL Pouchi API와 사용자 승인 화면
APPROVAL_SURFACE=waas-web 모든 승인을 Pouchi 화면에서
TENANT_ID, CHAIN_ID, CHAIN_RPC_URL, REGISTRY_PATH 앱 ID, 체인, 레지스트리
GATEWAY_PUBLIC_URL, REMOTE_MCP_URL 외부 주소, 지갑 MCP 주소
TENANT_SIGNER_PRIVATE_KEY 앱 서버의 실행 서명 키. 앱 운영자가 대리인인 위임의 실행에 서명. 시크릿 매니저에서 주입. 이미지와 저장소에 넣지 않음
MANDATE_CREDENTIAL_KEY_FILE 서비스 자격 증명 마스터 키 파일. 바꾸면 모든 서비스 자격 증명이 무효
OWNER_CALL_CREDENTIAL_FILE 단건 구매를 거래 1건으로 만드는 앱 서버의 Client Credential (선택)

4. 서비스 MCP (각 서비스)

섹션 제목: “4. 서비스 MCP (각 서비스)”

서비스가 직접 만들고 호스팅합니다. 템플릿으로 시작합니다.

터미널 창
npm init @shard-lab/agentpay-service acme-news -- --name "Acme 뉴스"
cd acme-news && npm install && npm test
docker build --secret id=npmrc,src=$HOME/.npmrc \
  --secret id=packages_token,env=NC_WAAS_PACKAGES_TOKEN -t acme-news-mcp .
docker run -d -p 8080:8080 --env-file .env acme-news-mcp
환경 변수 설명
SERVICE_ID, SERVICE_NAME 앱 운영자에게 등록한 id와 표시 이름
PUBLIC_URL 등록한 origin과 정확히 같아야 함 (https://acme.example.com)
AGENTPAY_GATEWAY_URL 앱 게이트웨이 (나중 청구가 있을 때)
PAYMENT_TOKEN_ADDRESS, MERCHANT_CONTRACT_ADDRESS 결제 토큰과 서비스 컨트랙트 (둘 다 앱 운영자 등록)

앱 등록 항목

섹션 제목: “앱 등록 항목”
  1. 서비스: id, name, origin, 나중 청구 허용 여부(merchantCharges)
  2. 컨트랙트: 서비스가 권한을 요청할 주소. 코드 해시를 고정하고, Pouchi 앱 관리 콘솔에도 등록해 승인 화면에 이름이 보이게 합니다.
  3. 배포 환경 origin: 게이트웨이와 지갑 MCP에 AGENTPAY_SERVICE_ORIGINS="acme-news=https://acme.example.com"

등록 전에는 지갑이 그 origin의 intent를 받지 않습니다. 서비스는 등록된 자기 컨트랙트에만 권한을 요청할 수 있습니다.

서비스 운영 규칙

섹션 제목: “서비스 운영 규칙”
  • /intents/<id>와 /agentpay/mandates를 같은 origin에서 https로 제공합니다 (키트가 처리).
  • 받은 권한 자격 증명은 암호화해 저장합니다. 그 권한 하나에만 쓸 수 있고, 해지하면 release로 반납합니다.
  • 서비스 MCP는 로그인이 없어도 됩니다. 견적과 intent만 만들기 때문입니다.

5. 에이전트 앱 설정

섹션 제목: “5. 에이전트 앱 설정”

AI 에이전트 연결의 공개 주소에는 지갑과 shop_* 도구가 함께 있어 URL 하나만 추가합니다. 쇼핑 MCP를 따로 넣을 필요는 없습니다. 아래 설정은 지갑과 자체 서비스를 직접 호스팅하는 개발자용입니다. example.com 주소는 모두 등록된 배포 주소로 바꿉니다. 자체 서비스 MCP는 견적과 intent만 만들므로 지갑 로그인이 필요하지 않습니다.

Hermes (~/.hermes/config.yaml)

mcp_servers:
  agentpay:
    url: "https://wallet-mcp.example.com/mcp"
    auth: oauth
    oauth: { flow: device }   # 또는 browser
    timeout: 300              # 사용자가 승인하는 동안 기다림
  acme:
    url: "https://acme.example.com/mcp"
    timeout: 120

Claude Code

터미널 창
claude mcp add --transport http agentpay https://wallet-mcp.example.com/mcp
claude mcp add --transport http acme https://acme.example.com/mcp

Claude 데스크톱, claude.ai: 설정의 커넥터에서 사용자 지정 커넥터를 추가하고 URL을 넣습니다. 처음 쓸 때 OAuth 로그인 창이 열립니다.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "agentpay": { "url": "https://wallet-mcp.example.com/mcp" },
    "acme": { "url": "https://acme.example.com/mcp" }
  }
}

결제 전용 에이전트에는 셸, 파일, 웹 도구를 같이 켜지 않는 것을 권장합니다 (agent-pay tools/hermes/config.example.yaml).

6. 개발 문서

섹션 제목: “6. 개발 문서”
터미널 창
cd apps/docs && npm ci && npm run build   # dist/ 정적 파일

문서 빌드는 dist/에 정적 파일을 만듭니다. 제품 랜딩은 apps/brand에서 따로 빌드합니다. 외부 스크립트와 추적 도구는 쓰지 않습니다.

배포 준비 상태

섹션 제목: “배포 준비 상태”
  • 지갑 MCP와 게이트웨이 상태를 파일에서 DB로 (여러 대 운영)
  • TENANT_SIGNER_PRIVATE_KEY를 KMS 서명으로
  • 서비스 등록을 레지스트리 파일에서 앱 관리 콘솔 API로
  • agent-pay 저장소의 원격(GitHub) 생성, 패키지 게시 승인

Pouchi 개발 문서Pouchi Homellms.txtShard Lab