🔱 Aquaman

🔱 AI 에이전트를 위한 유일한 독립형 자격 증명 프록시: 자체 보관소(bring-your-own-vault) 격리 및 최소 권한 요청 정책. 키는 이미 보관 중인 곳에 그대로 두며, 에이전트의 메모리에는 절대 남지 않습니다. 1Password, keychain, keepassxc 및 기타 여러 도구와 호환됩니다.

Claude Code, Codex, OpenClaw, Hermes 또는 Docker Sandboxes를 설정했는데, 이제 소중한 API 키가 평문으로 들어 있는 .env 파일을 바라보고 계신가요? 관련 글들을 읽어보셨을 테고, 에이전트가 프롬프트 인젝션을 당하면 무슨 일이 벌어지는지도 아실 겁니다. 충분히 이해합니다.

Aquaman은 세 가지 방어 계층으로 이 문제를 해결합니다:

1. 프로세스 격리: API 키는 송신 시점에 키를 주입하는 별도의 프록시 프로세스에 존재합니다. 에이전트는 키가 아닌 마커만 보유하므로, 에이전트에서 RCE가 발생하더라도 키를 읽을 수 없습니다. 코딩 에이전트는 선언한 참조만, 한 번에 한 명령씩만 받습니다.
2. 요청 정책: 서비스별 규칙으로 에이전트가 어떤 엔드포인트를 호출할 수 있는지 제어합니다. 관리자 API 차단, 삭제 방지, 초안 허용하되 전송 거부 등을 설정할 수 있습니다. 거부된 요청에는 실제 자격 증명이 절대 전달되지 않습니다.
3. 변조 감지 감사: 모든 자격 증명 사용은 SHA-256 해시 체인으로 기록됩니다. 무엇에 접근했는지 증명하고, 사후에 변조 여부를 탐지할 수 있습니다.

경로 선택

Aquaman은 하나의 보관소 + 하나의 데몬을 공유하는 네 개의 유기적인 패키지로 제공됩니다. 필요한 것만 설치하세요:

패키지	기능	설치 시점
aquaman-proxy	핵심: 보관소, 데몬, 감사, 정책, CLI. 누구나 필요한 구성 요소.	항상.
aquaman-plugin	OpenClaw Gateway 어댑터. Gateway 시작 시 프록시를 실행하고, 모델 및 Telegram 트래픽을 프록시를 통해 라우팅하며, 5가지 인증 모드에 걸쳐 25개의 내장 서비스를 제공합니다.	OpenClaw Gateway를 운영하는 경우. https://clawhub.ai/plugins/aquaman-plugin 에서도 사용 가능합니다.
aquaman-coder	AI 코딩 에이전트 어댑터. 프로젝트 범위의 aquaman://service/key 참조를 Bash 도구 호출마다 해석합니다.	Claude Code 또는 Codex를 사용하는 경우.
aquaman-hermes	Hermes 에이전트 호스트 플러그인 (Python, PyPI 배포). 네이티브 ANTHROPIC_BASE_URL/OPENAI_BASE_URL을 통해 Hermes를 옵트인 방식의 토큰 게이트 루프백 리스너로 연결하며, 세션 내 /aquaman-status 명령, 도구, 상태 확인 프로브를 추가합니다. 격리는 프록시 측에서 이루어지며, 플러그인은 자격 증명을 보유하지 않습니다.	Hermes 에이전트 호스트를 운영하는 경우. pip install aquaman-hermes
Docker Sandboxes	패키지가 아닙니다: aquaman-proxy만 필요한 별도 경로입니다. Docker 자체 프록시가 시크릿을 주입하고, aquaman get이 허용 목록 및 감사 로그와 함께 보관소에서 시크릿을 제공합니다.	Docker Sandboxes에서 에이전트를 운영하는 경우. 빠른 시작 5를 참조하세요.
NVIDIA OpenShell	패키지가 아닙니다: aquaman daemon이 OpenShell 게이트웨이의 자격 증명 드라이버가 됩니다. OpenShell이 샌드박스로부터 키를 격리하고, aquaman이 허용 목록 및 감사 로그와 함께 보관소에서 참조로 키를 제공합니다.	OpenShell 샌드박스에서 에이전트를 운영하는 경우. 빠른 시작 6을 참조하세요.

단일 aquaman CLI가 네 가지 모두를 제공합니다. vault와 audit을 위한 최상위 명령, OpenClaw 통합을 위한 aquaman openclaw ..., 코딩 에이전트 통합을 위한 aquaman coder ...(내부적으로 aquaman-coder에 위임), 그리고 Hermes Python 패키지를 위한 aquaman hermes ...가 있습니다.

빠른 시작

aquaman help, aquaman doctor가 도움이 됩니다.

1. Vault만 사용 (프록시 + 시크릿만)

npm install -g aquaman-proxy
aquaman setup                                # backend wizard + store keys
aquaman daemon &                             # start the proxy
aquaman credentials list                     # verify

프록시는 ~/.aquaman/proxy.sock(UDS, chmod 0o600)에서 수신 대기합니다. 어떤 도구든 http://aquaman.local/<service>/<path>로 지정하면 프록시가 선택한 vault 백엔드에서 해당 서비스의 인증 헤더를 주입합니다.

2. OpenClaw Gateway

openclaw plugins install aquaman-plugin           # 1. install plugin + proxy
openclaw aquaman setup                            # 2. backend + keys + plugin wire-up
openclaw                                          # 3. done - proxy starts automatically

문제 해결: openclaw aquaman doctor.

npm을 직접 사용하시나요? npm install -g aquaman-proxy && aquaman openclaw setup도 동일한 작업을 수행합니다. 프록시 CLI를 설치하고, 키를 저장하며, 플러그인을 ~/.openclaw/extensions/aquaman-plugin/에 설치하고, 자격 증명을 연결합니다(OpenClaw ≥ 2026.6.5에서는 SecretRef 참조, 이전 버전에서는 auth-profiles.json 플레이스홀더).

aquaman openclaw setup은 models.providers.<svc>.baseUrl과 channels.telegram.apiRoot를 프록시의 루프백 리스너로 지정합니다. OpenClaw의 모델 전송 계층과 각 채널이 자체 HTTP 클라이언트를 구축하여 fetch 인터셉터를 우회하기 때문입니다. Telegram 이외의 채널은 엔드포인트 재정의를 노출하지 않으므로, 해당 토큰은 저장되고 마이그레이션되지만 이그레스 시점에 주입되지는 않습니다(packages/plugin/README.md 참조). openclaw.json의 플러그인 설정 아래에 채널을 추가하세요. 지원되는 채널로는 Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face 등이 있습니다(총 25개).

3. AI 코딩 에이전트 (Claude Code, Codex)

npm install -g aquaman-proxy aquaman-coder        # 1. install daemon + adapter
aquaman setup                                      # 2. vault wizard
aquaman daemon &                                   # 3. start the proxy

aquaman coder project add my-app --path ~/code/my-app \
  --env ANTHROPIC_API_KEY=aquaman://anthropic/api_key \
  --env GITHUB_TOKEN=aquaman://github/token         # 4. declare a project
aquaman coder setup claude-code                    # 5. wire Claude Code hooks
                                                   #    (or: aquaman coder setup codex)
aquaman doctor                                     # 6. verify - should show both vault + coder green

직접 확인해 보세요 (30초 만에 깨닫는 순간): Claude Code(또는 Codex)를 재시작하고, ~/code/my-app 안에서 새 세션을 열고, 에이전트에게 다음을 실행하도록 요청하세요:

printenv | grep ANTHROPIC_API_KEY

이것은 트랜스크립트에서 보게 될 것입니다:

ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault). 

자식 프로세스는 실제 키를 보았습니다(테스트, 빌드, MCP 서버, import 스크립트 등 실제로 키가 필요한 모든 것은 정상적으로 작동합니다). 에이전트 - 즉, 여러분의 머신에서 어떤 코드를 실행할지 결정하는 주체 - 는 그 값을 결코 보지 못하며, 따라서 대화 기록도, 모델 제공자의 로그도, 나중에 여러분의 터미널을 스크린샷으로 찍는 누구도 그 값을 볼 수 없습니다.

여러분의 터미널에서도 사용하세요. 동일한 래퍼는 에이전트 없이도 작동합니다. 커버된 프로젝트로 cd한 뒤 명령 앞에 접두사를 붙이기만 하면 됩니다:

cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

동일한 환경 변수 주입, stdout/stderr에 대한 동일한 리다이렉션. Makefile 타깃, 셸 별칭, 또는 CI 러너 등 평소라면 .env 파일을 찾았을 곳 어디에든 넣을 수 있습니다.

Claude Code나 Codex가 ~/code/my-app에서 셸 명령을 실행하면, aquaman의 훅이 updatedInput.command를 통해 명령을 재작성하여 aquaman-coder exec 아래에 감쌉니다. 해당 래퍼는:

• 브로커(UDS를 통한 POST /broker/resolve)를 통해 각 aquaman://service/key 참조를 해석합니다. 자격 증명은 에이전트의 수명 동안이 아니라 단일 명령을 위해 구체화됩니다.
• stdout/stderr를 리다액터를 통해 파이프하며, 리다액터는 해석된 각 값에 대해 값 기반 패턴을 앞에 붙입니다: 주입된 문자열은 형태와 무관하게 리다액션됩니다 (Atlassian 토큰, Notion 시크릿, 내부 API 키 — 어느 것도 알려진 제공자 형식과 일치할 필요가 없습니다). 형태 기반의 일반 패턴(sk-ant-, ghp_, sk_live_, AKIA…, JWT, PEM 블록, ATATT3xF…)은 우리가 주입하지 않은 시크릿이 자식 프로세스에서 노출될 경우를 대비한 심층 방어로서 이후에 여전히 실행됩니다.
• 명령이 종료되면 정리합니다.

Claude Code 샌드박스: 기본적으로 Unix 소켓을 차단하므로, aquaman coder setup claude-code는 macOS에서 프록시 소켓을 허용 목록에 추가합니다(sandbox.network.allowUnixSockets). Linux와 WSL2는 해당 목록을 무시하며, 유일한 옵션은 sandbox.network.allowAllUnixSockets: true로, 이는 샌드박스된 명령에 모든 Unix 소켓을 개방합니다.

Codex: 설정 후 Codex의 시작 훅 검토에서 aquaman 훅을 승인하세요(Codex는 신뢰하기 전까지 새 훅을 건너뜁니다). 해당 샌드박스 역시 기본적으로 프록시 소켓을 차단하므로, aquaman coder setup codex는 이를 허용하는 config.toml 권한 프로필을 출력합니다. Codex 훅은 셸 출력을 재작성할 수 없으므로, 리다액션은 aquaman-coder exec 내부에서 이루어집니다. 자세한 내용은 packages/coder/README.md를 참조하세요.

4. Hermes (에이전트 호스트)