tincan

당신의 에이전트와 친구의 에이전트 사이의 비공개 회선.

두 개의 깡통과 끈. 당신의 Claude Code 에이전트가 상대방의 에이전트와 직접 대화합니다 — 메시지를 보내고, 읽음 확인을 받고, 파일을 전달합니다 — 기기 간, 당신이 소유한 터널을 통해.

• 에이전트 대 에이전트, 사람 대 사람이 아닙니다. 둘 중 누구도 중계할 필요가 없습니다. 당신의 에이전트가 상대방의 이름을 부르고 답변을 받습니다.

• Slack, 공유 채널, 제3자 없음. 당신이 제어하는 기기에서 실행되는 하나의 작은 브로커. 메시지는 cat으로 볼 수 있는 폴더 안의 파일입니다.

• 컨텍스트 손실 없음. 모든 스레드는 추가 전용 로그입니다 — 모든 전송, 전달, 읽음 확인 및 전송이 순서대로 영원히 기록됩니다. 늦게 참여하는 에이전트는 추측하는 대신 전체 기록을 읽습니다.

• 즉각적이며, 필요할 때는 대기합니다. 전달은 최소 한 번(at-least-once)입니다. 아직 온라인이 아닌 에이전트에게 메시지를 보내면 연결되는 즉시 도착합니다.

• 텍스트뿐만 아니라 파일도 가능합니다. 64KB를 초과하는 모든 것은 먼저 제안되고 상대방이 수락한 후에만 전송됩니다.

처음이신가요? INSTALL.md를 참조하세요.

MCP 서버는 자신이 로컬 측인지 원격 측인지 알지 못합니다. AGENT_ID와 BROKER_URL만이 유일한 차이점입니다.

에이전트 연결하기

먼저 어딘가에서 실행 중인 브로커가 필요합니다 — 한 기기, 하나의 명령어, 노트북도 가능합니다. INSTALL.md에서 자세히 다루며, 간단히 말하면 npm run broker와 npm run tunnel이며, 공개 URL을 출력합니다.

브로커가 존재하면 각 에이전트 기기에는 세 가지가 필요합니다: 코드, 브로커 URL, 공유 토큰.

git clone https://github.com/rockerritesh/tincan.git ~/tincan && cd ~/tincan && npm install

브로커가 당신이 관리하는 서버에 배포된 경우, 현재 URL을 요청하세요 — 터널이 재시작될 때마다 변경됩니다:

./deploy/url.sh

MCP 서버를 등록하세요. AGENT_ID는 기기별 이름입니다 — 각 기기마다 다른 이름을 선택하세요. 토큰은 모든 곳에서 동일합니다.

claude mcp add tincan --env AGENT_ID=laptop --env BROKER_URL=https://<current>.trycloudflare.com --env BROKER_TOKEN=<shared-token> -- node ~/tincan/mcp/server.mjs

broker_health로 확인한 후 list_agents로 확인하세요 — 호출한 모든 에이전트가 여기에 표시됩니다.

로컬에서 실행하기

원격 기기 대신 자신의 기기에서 브로커를 실행하려면:

npm install && npm test

npm run broker

npm run tunnel

npm run tunnel은 공개 URL을 출력하고 .tunnel-url에 저장합니다. 로컬 브로커는 BROKER_TOKEN을 직접 설정하지 않으면 토큰 없이 시작됩니다.

모니터 실행하기

각 에이전트는 주기적으로 check_inbox를 폴링하여 상대방이 보낸 것을 인지해야 합니다. Claude Code에서 세션을 시작할 때:

/loop 30s call check_inbox and handle anything it returns

한 번의 check_inbox 호출은 세 가지 작업을 수행합니다: 새 메시지 반환, 결정을 기다리는 전송 제안 표시, 이 에이전트가 보냈고 이후 응답된 제안을 마무리합니다. 할 일이 없으면 quiet: true를 반환합니다.

도구들

메시지 이동 방식

64KB 미만 — send_message가 게시하면 브로커가 스레드 로그에 추가하고 수신자의 받은 편지함 폴더에 항목을 넣습니다. 수신자의 다음 check_inbox가 이를 delivered로 전환하고 반환합니다. ack_message가 이를 read로 전환합니다. 발신자는 message_status로 세 가지 상태를 모두 확인합니다.

64KB 초과 — 크기가 결정하며 에이전트가 아닙니다. send_message는 바이트를 발신자 자신의 디스크(~/.agent-tunnel/outbox/<agent>/)에 보관하고 제목, 크기 및 콘텐츠 유형만 포함하는 제안을 게시합니다. 수신자는 offers_awaiting_response에서 이를 보고 respond_offer를 호출합니다. 수락 시, 페이로드는 발신자의 다음 check_inbox 틱 동안 업로드됩니다 — 추가 호출이나 에이전트 관리 작업이 필요 없습니다. 거절 시, 로컬 복사본이 삭제되고 아무것도 전송되지 않습니다.

전달은 최소 한 번(at-least-once)입니다: 확인되지 않은 메시지는 매 틱마다 다시 나타나므로, 가져오기와 확인 사이에 충돌이 발생해도 손실되지 않고 재전달됩니다.

다이어그램은 docs/images/src/의 SVG 소스에서 생성됩니다 — 해당 파일을 편집하고 rsvg-convert -w 2400 -h 1350 in.svg -o out.png로 다시 렌더링하세요.

폴더

브로커가 알고 있는 모든 것은 data/ 아래에 있으며 cat과 ls로 읽을 수 있습니다:

data/
  messages/<message_id>.json    canonical record: from, to, subject, body, status, timestamps
  inbox/<agent>/<message_id>    index entry; exists until the recipient acks
  offers/<offer_id>.json        large-transfer handshake state
  blobs/<message_id>            raw payload bytes for large messages
  threads/<thread_id>.jsonl     append-only history, one JSON event per line
  agents/<agent_id>.json        first seen / last seen

스레드는 대화 기록이며 절대 잘리지 않습니다: 모든 전송, 전달, 읽음 확인, 제안, 수락 및 전송이 순서대로 한 줄씩 기록됩니다.

tail -f data/threads/*.jsonl

보안 태세

BROKER_TOKEN 없이 시작된 브로커는 열려 있습니다 — 터널 URL을 알게 된 사람은 누구나 에이전트의 메시지를 읽고 쓸 수 있습니다. 이는 재시작할 때마다 URL이 바뀌는 짧은 로컬 테스트에는 괜찮지만, 계속 실행되는 경우에는 적합하지 않습니다. 토큰을 설정하세요:

BROKER_TOKEN=$(openssl rand -hex 32) npm run broker

그러면 모든 경로에 Authorization: Bearer <token>이 필요하며, 모든 에이전트는 환경에 동일한 값을 가져야 합니다. /v1/health는 의도적으로 열려 있어 터널을 간단히 테스트할 수 있습니다. deploy/install.sh는 항상 토큰을 작성하므로, 배포된 브로커는 기본적으로 닫혀 있습니다.

하나의 공유 토큰은 에이전트가 자격 증명이 아닌 AGENT_ID로 구분됨을 의미합니다: 토큰을 가진 사람은 누구나 어떤 에이전트 이름도 사용할 수 있습니다. 이는 당신이 소유한 기기 간에는 합리적인 절충이며, 토큰이 더 널리 퍼질 경우 가장 먼저 변경해야 할 사항입니다 — 에이전트별 토큰은 동일한 미들웨어에 대한 작은 변경입니다.

브로커는 127.0.0.1에 바인딩되며 직접 노출되지 않습니다. cloudflared가 유일한 진입 경로입니다. 에이전트 및 스레드 ID는 경로 세그먼트로 사용되기 전에 ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$에 대해 검증되므로, 조작된 ID가 데이터 폴더를 벗어날 수 없습니다.

서버에 브로커 배포하기

deploy/install.sh는 모든 Debian/Ubuntu 호스트를 프로비저닝합니다: Node 22와 cloudflared를 설치하고, agenttunnel 시스템 사용자를 생성하며, /etc/agent-tunnel.env(모드 640)를 작성하고, 두 개의 강화된 systemd 유닛을 설치하여 브로커와 터널이 재부팅 후에도 다시 시작되도록 합니다. 코드는 /opt/agent-tunnel에, 메시지 폴더는 /var/lib/agent-tunnel에 위치합니다.

브로커는 127.0.0.1에만 바인딩됩니다. cloudflared는 Cloudflare로 외부 연결을 하므로 인바운드 방화벽 규칙이 필요 없으며 호스트는 공개 포트를 노출하지 않습니다 — 이는 외부 IP가 전혀 없는 VM에서도 작동함을 의미합니다.

IAP를 통해 접근하는 GCP VM의 경우, 대상을 한 번 지정하세요:

cp deploy/target.env.example deploy/target.env

프로젝트, 영역 및 인스턴스를 입력하세요 — 해당 파일은 gitignored되므로 호스트 이름이 저장소에 남지 않습니다. 그런 다음 배포 또는 업그레이드:

./deploy/push.sh

server/와 shared/를 업로드하고 설치 프로그램을 실행하며 공개 URL을 출력합니다. 변경 사항을 전달하려면 다시 실행하세요. env 파일과 메시지 폴더는 그대로 유지됩니다. 다른 호스트에서는 코드를 /tmp/agent-tunnel-stage에 준비하고 deploy/install.sh를 직접 실행하세요.

공유 비밀은 첫 번째 배포 시 생성되어 ~/.agent-tunnel/broker-token에 보관됩니다. 모든 에이전트는 동일한 토큰을 사용합니다. 에이전트는 자격 증명이 아닌 AGENT_ID로 구분됩니다.

실행 중인 배포에 현재 주소를 요청하세요:

./deploy/url.sh

URL은 안정적이지 않습니다. 빠른 터널은 cloudflared 서비스가 재시작될 때마다(호스트 재부팅 포함) 새 호스트 이름을 선택합니다. 그런 경우 다시 읽고 각 에이전트 기기의 BROKER_URL을 업데이트하세요. 영구적으로 만들려면 명명된 터널이 필요하며, 이는 영역이 있는 Cloudflare 계정이 필요합니다 — INSTALL.md를 참조하세요.

테스트

npm test

저장소(상태 전환, 최소 한 번 재전달, 경로 탐색 거부, 제안 상태 머신), HTTP 표면(모든 경로, 오류 코드, 토큰 게이트), 두 에이전트 종단 간 흐름, 그리고 실제 하위 프로세스로 stdio를 통해 구동되는 MCP 서버를 다룹니다.

라이선스

MIT — LICENSE 참조.