Agent 푸시 연동

수신함은 duckterm-hookd가 구동합니다. 에이전트 머신에서 플랫폼 명령을 실행하고 DuckTerm으로 일회용 QR을 스캔하면 설치, hook 연결, 서비스 시작까지 완료됩니다.

1. 1

   DuckTerm에서 Agent 알림 열기

   DuckTerm을 설치하거나 열고 설정 → Agent 알림으로 이동하세요. 토큰이나 계정 id를 복사할 필요가 없습니다.

   페어링 전에 DuckTerm 설치

   QR 스캐너는 설정 → Agent 알림에 있습니다. 아래 호스트 명령을 실행하기 전에 DuckTerm을 설치하거나 여세요.

   App Store

   스캔하여 App Store 열기

   Google Play

   스캔하여 Google Play 열기
2. 2

   명령을 실행하고 QR 스캔

   플랫폼 명령을 실행하세요. 로컬 Web UI가 포함된 hookd가 설치되고 일회용 QR이 표시됩니다. DuckTerm으로 스캔하면 지원 에이전트 hook과 백그라운드 서비스가 설정됩니다.

   아래는 그대로 실행할 수 있는 완전한 명령입니다. 패키지에 로컬 Web UI가 포함되며 모바일 자격 증명을 셸 기록에 남기지 않고 QR을 표시합니다.

   

   macOS

   Homebrew · Apple Silicon / Intel

   hookd setup zsh

   brew install ducksee/tap/duckterm-hookd && \
   "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd" setup --qr

   

   Windows

   네이티브 PowerShell / CMD · Windows 10 / 11 · x64 / arm64

   PowerShell powershell

   irm https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.ps1 | iex

   Command Prompt cmd

   curl.exe -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.cmd -o install.cmd && install.cmd

   

   Linux

   Ubuntu, Debian 등 주요 systemd 배포판 · arm64 / x86_64

   hookd setup sh

   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh \
     | DUCKTERM_PAIR_QR=1 sh

   

   Windows WSL

   Windows의 Ubuntu · WSL1 / WSL2 · 관리형 서비스

   hookd setup sh

   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh \
     | DUCKTERM_PAIR_QR=1 sh

3. 3

   확인

   duckterm-hookd status를 실행한 뒤 설정 → Agent 알림에서 로컬 푸시와 플랫폼 푸시를 각각 테스트하세요. 이후 업그레이드나 서비스 재시작에도 이 페어링은 유지됩니다.

   자세히 보기

   $ duckterm-hookd status
   DuckTerm Agent connection · vX.Y.Z
   [ok] Connected to DuckTerm: <this host>
   [ok] Background service is running
   [ok] Cloud connection is online
   [ok] Membership: Pro
   [ok] Coding agents connected: Claude Code, Codex
   
   # End-to-end Hookd → cloud → APN / Inbox test
   $ duckterm-hookd test-push --note "Setup verification"
   test push accepted by local Hookd
   source=<this host>
   time=<current RFC3339 time>
   cwd=<current directory>
   Cloud/APN delivery is asynchronous; verify it on the device or in local send records.

   그다음 설정 → Agent 알림 → 확인에서 로컬 테스트와 플랫폼 푸시 테스트를 각각 보내세요. 둘 다 휴대폰에 도착하면 설정이 완료된 것입니다.

4. 4

   Hookd 업그레이드 또는 제거

   hookd와 Web UI를 업그레이드하고 Agent hook을 해제하거나, 이 호스트에서 DuckTerm을 더 이상 사용하지 않을 때 Homebrew 서비스를 완전히 제거하세요.

   자세히 보기

   # Homebrew / native Windows: verify, upgrade, and restart Hookd
   duckterm-hookd upgrade
   
   # Linux / WSL: upgrade binary, bundled UI, and service
   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh | sh
   
   # Upgrade only the independently versioned Web UI
   duckterm-hookd ui upgrade
   
   # Disconnect Agent hooks; keep the daemon installed
   duckterm-hookd hook uninstall
   
   # Homebrew: remove the service and binary completely
   brew services stop duckterm-hookd && brew uninstall duckterm-hookd

   duckterm-hookd hook uninstall은 지원되는 Agent 설정에서 DuckTerm 항목만 제거합니다. 데몬, 페어링 및 타사 hook은 그대로 유지됩니다.

5. 5

   LAN Direct와 호스트 방화벽

   휴대폰이 LAN 또는 VPN으로 직접 연결할 수 있도록 hookd는 모든 인터페이스의 TCP 11434(0.0.0.0 / [::])를 수신합니다. 이는 인터넷 공개가 아니므로 라우터 포트 포워딩이 필요하지 않으며, 모든 연결에는 DuckTerm 페어링 키가 필요합니다.

   자세히 보기

   Windows(네이티브)

   setup은 설치 폴더를 사용자 PATH에 추가합니다. 새 터미널에서 duckterm-hookd 또는 짧은 별칭 dhook을 사용할 수 있습니다. TCP 포트 규칙은 모든 네트워크 프로필에 적용됩니다. 관리자 권한이 필요하면 관리자 PowerShell에서 실행하세요:

   duckterm-hookd firewall install
   duckterm-hookd firewall status

   macOS

   Homebrew는 duckterm-hookd와 짧은 별칭 dhook을 설치합니다. 처음 방화벽 알림에서 허용을 선택하세요. 이전에 거부했다면 아래 명령으로 Homebrew hookd 실행 파일만 허용합니다:

   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add \
     "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd"
   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp \
     "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd"

   Linux / WSL

   설치 프로그램은 duckterm-hookd와 짧은 별칭 dhook을 /usr/local/bin에 설치합니다. UFW를 사용하면 TCP 11434를 허용하세요. 라우터의 공인 포트 포워딩은 설정하지 마세요:

   sudo ufw allow 11434/tcp
   duckterm-hookd firewall status

6. 6

   Public Direct

   선택 · 고급

   hookd는 127.0.0.1:11435에 루프백 전용 인그레스를 열어, 직접 운영하는 HTTPS/WSS 터널(Cloudflare Tunnel, frp, 리버스 프록시)로 게시할 수 있습니다. LAN 주소 게이트를 넓히지 않으며 Web 제어판의 20080 포트를 포함하지도 않습니다. routeSecret은 스캐너 격리용이며 애플리케이션 키가 아니므로 페어링 인증은 그대로입니다. 변경 후에는 hookd를 재시작하세요.

   자세히 보기

   # 1 · Enable the loopback ingress (default port 11435) and register the origin
   duckterm-hookd access enable
   duckterm-hookd access add https://hookd.example.com
   duckterm-hookd access list
   
   # 2a · Cloudflare Tunnel — shortest form
   cloudflared tunnel --url http://127.0.0.1:11435
   
   # 2b · frp — shortest frpc.toml
   # serverAddr = "frps.example.com"
   # serverPort = 7000
   # [[proxies]]
   # name = "hookd"
   # type = "https"
   # localIP = "127.0.0.1"
   # localPort = 11435
   # customDomains = ["hookd.example.com"]
   
   # 3 · Public Direct changes only take effect after a restart
   duckterm-hookd restart

에이전트별 연결 참고

hookd를 설치하면 지원되는 모든 에이전트가 연결됩니다. 일부 에이전트는 첫 실행 시 한 단계가 더 있고, 이벤트가 실제로 폰까지 도달하는지를 좌우합니다 — 아래가 그 에이전트들입니다. 그다음에는 에이전트를 tmux(또는 Herdr) 안에서 실행하고 한 마디 보내 보세요. Live Preview는 붙을 세션이 있어야 합니다.

OpenCode

OpenCode는 확인 절차가 없습니다. 설치 프로그램이 DuckTerm 플러그인을 플러그인 디렉터리에 기록합니다. 이 호스트에 OpenCode가 없을 때 hookd를 설치했다면 설치 프로그램을 다시 실행해야 플러그인이 배치됩니다.

시험해 보기

cd tmp
tmux new -s op-prod-main
opencode

입력 당신은 어떤 모델인가요 그리고 폰을 확인하세요. 메시지가 Inbox에 도착하고, Live Preview에서 해당 세션이 실시간으로 보여야 합니다.

Codex

Codex는 처음 실행할 때 hook을 신뢰할지 묻습니다. 전부 신뢰를 선택하세요. 신뢰되지 않은 hook은 실행되지 않으므로 hookd가 전달할 것이 없고 Inbox는 계속 비어 있습니다.

시험해 보기

cd tmp
tmux new -s cx-prod-main
codex

입력 당신은 어떤 모델인가요 그리고 폰을 확인하세요. 메시지가 Inbox에 도착하고, Live Preview에서 해당 세션이 실시간으로 보여야 합니다.

Claude Code

Claude Code는 ~/.claude/settings.json에서 hook을 읽으며, 이 파일은 설치 프로그램이 작성합니다. Claude Code는 시작할 때만 이 파일을 읽고 hook 변경을 확인 대상으로 표시하므로, 이미 실행 중이던 세션은 한 번 재시작하고 확인을 요구하면 승인한 뒤 이벤트를 기다리세요.

시험해 보기

cd tmp
tmux new -s cc-prod-main
claude

입력 당신은 어떤 모델인가요 그리고 폰을 확인하세요. 메시지가 Inbox에 도착하고, Live Preview에서 해당 세션이 실시간으로 보여야 합니다.

DeepSeek Harness

DeepSeek Harness는 트리 외부의 hooks bridge를 통해 hookd에 연결하며, 이 bridge는 hookd가 대신 설치합니다. 실패하면 dsh 웹 UI에 오류가 표시됩니다. dsh plugin add @deepseek-ai/dsh-hooks-claude-code를 직접 실행하고 hookd 설치 프로그램을 다시 실행한 뒤 dsh 웹 UI를 재시작하세요. bridge는 재시작 이후에만 적용됩니다.

시험해 보기

cd tmp
tmux new -s dsh-prod-main
dsh

입력 당신은 어떤 모델인가요 그리고 폰을 확인하세요. 메시지가 Inbox에 도착하고, Live Preview에서 해당 세션이 실시간으로 보여야 합니다.