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

tokenbud는 유료 AI 계정이나 개인 컴퓨터에서 실행하는 모델을 친구·팀원·수업 구성원과 공유하는 데스크톱 앱이다. 호스트가 9자리 ID와 비밀번호를 전달하면 다른 사람은 앱이나 웹페이지에서 접속해 대화할 수 있다. API 키나 계정을 공유하지 않고, 접속 인원과 시간당 질문 수를 제한하거나 한 번의 클릭으로 공유를 끝낼 수 있다.

프로젝트는 GitHub 저장소에서 Windows, macOS, Linux용 설치 파일을 제공한다. 최신 릴리스를 내려받을 수 있으며, 현재 빌드는 코드 서명이 없어 Windows SmartScreen과 macOS Gatekeeper가 처음 실행할 때 확인을 요청한다.

호스트는 tokenbud를 열고 Share my agent를 누르면 공유를 시작한다. 게스트는 앱에서 Connect to an agent를 선택하거나 릴레이 주소를 브라우저에서 열고 ID와 비밀번호를 입력한다. 호스트는 동시 접속 좌석을 1~50개로 설정할 수 있으며 기본값은 3개다. 좌석이 모두 차면 다른 게스트는 빈 자리가 생길 때까지 기다린다. Copy link는 ID가 입력된 웹 클라이언트 링크를 복사하므로 게스트는 비밀번호만 입력하면 된다. 호스트는 접속자와 질문 중인 사람을 확인하고 개별 접속을 끊을 수 있다. 새 비밀번호를 만들면 모두 접속이 끊기며, 화면 상단의 스위치로 공유를 중단할 수 있다.

시간당 대여할 질문 수는 기본 30개이며, 이동 시간 기준으로 계산한다. 한도에 도달하면 공유가 자동으로 일시 중단되고 게스트에게 재개 시점이 표시된다. 게스트는 대화를 여러 개 시작할 수 있고 후속 질문은 앞선 맥락을 이어간다. 창이나 브라우저 탭을 닫으면 좌석을 반환한다.

호스트 앱은 Cloudflare Worker 기반 릴레이에 외부 연결을 열어 ID를 받으므로 공유자가 라우터의 포트를 열거나 포트 포워딩을 설정할 필요가 없다. 게스트의 질문은 릴레이를 거쳐 호스트 컴퓨터로 이동하고, 선택한 모델이 답한 뒤 결과가 돌아간다. 릴레이는 비밀번호의 해시만 확인·저장하며, 완료된 질문은 10분 뒤 삭제한다. 릴레이에는 각 호스트별 Durable Object가 만들어져 비밀번호 해시, 좌석 수, 활성 세션을 보관한다. 질문과 답변은 전송 중 릴레이를 거친다.

모델·메모리와 이용 조건

응답 모델로는 Ollama, LM Studio 등 이 컴퓨터에서 실행하는 모델이나 OpenAI 호환 서버를 선택할 수 있다. 앱은 해당 모델을 통상 사용하는 포트에서 자동으로 찾는다. 또는 Anthropic, OpenAI, Google Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter의 API 키를 사용하거나 사용자 지정 제공자를 설정할 수 있다. 제공자별 키는 운영체제의 키체인에 저장되고, 모델 목록은 각 제공자에서 가져온다. 추론 모델의 답변에서는 <think> 부분을 제외한다.

Claude Code 로그인 방식은 개발 빌드에서만 제공되며, 자신의 컴퓨터에서 테스트하는 용도다. Claude Code나 다른 MCP 클라이언트가 공유된 에이전트에 질문하도록 tokenbud를 MCP 서버로 쓸 수도 있다. tokenbud mcp는 ask(prompt) 도구 하나를 제공하며, 호출이 실행되는 동안에만 좌석을 사용한다. 원문에 제시된 설정 명령은 다음과 같다.

sh
claude mcp add tokenbud -e TOKENBUD_ID=418203977 -e TOKENBUD_PASSWORD=k7m2pqxa -- tokenbud mcp

대화 기록과 사용자가 저장한 짧은 사실 목록은 앱의 설정 폴더나 브라우저 IndexedDB에만 보관된다. 예를 들어 ‘Rust를 작성함’, ‘짧은 답변을 선호함’ 같은 정보가 해당한다. 저장된 사실은 연결된 에이전트에 각 질문과 함께 전달된다. 에이전트가 기억할 사실을 제안할 수 있지만, 사용자가 Remember를 선택해야 저장된다. 사이드바의 Memory에서 사실을 추가·수정·삭제하거나 메모리를 끌 수 있다. 채팅 화면에는 기억할 사실을 제안하는 기능이 있으며, 동의하기 전에는 저장되지 않는다.

tokenbud는 자격 증명을 직접 보거나 전달하지 않지만, 모델 제공자의 계정 이용 약관은 별도로 적용된다. 로컬 모델은 제공자를 거치지 않는다. 제공자 API 키는 다른 사람을 위한 서비스를 만드는 데 사용할 수 있지만, 키의 사용 방식은 키 소유자가 책임져야 하며 제공자들은 접근 권한 재판매를 금지하므로 공유만 하고 판매해서는 안 된다고 프로젝트는 설명한다. Anthropic 약관상 Claude Free·Pro·Max 구독은 개인용이며, 이를 이용해 다른 사람의 질문에 답할 수 없다. 이에 따라 Claude Code 엔진은 개발 빌드에만 포함된다. Claude를 공유하려면 Anthropic API 키를 사용해야 한다.

릴레이 선택과 자체 운영

기본 설정에서는 프로젝트가 운영하는 릴레이를 이용한다. 원한다면 Cloudflare 무료 요금제로 자체 릴레이를 배포할 수 있다. 이를 위해 Node.js 20 이상이 필요하다. Cloudflare 무료 요금제는 하루 약 100,000건의 요청을 허용하며, 접속 게스트는 약 15초마다 확인 요청을 보낸다. 프로젝트는 이를 하루 종일 접속한 약 15~20명에 해당한다고 안내한다. 5달러 유료 요금제는 이 제한에 대한 부담을 없앤다고 설명한다. Cloudflare 대시보드에서 사용자 지정 도메인을 추가할 수도 있다.

원문이 안내한 배포 명령은 다음과 같다.

sh
git clone <this repository> tokenbud
cd tokenbud/desktop && npm install # the web client is built from here
cd ../relay && npm install
npx wrangler login # opens the browser once
npm run deploy # builds the web client, then deploys the Worker

배포가 끝나면 https://tokenbud-relay.<you>.workers.dev 같은 릴레이 주소가 출력된다. tokenbud의 Settings → Relay에서 My own relay를 고르고 주소를 붙여넣은 뒤 Use this relay를 누른다. 앱은 전환 전에 해당 주소가 tokenbud 릴레이인지 확인한다. 공유하는 사람과 접속하는 사람은 모두 같은 릴레이를 사용해야 하며, 게스트는 릴레이 주소를 브라우저에서 직접 열 수도 있다. 릴레이마다 별도 ID가 발급되고 기본 릴레이의 ID는 유지된다. 설정 대신 환경 변수 TOKENBUD_RELAY=https://…를 지정하면 해당 주소가 우선 적용되며, 스크립트나 테스트에 쓸 수 있다. tokenbud를 업데이트한 뒤에는 npm run deploy를 다시 실행한다. 배포 빌드의 기본 릴레이를 바꾸려면 crates/tokenbud-core/src/lib.rs의 DEFAULT_RELAY_URL을 수정한다.

보안·개인정보와 개발

릴레이는 비밀번호에 솔트를 적용한 PBKDF2 해시를 사용하고, 호스트 비밀값과 세션 토큰에는 SHA-256을 사용한다. 한 주소에서 1분 동안 비밀번호를 10회 틀리면 해당 주소만 차단되므로 다른 게스트가 호스트를 이용하는 일을 막지는 않는다. 존재하지 않는 ID와 잘못된 비밀번호에는 같은 응답을 보내 ID를 알아내기 어렵게 한다. 웹 클라이언트 탭에는 세션 토큰만 저장하고 비밀번호는 저장하지 않는다. 새로고침하면 같은 좌석으로 돌아오며, 탭을 닫으면 45초 안에 좌석이 해제된다. 데스크톱 앱과 웹 클라이언트에는 답변이 외부 이미지나 스크립트를 불러오지 못하도록 콘텐츠 보안 정책이 적용된다. 키와 비밀값은 Windows Credential Manager, macOS Keychain, Linux keyring 등 운영체제 키체인에 보관된다. 로컬 모델을 사용할 때 질문은 두 컴퓨터와 릴레이 밖으로 나가지 않는다. 릴레이가 전송 중인 질문과 답변을 보게 되는 점이 우려된다면 자체 릴레이를 운영할 수 있다.

소스에서 빌드하려면 Rust 1.90 이상과 Node.js 20 이상이 필요하다. Linux에서는 Tauri 사전 요구 사항도 필요하다. 프로젝트 안내에 나온 명령은 다음과 같다.

sh
cd desktop && npm install && npm run build && cd ..
cargo build --release

실행 파일은 target/release/tokenbud에 생성된다. 설치 파일을 만들려면 desktop/에서 npm run bundle을 실행한다. GitHub 릴리스는 버전 태그를 푸시하면 Windows, macOS, Linux 설치 파일을 빌드해 초안 릴리스에 첨부하는 릴리스 워크플로를 사용한다.

sh
git tag v0.1.0 && git push origin v0.1.0

저장소의 주요 경로는 다음과 같다.

  • apps/desktop: Tauri 2 데스크톱 앱으로, 호스트·클라이언트 모드와 tokenbud mcp를 포함한다.
  • apps/tokenbud-host: 릴레이 연결, 좌석, 질문 한도, 모델 엔진을 담당한다.
  • apps/tokenbud-client: ID와 비밀번호로 접속하며 MCP 서버도 포함한다.
  • crates/tokenbud-core: 통신 타입, 릴레이 클라이언트, 설정, 키체인 저장 기능을 담는다.
  • relay/: Cloudflare Worker로, /에서 웹 클라이언트를 제공하고 /v1에 API를 둔다.
  • desktop/: React, Tailwind, shadcn/ui를 사용하는 UI다. src/app은 데스크톱 창, src/web은 브라우저 클라이언트다.

개발 중에는 릴레이와 웹 클라이언트를 :8787에서 실행하고, 데스크톱 앱을 핫 리로드하거나 웹 클라이언트를 :1422에서 실행할 수 있다. UI 미리보기에는 샘플 데이터가 사용된다.

sh
cd relay && npm run dev # relay + web client on :8787
cd desktop && npm run app # the desktop app with hot reload
cd desktop && npm run dev:web # web client with hot reload on :1422 (proxies /v1 to :8787)
cd desktop && npm run preview:ui # the app's UI in a browser with sample data

TOKENBUD_RELAY=http://127.0.0.1:8787을 지정하면 앱이 로컬 릴레이에 연결된다. TOKENBUD_HOME=/some/dir은 한 인스턴스의 설정을 해당 폴더에 저장해 여러 인스턴스를 한 컴퓨터에서 실행할 때 쓸 수 있다. cargo run -p tokenbud-host --example share는 창 없이 터미널에서 공유를 시작하고 ID와 비밀번호를 출력한다. UI 미리보기에서는 ?steps=host,settings:model로 특정 화면까지 이동하고, ?theme=dark로 어두운 테마를 강제하며, ?connect=1로 접속 화면을 표시한다. README의 스크린샷은 이 방식으로 만든다.

릴레이 API는 호스트 생성 POST /v1/hosts, 호스트 WebSocket 연결 GET /v1/hosts/:id/connect, 세션 생성 POST /v1/hosts/:id/sessions, 세션 종료 DELETE /v1/hosts/:id/sessions, 좌석 유지 GET /v1/hosts/:id/ping, 질문 전송 POST /v1/hosts/:id/ask, 응답 대기 GET /v1/hosts/:id/jobs/:job?wait=25, 상태 확인 GET /health로 구성된다. 호스트 생성은 인증 없이 9자리 host_id와 host_secret을 반환한다. WebSocket은 호스트 비밀값으로 인증한다. 세션 생성 요청에는 {password, name}이 들어가고 세션 토큰을 반환한다. 잘못된 ID나 비밀번호는 401, 빈 좌석이 없으면 409, 요청이 너무 많으면 429, 공유 중이 아니면 503을 반환한다. 좌석 유지 요청은 15초마다 보내며 45초 동안 요청이 없으면 세션이 끝난다. 질문 요청의 {prompt, history, context?}에서 context는 게스트 메모리를 전달하며 최대 10KB다. 이미 질문이 실행 중이면 409, 일시 중단 상태면 503을 반환한다. 응답은 긴 폴링으로 받는다. /health는 {"service": "tokenbud-relay"}를 반환하며 인증이 필요 없다. 요청 본문은 최대 1.5MB다.

오류는 {"error": "A sentence for people.", "code": "wrong_password"} 같은 JSON으로 반환된다. 안내 문장이 아니라 code를 기준으로 처리해야 한다. 오류 코드는 wrong_password, rate_limited, seats_full, busy, not_sharing, paused, session_ended, too_large, bad_request, not_found다. WebSocket에서 호스트는 config {password, seats, name}, pause {paused}, kick {session_id}, result {job_id, status, text?, error?}를 보내고, 릴레이는 sessions, job, cancel을 보낸다.

프로젝트는 취미로 운영되며 시간이 날 때 유지 관리한다. 이슈와 풀 리퀘스트를 받으며, 작고 범위가 명확한 변경이 검토하기 쉽다고 안내한다. 설정 절차와 CI 검사, 코드 스타일은 CONTRIBUTING.md에, 변경 기록은 changelog에 있다. 라이선스는 MIT이며, 사용하는 모델 제공자의 약관은 별도로 적용된다.