목차
- 배경
- herdr
- Ovis
- 자격 증명 문제
- lend
- lend가 보호하지 못하는 것들
- 선행 기술
- 사용해 보기
저는 원격 에이전트들이 제 승인 하에 내 노트북에서 도구를 사용할 수 있도록 lend를 구축했습니다. 이것이 제 작업 흐름에 어떻게 통합되는지 설명하겠습니다.
배경
요즘 저는 툴체인(toolchain)의 일부로 에이전트를 매우 많이 사용합니다. 보통 한 번에 몇 개를 실행하고 있습니다: 하나의 리포지토리에서 작동하는 Claude Code, 다른 곳의 브랜치를 검토하는 Codex, 그리고 백그라운드에서 장시간 실행되는 무언가입니다. 저는 종종 이들이 서로의 작업을 검토하도록 합니다. 이들 중 어느 것도 제 노트북에서 실행되지는 않습니다. 그들은 제가 버릴 수 있는 VM(Virtual Machine)에서 실행되며, 제 노트북에는 제가 중요하게 생각하는 것들, 즉 SSH 키, 1Password 볼트, 그리고 gh 및 클라우드 CLI가 로그인된 상태로 남아 있습니다.
저는 이 에이전트들을 picd라는 저희 호스팅 서비스인 pico.sh에서 실행합니다. 이것은 저에게 Docker 엔진과 SSH를 통한 셸을 갖춘 자체 VM을 제공합니다. 저는 herdr와 에이전트들을 그곳에서 실행하며, 홈 디렉토리가 재시작에도 유지되므로 dotfiles와 도구들이 제자리에 머무릅니다.
이 방식은 에이전트가 제 노트북의 무언가를 필요로 할 때까지는 훌륭하게 작동합니다. 이 글에서는 herdr 및 Ovis와 병렬로 에이전트를 실행하는 방법과 자격 증명 문제를 처리하기 위해 제가 작성한 도구인 lend에 대해 설명하겠습니다.
herdr
herdr는 코딩 에이전트를 위해 구축된 터미널 멀티플렉서(terminal multiplexer)입니다. 일반적인 작업 공간(workspaces), 탭, 창을 사용할 수 있을 뿐만 아니라, 각 창에서 어떤 에이전트가 실행되고 있는지, 그리고 무엇을 하고 있는지도 알고 있습니다. 사이드바는 각 에이전트가 작동 중인지, 저를 기다리고 있는지, 아니면 완료되었는지 보여주므로, 어느 것이 주의가 필요한지 한눈에 알 수 있습니다.
CLI는 실행 중인 세션과 통신하므로 에이전트들이 서로를 구동할 수 있습니다. 하나의 에이전트는 다른 창에서 Codex를 시작하고, 프롬프트를 제공하며, 그것이 끝날 때까지 기다린 다음, 그것이 말한 내용을 읽을 수 있습니다:
1herdr agent start reviewer --kind codex --pane "$PANE"
2herdr agent prompt reviewer "Review the diff on am/fix-retries" --wait --until done
3herdr agent read reviewer --source recent
원격 호스트도 같은 방식으로 작동합니다. herdr machine add agent-vm
가상 머신(VM)에 herdr를 설정하고 그 세션을 내 로컬 클라이언트에 추가합니다. 이 세션들은 제가 연결을 끊은 후에도 계속 실행됩니다.
Ovis
Ovis는 herdr를 위한 브라우저 및 휴대폰 클라이언트입니다. 이 클라이언트는 각 에이전트의 기록(transcript)을 채팅처럼 보여주며, 실시간 터미널은 탭만 하면 접근할 수 있습니다. 에이전트가 승인을 요청하거나 질문이 있을 때, Ovis는 이를 제가 답변할 수 있는 카드로 변환하고 푸시 알림을 보냅니다. 이 클라이언트는 herdr에 저장된 기기들을 가져오므로, 별도의 설정 없이도 제 VM들이 표시됩니다. 저는 Tailscale을 통해 여기에 접근합니다.
만약 제가 책상에서 자리를 비운 사이에 에이전트가 질문에 막히면, 저는 휴대폰으로 답변하고 다른 에이전트들은 계속 진행됩니다.
자격 증명 문제 (The credential problem)
VM에 있는 에이전트들은 여전히 저인 것처럼 행동해야 합니다. 저는 이들을 사용하여 gh로 CI를 모니터링하고, 1Password의 토큰으로 API를 호출하며, 다른 호스트에 SSH 접속을 합니다. 이를 작동시키는 일반적인 방법은 두 가지가 있으며, 어느 쪽도 마음에 들지 않습니다.
첫 번째는 자격 증명을 VM에 복사하는 것입니다. ~/.config/gh/hosts.yml의 토큰은 해당 기기에서 에이전트와 그것이 실행하는 모든 것을 포함하여, 토큰이 유효한 동안 읽을 수 있습니다.
두 번째는 ssh -A를 사용하여 제 SSH 에이전트를 포워딩하는 것입니다. 개인 키(private key)는 제 노트북에 남아 있지만, VM은 요청하거나 자신이 서명한 기록 없이 에이전트의 모든 키를 사용할 수 있습니다. 또한 이는 SSH 키만을 다룹니다.
제가 원했던 것은 자격 증명이 노트북에 남아 있고, 그것이 필요한 명령어들도 그곳에서 실행되는 것이었습니다. 에이전트가 무언가를 실행해달라고 요청하면, 저는 Touch ID로 승인하고 에이전트는 결과를 돌려받습니다.
lend
바로 여기에 lend가 등장합니다. lend는 기존 SSH 에이전트 앞에 놓이는 프록시(proxy)이며, 실제 소켓 대신 이 소켓을 포워딩합니다. SSH와 Git은 평소처럼 작동하며, lend는 SSH 에이전트 확장 기능을 통해 명령어를 실행할 수 있는 방법을 추가합니다.
VM의 에이전트가 gh를 실행하도록 요청하면, 그 요청은 소켓을 통해 전달되고 gh
내 노트북에서 내 로그인으로 실행됩니다. 토큰은 절대 노트북을 벗어나지 않기 때문에 에이전트가 가질 수 없습니다. 서명(signature)이든 명령(command)이든 모든 요청은 노트북의 정책과 비교되며, 어떤 일이 일어나기 전에 제 승인이 필요합니다.
1Remote: lend exec -- command args
2 |
3 forwarded SSH agent socket
...
정책은 노트북에 존재하며, VM이 요청할 수 있는 것을 나열합니다. 그 외의 모든 것은 거부됩니다. 제 정책은 상당히 짧습니다:
1{
2 "default": "deny",
3 "commands": [
...
규칙은 특정 하위 명령만 허용하고 싶을 때 ["pr", "view"]와 같은 args_prefix를 가질 수도 있습니다. biometric:inline은 Touch ID를 요청 대화 상자에 바로 표시하므로, 저는 요청을 읽고 한 번 터치하여 승인합니다. 일반적인 biometric은 '허용(Allow)'을 클릭한 후 두 번째 프롬프트에서 Touch ID를 요청합니다.
연결하려면 노트북에서 lend ssh를 실행합니다. 이는 해당 연결에 대한 프록시를 시작하고 SSH가 종료되면 중지합니다:
1lend ssh --config ./policy.json -- agent-vm
저는 VM에서 herdr을 실행합니다. Claude Code는 run_local_command라는 단일 도구를 가진 MCP 서버인 lend mcp를 통해 lend와 통신합니다. 이 도구는 실행할 명령과 이유(reason)를 받으며, 이유는 필수입니다:
1{
2 "mcpServers": {
3 "laptop": {"command": "lend", "args": ["mcp"]}
...
여기서 저는 VM의 Claude Code에게 lend 리포지토리의 설명을 요청했습니다. 이는 gh repo view 도구를 호출했고, 제 Mac은 요청을 보여주었으며, 한 번의 터치로 승인되었습니다:
Claude Code on the VM asks to run gh repo view on the laptop. The lend dialog on the Mac lists the request and the caller, Touch ID approves it, and Claude prints the repo description.
대화 상자에는 실행 파일의 전체 경로, 모든 인자(argument), 노트북에서 실행될 디렉토리, 이유, 그리고 원격 프로세스가 자신에 대해 말한 내용이 표시됩니다. 제가 승인하면, gh는 노트북에서 실행되고 stdout, stderr, 그리고 종료 코드 스트림은 에이전트로 다시 전송됩니다. 이유와 호출자 세부 정보는 VM에서 오기 때문에 '미검증(unverified)'으로 표시됩니다. 이는 제가 결정하는 데 도움을 주기 위한 것이며 정책이 허용하는 것을 변경할 수는 없습니다.
MCP를 건너뛰고 싶다면, 동일한 요청은 VM에서의 일반 CLI 호출처럼 작동합니다:
1lend exec --reason "Read the repo description" -- gh repo view antoniomika/lend
재접속 시 소켓을 안정적으로 유지하는 방법
herd panes는 SSH 연결이 끊어져도 살아남지만, 포워딩된 소켓은 해당 연결에 속합니다. 제가 재연결하면 SSH는 새로운 소켓 경로를 제공합니다. 이로 인해 여전히 실행 중인 에이전트들은 이전의 SSH_AUTH_SOCK을 유지하게 됩니다.
저는 고정된 경로에 심볼릭 링크(symlink)를 사용하고, VM에서 ~/.ssh/rc를 통해 이를 업데이트합니다. SSH는 셸을 시작하기 전에 이 파일을 실행하므로, 새로운 연결이 포워딩한 소켓을 인식할 수 있습니다:
1#!/bin/sh
2
3if [ -n "${SSH_AUTH_SOCK:-}" ] &&
...
이 검사는 포워딩된 소켓이 lend와 통신하는지 확인한 후 링크를 업데이트합니다. 이 디렉터리는 제 사용자에게만 비공개이며, 다른 에이전트 소켓과 분리하여 이 링크를 유지합니다. 저는 lend의 절대 경로를 사용하는데, 이는 셸이 PATH에 ~/.local/bin을 추가하기 전에 실행되기 때문입니다. X11 블록은 쿠키 설정을 처리하며, SSH는 이 파일이 존재할 때 이를 위임합니다.
제 ~/.bashrc는 환경 변수를 내보내기(export)하기 전에 안정적인 경로를 확인합니다:
1if [ -S "$HOME/.ssh/lend/agent.sock" ] &&
2 "$HOME/.local/bin/lend" doctor --remote --socket "$HOME/.ssh/lend/agent.sock" --timeout 1s >/dev/null 2>&1; then
3 export SSH_AUTH_SOCK="$HOME/.ssh/lend/agent.sock"
...
herdr panes의 새로운 Bash 셸은 이 경로가 작동할 때 안정적인 경로를 가져옵니다. 검사에 실패하면, Bash는 SSH_AUTH_SOCK을 그대로 둡니다. MCP(Machine Code Processor), 승인 후크(approval hooks), 그리고 Git은 제가 시작할 때 해당 경로를 상속받습니다. 재연결한 후에는 SSH 후크가 심볼릭 링크를 업데이트하고, 해당 프로세스들은 이후 요청에 새로운 소켓을 사용합니다. 오래된 소켓 경로로 이미 실행 중인 에이전트들은 환경 변수에서 안정적인 경로를 사용하여 한 번 다시 시작해야 합니다.
노트북에서 오는 SSH 연결은 계속 열려 있어야 합니다. 연결이 끊어지면 요청이 실패하고, 재연결하면 새로운 승인 및 임대(leases)와 함께 새로운 lend 세션이 시작됩니다. 이 링크는 한 번에 하나의 연결만을 가리키기 때문에, 가장 마지막 업데이트가 최종적으로 적용됩니다.
에이전트가 절대 볼 수 없는 비밀 정보
gh
이는 이미 제 노트북에 로그인되어 있기 때문에 작동합니다. 일부 도구는 토큰을 전달받아야 합니다. 그런 경우, 명령어 규칙(command rule)을 사용하여 op read와 같은 명령어로 비밀 정보를 읽어낸 다음 이를 승인된 명령어에 환경 변수(environment variables)로 전달할 수 있습니다:
1{
2 "secret_reader": "/opt/homebrew/bin/op",
3 "secret_reader_args": ["read", "--no-newline"],
...
에이전트가 gh pr view 실행을 요청하고 제가 이를 승인하면, lend는 1Password에서 토큰을 읽어와 GH_TOKEN이 설정된 상태로 gh를 실행한 후 결과를 반환합니다. 이 토큰은 노트북에 남아 있습니다. VM은 어떤 변수가 설정되는지 또는 어떤 참조가 읽히는지 알 수 없습니다. 프롬프트에는 변수 이름과 참조가 표시되며, 값 자체는 프롬프트나 기록에 절대 나타나지 않습니다.
다음은 GH_TOKEN을 주입하는 규칙을 가진 상태로 VM이 gh api user를 실행하는 모습입니다. lend에서 제가 승인한 후 1Password가 op read가 토큰을 반환하기 전에 자체 Touch ID 인증을 요청합니다. VM은 제 로그인 정보를 다시 얻게 되지만, 자신의 환경 변수에는 GH_TOKEN이 없습니다:
주의할 점이 하나 있습니다. 이는 승인된 명령어가 자신의 환경을 출력하지 않을 때만 작동한다는 것입니다. 만약 env나 sh를 승인하면, 그 값들을 그대로 넘겨준 셈입니다. 마찬가지로 op 자체를 명령어 실행으로 허용하는 것도 비밀 정보가 출력되고 해당 출력이 에이전트로 바로 가기 때문에 주의해야 합니다.
SSH 키
키 역시 별도의 정책을 갖습니다. 목록에 없는 키는 VM으로부터 숨겨지며, 목록에 있는 키는 어떤 서명(sign)을 할 수 있는지에 따라 제한될 수 있습니다. max_signatures는 세션당 키가 생성할 수 있는 최대 서명 횟수를 제한합니다.
임대(Leases)
규칙은 제가 승인할 때, 예를 들어 5분 또는 3회 사용과 같은 임대를 제공할 수 있습니다. 임대는 lend ssh 세션 내에서만 존재하며, 제가 승인한 정확한 명령어와 인자만 일치합니다. 세션이 종료되거나 화면 잠금이 발생하면 사라집니다.
상황 확인하기
lend status --all --watch는 연결된 것, 대기 중인 것, 실행 중인 것, 그리고 활성화된 임대 정보를 보여줍니다. lend pause --all은 모든 것을 취소하고 제가 재개할 때까지 새로운 요청을 거부합니다. lend history
실행된 내용과 승인 방식에 대한 기록을 유지합니다. 인자(arguments), 출력(output), 비밀 정보(secrets)는 제외하며, 인자 로깅(logging arguments)은 선택적으로 활성화할 수 있습니다.
노트북에서 에이전트 프롬프트 응답하기
에이전트는 또한 VM에서 셸 명령어 실행, 파일 편집 또는 URL 가져오기 등 제 자격 증명과는 전혀 관련 없는 것들에 대해서도 권한을 요청합니다. lend approve는 이러한 질문들을 Mac의 동일한 대화창으로 전송합니다. 노트북에서는 아무것도 실행하지 않습니다. 사용자에게 물어보고, 에이전트가 그 답변으로 무엇을 할지 결정합니다.
Claude Code의 경우, VM에 있는 PermissionRequest 훅(hook)을 사용합니다:
1{
2 "hooks": {
3 "PermissionRequest": [
...
이제 Claude Code가 일반적으로 터미널에서 멈춰서 질문할 때, Mac 화면에는 해당 명령어 또는 도구 입력이 표시되고 저는 Touch ID로 답변합니다. 노트북 정책은 어떤 주제에 대해 질문하는 것이 허용되는지 목록화하며, 각 주제는 자체적인 승인 절차를 가집니다:
1"approvals": {
2 "topics": [{"name": "claude-code", "approval": "biometric:inline"}]
3}
Codex, Antigravity, pi용 어댑터가 있으며, 그 외의 모든 경우를 위한 일반 JSON 형식도 제공됩니다. 스크립트에서도 사용할 수 있습니다: lend approve --topic deploy --title "terraform apply" && terraform apply
이는 제가 노트북에서 승인한 후에만 적용됩니다. 만약 노트북에 접근할 수 없다면, 훅은 방해되지 않는 상태를 유지하며 에이전트는 평소처럼 자체 UI에서 질문합니다.
lend가 보호하지 못하는 것
승인된 명령어는 제 사용자 권한으로 실행되며 제 파일에 접근할 수 있습니다. 승인은 무엇을 실행할지 결정하지만, lend는 이를 샌드박스(sandbox) 처리하지 않습니다. 만약 제가 셸, 인터프리터 또는 stdin으로부터 지침을 읽는 모든 것을 승인한다면, 저는 기본적으로 노트북에서 어떤 것이든 실행하는 것을 승인한 것과 같습니다. 왜냐하면 stdin은 승인 후에 스트림되며 프롬프트에 표시되지 않기 때문입니다.
프롬프트의 호출자(caller) 세부 정보는 VM에서 오며 위조될 수 있습니다. VM의 포워딩된 소켓에 접근할 수 있는 모든 사람(root 포함)은 세션이 열려있는 동안 요청을 할 수 있습니다. 정책은 여전히 그들이 무엇을 요청할 수 있는지 제한하며, 모든 요청에는 여전히 저의 승인이 필요합니다.
lend는 아직 초기 단계이며 macOS와 Linux에서 실행됩니다. 이는 PTY(Pseudo-Terminal)를 할당하지 않기 때문에 대화형 프로그램은 이를 통해 작동하지 않습니다. Linux에서는 승인이 Zenity 다이얼로그 또는 터미널 프롬프트로 이루어지며, 생체 인식(biometric) 승인은 macOS에서만 가능합니다.
기존 기술 (#)
ssh-rev-exec는 로컬 실행 요청을 SSH 에이전트 프록시(agent proxy)를 통해 전송하며, op-forward는 1Password CLI 명령어를 데스크톱 인증 기능을 가진 기기로 전달합니다. lend는 동일한 에이전트 확장 트릭(agent extension trick)을 사용하지만, 요청별 정책(per-request policy), 로컬 승인(local approval), 키 필터링(key filtering) 기능을 추가한 별도의 구현체입니다.
사용해 보기 (#)
노트북과 원격 호스트 모두에 lend를 설치합니다: