원문 캡처 · github.com
원문 캡처 · github.com

toli는 Claude Code, Codex 등 서로 다른 환경에서 실행되는 AI 에이전트가 작업을 맡기고 질문과 결과를 주고받도록 연결하는 도구다. 에이전트 간 통신에는 A2A 프로토콜을, 도구 연결에는 MCP를 사용하며, 한 컴퓨터 안에서뿐 아니라 네트워크를 통해 다른 사람의 에이전트와도 협업할 수 있다.

코딩 에이전트만을 위한 도구는 아니다. MCP 클라이언트가 있는 에이전트라면 참여할 수 있어, 개인 비서가 답변하기 전에 코딩 에이전트에 확인을 요청하는 식으로도 쓸 수 있다. 프로젝트 저장소에는 시연 GIF와 OpenClaw 시연 GIF가 공개돼 있다.

toli는 힌디어로 함께 일하는 사람들의 모임을 뜻하는 ‘टोली’를 이름으로 삼았다. 발음은 “toh-lee”다.

작동 방식

사용자는 toli 데몬 하나를 실행하고, 각 에이전트에 이름과 토큰을 부여한다. 에이전트는 로컬호스트에서 MCP를 통해 데몬에 연결된다. 각 에이전트에는 같은 데몬이나 다른 사람의 데몬에서 함께 작업하도록 허용된 피어가 있다. 피어는 사용자만 추가할 수 있으며 에이전트가 직접 추가할 수는 없다. 페어링할 때는 양방향으로 토큰을 주고받는다.

에이전트와 피어는 A2A를 통해 작업을 보내고, 작업을 위임하거나 질문을 하며 결과를 돌려줄 수 있다. 작업이 도착하면 toli가 해당 에이전트를 깨우고 알린다. 사용자는 TUI나 CLI에서 작업을 확인하고 관리할 수 있다. TUI 화면도 저장소에 공개돼 있다.

설치

macOS와 Linux에서는 다음 명령으로 설치한다.

sh
curl -fsSL https://raw.githubusercontent.com/arjunvlama/toli/main/install.sh | sh

Homebrew를 사용하려면 다음을 실행한다.

sh
brew install arjunvlama/tap/toli

Windows PowerShell에서는 다음 명령을 실행한다.

powershell
irm https://raw.githubusercontent.com/arjunvlama/toli/main/install.ps1 | iex

Go로 설치할 수도 있다.

sh
go install github.com/arjunvlama/toli/cmd/toli@latest

설치한 뒤 백그라운드에서 데몬을 시작하고 상태를 확인한다.

sh
toli daemon install
toli daemon status

toli daemon stop, start, uninstall 명령으로 데몬을 중지하거나 시작하고 제거할 수 있다.

같은 컴퓨터의 에이전트 연결

저장소는 2분 빠른 시작 절차를 안내한다. 먼저 각 에이전트를 시작하는 폴더에서 에이전트를 추가하고 toli에 연결한다. 여기서 폴더는 claude나 codex를 입력하는 위치 또는 편집기에서 연 폴더를 말한다. --connect에는 에이전트가 사용하는 하네스 이름을 지정한다. 피어는 에이전트에 작업을 보낼지 판단할 때 설명을 확인할 수 있다. 지원 하네스 전체 목록은 에이전트 연결 안내에 있다.

sh
cd ~/src/web-ui
toli agent add alice --description "Owns the web UI" --connect claude-code

cd ~/src/api
toli agent add bob --description "Owns the API" --connect codex

각 명령은 처리 결과를 출력한다. 예를 들어 Claude Code 연결은 다음과 같이 안내한다.

text
✓ Added agent 'alice'. card_url  http://127.0.0.1:7422/a2a/alice/.well-known/agent-card.json ✓ Connected Claude Code to agent 'alice' in ~/src/web-ui (~/.claude.json, .claude/settings.local.json). Next: start a Claude Code session, or restart a running one (`claude --continue`).

세션은 시작할 때만 toli를 불러오므로 각 폴더에서 새 세션을 시작하거나 이미 실행 중인 세션을 다시 시작해야 한다. toli agent list에서 하네스가 표시되면 연결된 것이다. Codex처럼 일부 하네스는 세션을 시작하거나 다시 시작한 뒤 메시지를 한 번 보내야 목록에 나타난다.

그다음 피어를 페어링한다. alice가 bob에게 초대장을 만든다.

sh
toli peer invite alice bob

초대장은 한 번만 사용할 수 있고 24시간 동안 유효하다. 명령은 초대 문자열을 출력하며, 이를 비공개로 전달해야 한다. 초대 문자열을 가진 사람은 누구든 alice와 페어링할 수 있다.

text
✓ Created an invite for peer 'bob'. It works once, within 24 hours. To accept it, run this where peer 'bob' runs:     toli peer accept <agent> toli-invite:eyJ2IjoxLCJhZ2Vu… Send it privately: whoever has it can pair with agent 'alice'.

bob이 자신의 환경에서 초대를 수락한다.

sh
toli peer accept bob <invite>
text
✓ Paired agent 'bob' with peer 'alice'.

연결 상태는 다음 명령으로 확인한다.

sh
toli peer list alice

출력에는 피어 이름, 연결 여부, 토큰 보유 여부, URL과 마지막 오류가 표시된다. 연결된 예시는 다음과 같다.

text
NAME  CONNECTED  HAS_TOKEN  URL                                                        LAST_ERROR bob   true       true       http://127.0.0.1:7422/a2a/bob/.well-known/agent-card.json

마지막으로 alice의 세션에서 “Ask bob what it's working on.”이라고 요청하면 bob이 작업을 받으며 깨어난다. 협업 과정을 보려면 toli TUI를 실행하거나 toli task list alice를 사용한다.

서로 다른 컴퓨터의 에이전트 연결

절차는 같은 컴퓨터에서 연결할 때와 같지만, 각 데몬이 네트워크를 통해 서로 접속할 수 있어야 한다.

toli 자체는 네트워킹을 처리하지 않는다. 데몬은 A2A 주소에서 피어의 접속을 기다린다. 기본값은 로컬호스트이며 --a2a-listen으로 설정한다. 피어에게 알릴 공개 URL은 기본적으로 A2A 주소이며 --public-url로 지정한다. 데몬 간 트래픽은 토큰과 작업 내용을 포함하는 일반 HTTP이므로 연결 방식을 신중히 선택해야 한다.

  • Tailscale 사용을 권장한다. 트래픽이 암호화되고 포트를 열 필요가 없다. 컴퓨터의 Tailscale IP는 tailscale ip -4로 확인할 수 있다. 데몬이 해당 IP에서 수신하도록 설정하고 같은 주소를 피어에게 알려준다.
sh
toli daemon install --a2a-listen <tailscale IP>:<port> --public-url http://<tailscale IP>:<port>

toli daemon install을 다시 실행하면 이전 설정을 대체한다.

  • 집이나 사무실처럼 신뢰하는 네트워크에서는 컴퓨터의 로컬 IP를 사용해 같은 방식으로 설정한다.
  • 공용 인터넷에서는 HTTPS 뒤에서만 연결한다. 데몬은 로컬에서 수신하도록 두고, A2A 주소 앞에 HTTPS 터널(Cloudflare Tunnel, ngrok)이나 리버스 프록시를 둔다. 터널의 https:// 주소를 데몬의 공개 URL로 지정한다. A2A 주소 자체를 인터넷에 직접 노출해서는 안 된다.

이후에는 앞서 설명한 2단계처럼 페어링한다. 한쪽이 초대장을 만들어 비밀번호처럼 비공개로 전달하고, 다른 쪽은 자신의 데몬에서 초대를 수락한다. 초대장 없이 연결하려면 toli peer add와 toli peer token을 사용한다. 자세한 옵션은 toli peer --help에서 확인할 수 있다.

에이전트 연결과 알림

하네스를 지정해 에이전트를 연결하는 기본 명령은 다음과 같다.

sh
toli connect <harness> <agent> [--scope project|user]

이 명령은 에이전트에 toli 도구(MCP)와 알림 기능을 제공해 작업이 도착하면 에이전트를 깨운다. 지원 하네스는 claude-code, codex, opencode, pi, openclaw다. 에이전트를 추가할 때 toli agent add --connect를 사용해도 같은 설정을 한다.

명령은 에이전트를 시작하는 폴더에서 실행해야 한다. 기본적으로 해당 폴더에서 시작한 세션을 연결하며, 모든 세션을 연결하려면 --scope user를 지정한다. 연결 과정에서 에이전트마다 새 MCP URL을 만든다. 이전 URL을 사용하는 세션은 연결이 끊기므로, 이미 가진 URL을 사용하려면 에이전트 이름 대신 --mcp-url <url>을 전달한다.

연결 뒤에는 새 세션을 시작하거나 실행 중인 세션을 다시 시작해야 한다. 세션은 시작할 때만 toli를 불러온다. 시작한 세션은 toli agent list에 하네스와 함께 표시된다. 일부 하네스는 첫 메시지를 보낸 뒤에야 세션을 등록하므로 목록에 나타나지 않으면 에이전트에게 메시지를 보내야 한다. 설정을 되돌리려면 toli disconnect <harness>를 실행한다.

다른 MCP 에이전트 연결

MCP 클라이언트가 있는 에이전트는 모두 toli를 사용할 수 있다. toli agent new-token <agent>가 출력하는 해당 에이전트의 MCP URL을 클라이언트에 지정하면 toli 도구를 제공할 수 있다.

작업이 도착했을 때 에이전트를 깨우는 방법은 두 가지다. 프로그램 형태의 에이전트는 백그라운드에서 알림을 듣는 방식으로 처리할 수 있으며, 예시는 pull.py에 있다. API가 있는 서비스형 에이전트는 웹훅을 호출하거나 알림마다 프로그램을 실행하도록 설정할 수 있다.

sh
toli agent notify <agent> --webhook <url>

웹훅 예시는 webhook.py에 있다. 동작 방식은 사용자 지정 에이전트 문서에서 확인할 수 있다.

보안과 신뢰

피어를 추가할 수 있는 주체는 사용자뿐이며, CLI나 TUI로 관리한다. 사용자가 추가한 피어는 신뢰 대상으로 취급된다. 에이전트의 하네스가 외부 작업으로 깨어날 수 있다면 피어가 보낸 작업이 에이전트를 실행시킬 수 있다.

각 에이전트는 데몬과 통신하는 토큰을 가지며, 토큰은 MCP URL에 들어 있다. 페어링마다 양방향 토큰도 발급된다. toli agent new-token과 toli peer new-token으로 각각 토큰을 교체할 수 있다.

데몬의 MCP 서버와 관리 API는 로컬호스트에서만 수신한다. 관리 API를 사용하려면 ~/.toli에 있는 관리자 토큰이 필요하다. 컴퓨터 간 연결에는 Tailscale이나 HTTPS를 사용해야 한다. toli의 A2A 트래픽 자체는 일반 HTTP로 전송된다.

에이전트는 샌드박스에서 실행하는 것이 좋다. toli는 피어와 브라우저, 다른 사용자의 접근은 차단하지만, 사용자 권한으로 셸을 실행하는 에이전트가 ~/.toli를 읽거나 관리 API를 호출하는 것까지 막지는 않는다. 에이전트가 toli의 MCP 포트에만 접근할 수 있도록 샌드박스를 구성하고, ~/.toli/**와 관리 API 포트(기본값 7421)를 차단해야 한다.

도구 목록은 MCP API 문서, 사용자 지정 에이전트 연결은 관련 문서에서 확인할 수 있다. 전체 명령은 toli --help에 정리돼 있다. 기여 안내는 CONTRIBUTING.md, 아키텍처 설명은 ARCHITECTURE.md에 있다. 보안 취약점을 발견하면 이슈를 열지 말고 SECURITY.md의 안내에 따라 비공개로 신고해야 한다.

toli는 아직 초기 단계지만 작동하며, Claude Code, Codex, OpenCode, OpenClaw, Pi에서 테스트됐다. 데몬은 macOS, Linux, Windows에서 실행된다. 라이선스는 Apache-2.0이다.