프로덕션 Docker 아키텍처: 엔터프라이즈 AI 지갑을 위한 WAIaaS 데몬 + Push-Relay 실행

당신의 AI 에이전트의 개인 키(private keys)를 제3자에게 신뢰하고 맡기시겠습니까? 만약 실제 자금을 이동시키는 자율 에이전트(autonomous agents)를 구축하고 있다면, 이 질문에는 진지한 답변이 필요하며, 많은 개발자들에게 그 답변은 '아니오'입니다. 지갑 인프라를 셀프 호스팅(Self-hosting)한다는 것은 당신의 키가 당신의 서버에 존재하고, 당신의 정책이 당신의 컨테이너(container)에서 실행되며, 어떤 외부 서비스도 당신의 에이전트 트랜잭션을 속도 제한(rate-limit)하거나, 중단시키거나, 엿볼 수 없음을 의미합니다.

AI 지갑 인프라를 셀프 호스팅해야 하는 이유

AI 지갑 분야에서 셀프 호스팅 인프라를 지지하는 이유는 단순히 철학적인 것이 아니라 실용적인 이유 때문입니다. 당신의 에이전트가 DeFi 거래를 실행하거나, x402를 통해 API 호출 비용을 지불하거나, 체인 간에 자금을 이동할 때, 모든 트랜잭션은 에이전트와 블록체인 사이에 위치한 인프라를 통과합니다. 만약 그 인프라가 호스팅 서비스라면, 당신은 스스로 통제할 수 없는 수탁(custody) 및 가용성(availability) 의존성을 도입하게 된 것입니다.

당신의 서버에서 WAIaaS를 실행하면 그 방정식이 뒤집힙니다. 당신이 마스터 비밀번호, 서명 키(signing keys), 정책 엔진(policy engine), 그리고 알림 채널을 직접 제어합니다. 제3자에 의해 부과되는 API 속도 제한(rate limits)도 없고, 에이전트의 작업 도중에 연결을 끊을 수 있는 서비스 약관(Terms of Service)도 없으며, 당신의 지갑 활동을 들여다볼 수 있는 벤더(vendor)도 없습니다. 이는 암호화폐 세계에서 자신만의 이메일 서버를 운영하는 것과 유사하지만, 도구들이 실제로 실용적으로 사용할 수 있을 만큼 성숙해졌다는 점이 다릅니다.

WAIaaS는 AI 에이전트를 위해 구축된 오픈 소스(open-source) 셀프 호스팅 Wallet-as-a-Service입니다. 15개의 패키지로 구성된 모노레포(monorepo)는 프로덕션 지갑 인프라를 실행하는 데 필요한 모든 것을 제공합니다: 메인 데몬(daemon), 모바일 알림을 위한 Push-Relay 서비스, CLI, MCP 통합, 그리고 정책 엔진입니다. 프로덕션 Docker 배포가 어떻게 구성되는지 살펴보겠습니다.

2-서비스 아키텍처

배포하기 전에 이해해야 할 중요한 세부 사항이 있습니다: WAIaaS는 하나의 이미지가 아니라 두 개의 Docker 이미지를 제공합니다.

• waiaas 데몬 (daemon) — 핵심 지갑 서비스입니다. 이 서비스는 REST API (39개 라우트 모듈), 7단계 트랜잭션 파이프라인 (transaction pipeline), 정책 엔진 (policy engine), 세션 인증 (session auth) 및 DeFi 통합을 처리합니다.
• push-relay — 트랜잭션 승인을 위한 모바일 푸시 알림 (mobile push notifications)을 처리하는 보조 서비스입니다. 에이전트가 APPROVAL 티어에 해당하는 트랜잭션을 제출하면, push-relay가 귀하의 휴대폰으로 알림을 보냅니다.

두 이미지 모두 동일한 저장소 (repository)에 존재합니다. 데몬은 필수 서비스이며, push-relay는 터미널 앞에 앉아 있을 필요 없이 모바일 알림을 통해 인간 참여형 승인 (human-in-the-loop approval)을 원할 때 추가하는 서비스입니다.

이러한 분리는 의도적인 설계입니다. push-relay는 개인 키 (private keys)에 접근할 수 없으며, 오직 알림 이벤트 (notification events)를 수신하여 전달할 뿐입니다. push-relay 없이 데몬만 실행할 수도 있고, 보안 모델에 따라 push-relay를 완전히 다른 호스트에서 실행할 수도 있습니다.

배포 전 보안 모델 이해하기

WAIaaS는 3계층 보안 아키텍처 (3-layer security architecture)를 구현합니다:

1. 세션 인증 (Session auth) → 정책 평가 (policy evaluation) — 모든 에이전트 트랜잭션은 실행 전 정책 엔진 (policy engine)을 통과합니다.
2. 시간 지연 (Time delay) + 승인 (approval) — DELAY 및 APPROVAL 티어는 조건이 충족될 때까지 트랜잭션을 보류합니다.
3. 모니터링 (Monitoring) + 킬 스위치 (kill switch) — 유입되는 트랜잭션 모니터링 및 소유자 제어 복구 기능을 제공합니다.

세 가지 인증 방식이 누가 무엇을 할 수 있는지를 결정합니다:

• masterAuth (Argon2id) — 시스템 관리자 작업: 지갑 생성, 세션 관리, 정책 설정
• sessionAuth (JWT HS256) — AI 에이전트가 일상적인 작업에 사용하는 방식: 토큰 전송, 잔액 조회, DeFi 액션 실행
• ownerAuth (SIWS/SIWE) — 자금 소유자: 보류된 트랜잭션 승인, 킬 스위치 사용

정책 엔진은 기본 거부 (default-deny) 모델을 강제합니다. ALLOWED_TOKENS 또는 CONTRACT_WHITELIST를 명시적으로 구성하기 전까지 모든 트랜잭션은 차단됩니다. 이는 프로덕션 환경을 위한 올바른 기본 설정입니다. 즉, 에이전트가 할 수 없는 것을 제외하는 방식이 아니라, 에이전트가 할 수 있는 것을 선택적으로 허용하는 방식입니다.

Docker Compose를 이용한 배포

데몬을 실행하는 가장 빠른 방법은 docker compose up입니다:

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d

첫 실행을 위한 과정은 정말 이것이 전부입니다. 이미지는 ghcr.io/minhoyoo-iotrust/waiaas:latest이며, 기본 포트 바인딩(port binding)은 127.0.0.1:3100:3100으로, 설계상 로컬호스트(localhost)에서만 접근 가능합니다. 여러분의 데몬은 기본 설정 상태에서 인터넷에 노출되지 않습니다.

설정을 스크립트로 작성하거나 헤드리스(headless)로 실행하려는 경우처럼, 더 제어된 첫 시작을 원한다면 자동 프로비저닝(auto-provision) 플래그를 사용하세요:

docker run -d \
  --name waiaas \
  -p 127.0.0.1:3100:3100 \
...

WAIAAS_AUTO_PROVISION=true는 엔트리포인트(entrypoint)에 첫 부팅 시 무작위 마스터 비밀번호를 생성하고 이를 /data/recovery.key에 기록하도록 지시합니다. 이는 첫 실행 전에 수동으로 비밀번호를 설정하고 싶지 않은 자동화된 배포(automated deployments) 환경에서 유용합니다. 데몬이 실행된 후에는 waiaas set-master를 통해 나중에 보안을 강화할 수 있습니다.

프로젝트에 포함된 전체 Compose 설정은 다음과 같습니다:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
...

이 설정에서 주목할 만한 몇 가지 사항은 다음과 같습니다:

• 네임드 볼륨 (Named volume) (waiaas-data) — 지갑 데이터가 컨테이너 재시작 및 업데이트 후에도 유지됩니다. -v 옵션 없이 docker compose down을 실행하면 데이터는 그대로 유지됩니다.
• 헬스체크 (Healthcheck) — 헬스 엔드포인트(health endpoint)가 응답을 중단하면 Docker가 컨테이너를 재시작합니다. 무인(unattended) 프로덕션 실행에 적합합니다.
• restart: unless-stopped — 호스트가 재부팅된 후에도 데몬이 다시 실행됩니다.
• 127.0.0.1:3100 — 오직 로컬호스트만 접근할 수 있습니다. 외부 접근이 필요한 경우, 앞에 리버스 프록시(reverse proxy, nginx, Caddy 등)를 두고 그곳에서 TLS를 처리하십시오. 3100 포트를 인터넷에 직접 노출하지 마십시오.

프로덕션 비밀 관리 (Production Secrets Management)

docker-compose.secrets.yml 오버레이(overlay)는 로그에 남을 수 있는 환경 변수(environment variables)나 .env 파일에 자격 증명(credentials)을 넣지 않고 프로덕션에서 이를 처리하는 방법입니다.

# 비밀 파일 생성
mkdir -p secrets
echo "your-secure-password" > secrets/master_password.txt
...

Docker Secrets 통합은 엔트리포인트(entrypoint)에서 직접 지원됩니다. 비밀 파일은 런타임(runtime) 시 컨테이너 내부에 마운트(mount)되어 엔트리포인트 스크립트에 의해 읽히며, docker inspect 출력 결과나 프로세스 환경 변수 목록에는 절대 나타나지 않습니다.

운영 보안(operational security)을 중시하는 셀프 호스팅(self-hoster) 사용자에게 이것이 올바른 실행 방식입니다. 마스터 비밀번호는 쉘 히스토리(shell history)나 docker-compose.yml 옆에 놓인 .env 파일이 아니라, 600 권한을 가진 파일 내에 존재하게 됩니다.

주요 환경 변수 (Key Environment Variables)

데몬(daemon)은 주로 환경 변수(environment variables)를 통해 구성됩니다. 프로덕션 배포 시 중요한 변수들은 다음과 같습니다:

WAIAAS_AUTO_PROVISION=true              # 첫 실행 시 마스터 비밀번호 자동 생성
WAIAAS_DAEMON_PORT=3100                 # 리스닝 포트 (Listening port)
WAIAAS_DAEMON_HOSTNAME=0.0.0.0         # 바인드 주소 (Bind address)
...

프로덕션에서는 RPC 엔드포인트(endpoint) 변수가 중요합니다. 데몬은 18개 네트워크에 걸친 2가지 체인 유형에 대해 RPC 액세스가 필요합니다. 만약 직접 호스팅하는 Solana 또는 Ethereum 노드를 실행 중이라면, 이곳에 데몬을 연결하여 키(key)뿐만 아니라 인프라 전체를 완전히 주권적(sovereign)으로 유지할 수 있습니다.

지갑 및 정책 설정 (Setting Up Wallets and Policies)

데몬이 실행되면 CLI가 초기 설정을 처리합니다. 전역(globally)으로 설치하세요:

npm install -g @waiaas/cli

CLI에는 20개의 명령어가 포함되어 있습니다. 초기 설정을 위한 관련 흐름은 다음과 같습니다:

waiaas init                        # 데이터 디렉토리 + config.toml 생성
waiaas start                       # 데몬 시작
waiaas quickset --mode mainnet     # 한 단계로 지갑 + MCP 세션 생성

quickset은 빠른 경로(fast path)입니다. 구성된 체인들에 걸쳐 지갑을 생성하고, AI 에이전트가 사용할 토큰인 MCP 세션을 생성합니다.

수동 제어를 원한다면, API를 통해 직접 지갑을 생성할 수 있습니다:

curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
...

그 다음, 에이전트를 위한 세션 토큰 (session token)을 생성합니다:

curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
...

해당 세션 토큰은 에이전트가 사용하는 토큰입니다. 이 토큰은 지갑 생성이나 정책 관리 (policy management) 권한은 없으며, 오직 정책을 통해 허용된 작업에만 접근할 수 있습니다.

프로덕션을 위한 정책 엔진 (Policy Engine) 설정

기본 거부 (default-deny) 모델은 에이전트가 유용한 작업을 수행하기 전에 반드시 정책을 설정해야 함을 의미합니다. 트레이딩 지갑을 위한 합리적인 시작점은 다음과 같이 4단계로 구성된 지출 한도 (spending limit) 설정입니다:

curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
...

이를 통해 다음과 같은 완전한 4단계 보안 모델을 작동시킬 수 있습니다:

• $100 이하: 즉시 실행, 알림 없음
• $100–$500: 즉시 실행, 알림 전송
• $500–$2,000: 15분 동안 대기열 (queued)에 머문 후 실행 (대기 시간 동안 취소 가능)
• $2,000 초과: WalletConnect, Telegram 또는 푸시 알림을 통해 명시적으로 승인할 때까지 보류

21가지 정책 유형은 토큰 화이트리스트 (token whitelists) 및 컨트랙트 화이트리스트 (contract whitelists)부터, 무기한 선물 포지션을 위한 PERP_MAX_LEVERAGE 및 대출 프로토콜을 위한 LENDING_LTV_LIMIT와 같은 DeFi 특화 규칙까지 모든 것을 다룹니다. 프로덕션 환경에서는 최소한 ALLOWED_TOKENS와 CONTRACT_WHITELIST를 설정해야 합니다. 이 설정이 없으면 기본 거부 (default-deny) 모델에 의해 토큰 전송과 컨트랙트 호출이 완전히 차단됩니다.

MCP를 통한 에이전트 연결

데몬 (daemon)이 실행되고 지갑 설정이 완료되면, Claude 또는 다른 MCP 호환 AI를 연결하는 것은 단 한 번의 명령으로 가능합니다:

waiaas mcp setup --all    # Claude Desktop에 모든 지갑을 자동 등록

또는 claude_desktop_config.json에서 수동으로 설정할 수 있습니다:

{
  "mcpServers": {
    "waiaas": {
...

이 MCP 서버는 지갑 운영, 15개의 통합 프로토콜에 걸친 트랜잭션 및 DeFi 액션, NFT 운영, 그리고 x402 HTTP 결제를 아우르는 45개의 도구 (tools)를 노출합니다. 사용자의 에이전트(agent)는 셀프 호스팅된 지갑에 대해 세션 범위 내에서 정책이 적용된 인터페이스를 갖게 됩니다. 즉, 제3자 릴레이(third-party relay)나 설정된 블록체인 RPC를 제외한 외부 API 호출 없이 작동합니다.

유용한 Docker 작업 (Docker Operations)

docker compose up -d          # 데몬 (daemon) 시작
docker compose logs -f        # 로그 추적
docker compose down           # 중지 (데이터는 이름이 지정된 볼륨(named volume)에 보존됨)
...

이름이 지정된 볼륨 (named volume) 방식을 사용하므로 업데이트가 안전합니다. 새 이미지를 풀(pull)한 뒤, -v 옵션 없이 스택을 내렸다가(down) 다시 올리면(up) 지갑 데이터는 그대로 유지됩니다. 데몬의 헬스체크 (healthcheck) 기능이 데몬이 준비되었을 때 Docker에 알려줍니다.

디버깅을 위해, 데몬이 실행되는 동안 OpenAPI 명세 (spec) 및 대화형 문서 (interactive docs)를 사용할 수 있습니다:

# OpenAPI 3.0 명세 다운로드
curl http://127.0.0.1:3100/doc -o openapi.json

...

/reference에서 제공되는 Scalar 기반의 대화형 레퍼런스 (interactive reference)를 통해, 가공되지 않은 JSON을 읽지 않고도 39개의 API 경로 (routes)를 쉽게 탐색할 수 있습니다.

빠른 시작 요약 (Quick Start Summary)

가장 짧은 경로로 아무것도 없는 상태에서 정책으로 보호되는 실행 중인 AI 지갑을 구축하고 싶다면:

1. 클론 및 시작: git clone https://github.com/minhoyoo-iotrust/WAIaaS.git && cd WAIaaS && docker compose up -d
2. CLI 설치: npm install -g @waiaas/cli
3. 지갑 및 세션 생성: waiaas quickset --mode mainnet
4. Claude에 연결: waiaas mcp setup --all
5. 지출 정책 설정: 에이전트가 메인넷 (mainnet)에서 작동하도록 허용하기 전에 REST API 또는 /admin의 관리자 UI (Admin UI)를 통해 지출 정책을 설정하세요.

전체 스택은 사용자의 하드웨어에서 실행됩니다. 푸시-릴레이 (push-relay)가 모바일 승인을 처리하며, 정책 엔진 (policy engine)이 사용자의 규칙을 강제합니다. 키 (keys)는 절대 서버를 떠나지 않습니다.

다음 단계 (What's Next)

WAIaaS 리포지토리(repository)에는 고급 정책 설정(policy configurations), 15개의 통합 DeFi 프로토콜, 그리고 프로그래밍 방식으로 에이전트(agent)를 구축하기 위한 전체 SDK에 대한 상세 문서가 포함되어 있습니다. 만약 단일 에이전트 설정을 넘어선 무언가 — 즉, 다중 에이전트(multiple agents), 다중 지갑(multiple wallets), 에이전트별 서로 다른 정책 프로필(policy profiles) — 를 구축하고 있다면, 멀티 월렛 MCP(multi-wallet MCP) 설정과 TypeScript/Python SDK가 자연스러운 다음 단계가 될 것입니다.

코드는 오픈 소스이며, 배포는 여러분의 몫이고, 키(keys)는 원래 있어야 할 곳에 머뭅니다.

→ GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
→ Official site: https://waiaas.ai