QUICKSTART

3분 빠른 시작

데스크톱 워크벤치와 modelbuff CLI는 동일한 로컬 설정을 공유합니다. 편한 방식으로 바로 시작하세요.

CHAPTER 01 · DESKTOP APP

데스크톱 워크벤치 시작하기

기존 설정 가져오기, 듀얼 윈도우 계정 풀, 전용 브라우저, 에이전트 연결까지 4단계로 완료.

  1. 01설치 및 가져오기
  2. 02계정 및 바인딩
  3. 03로그인 및 브라우저
  4. 04에이전트 연결

01

앱 설치 및 기존 설정 무손실 가져오기

설치 후 바로 실행하세요. 첫 실행 시 기존 도구 설정을 읽기 전용으로 탐색해 원클릭으로 가져옵니다.

기존 설정 읽기 전용 원클릭 가져오기
단계 01: 기존 설정 무손실 가져오기
스크롤 시 재생

로컬 CC Switch, OpenCode 및 ccswitch:// 링크를 스캔해 원본 손상 없이 가져옵니다.

  • 비파괴 마이그레이션 — CC Switch, Magpie, OpenCode 및 기존 CLI 설정과 ccswitch:// 링크를 안전하게 가져옵니다.

02

계정 풀과 디렉터리 바인딩 구성

모든 계정의 5시간 / 7일 잔여 한도를 한눈에 보고, 프로젝트 폴더별로 격리 계정을 고정하세요.

듀얼 윈도우 스케줄링 & 폴더 자동 바인딩
단계 02: 계정 풀 및 폴더 바인딩
스크롤 시 재생

다중 계정 잔여 한도, 5차원 환경 점검, 429 무중단 릴레이 및 프로젝트 폴더 고정을 관리합니다.

  • 스마트 릴레이 — 리셋 임박 주간 한도를 우선 소진하고 미사용 5시간 윈도우를 보호하며 429 제한 시 자동 전환합니다.
  • 폴더 고정 — 업무 폴더와 개인 폴더가 각각 지정된 계정으로 자동 연결되어 혼용 사고를 막습니다.

03

샌드박스 로그인, 속도 측정, 전용 브라우저

자체 출구 노드를 연결해 지역 시간대와 언어를 맞추고 클린 샌드박스에서 공식 로그인을 진행하세요.

출구 정렬 격리 로그인 & 전용 브라우저
단계 03: 격리 로그인 및 전용 브라우저
스크롤 시 재생

고정 출구에 맞춰 시간대와 언어를 자동 정렬하고 클린 샌드박스에서 공식 로그인을 완료합니다.

  • 클린 경계 — 호스트 자격 증명은 샌드박스에 들어가지 않으며 로그인·SMS·2FA 인증은 모두 사용자가 직접 안전하게 완료합니다.
  • 전용 브라우저 즉시 실행 — 네트워크 탭에서 전체 노드 지연과 출구 IP를 측정하고, 계정별 색상 배지가 붙은 정품 Chrome / Edge를 원클릭 실행합니다.

04

주력 에이전트와 로컬 보호 게이트웨이 연결

워크벤치에서 자주 쓰는 에이전트를 클릭 한 번으로 연결하세요. 모델을 바꿔도 개발 흐름은 그대로입니다.

에이전트 연결 & 로컬 보호 게이트웨이
단계 04: 에이전트 연동 및 로컬 게이트웨이
스크롤 시 재생

쓰던 에이전트 그대로 모델을 전환하고, 외부 도구는 127.0.0.1:28330 게이트웨이에 연결합니다.

  • 도구 유지 · 모델 전환 — Claude Code, Codex, Cursor, Antigravity, Gemini CLI, OpenCode를 원클릭 연동.
  • 양방향 민감 정보 보호 — 기본 주소 127.0.0.1:28330. 키 마스킹과 경로 치환을 캐시 손실 없이 처리합니다.

CHAPTER 02 · CLI

modelbuff CLI 시작하기

GUI 의존성 없이 SSH / WSL2에서도 완벽 동작하며 데스크톱 앱과 ~/.modelbuff/config.toml을 공유합니다.

  1. 01CLI 설치
  2. 02설정 선언
  3. 03인증 및 점검
  4. 04상태 및 게이트웨이

01

한 줄 명령으로 CLI와 PATH 심 설치

경량 독립 CLI와 PATH 심을 설치하면 이후에는 평소처럼 원래 명령을 입력하면 됩니다.

CLI 설치 및 PATH 심(Shim) 초기화
terminal — zsh · ~
curl -fsSL https://go.modelbuff.com/install.sh | sh
export PATH="$HOME/.modelbuff/shims:$HOME/.modelbuff/bin:$PATH"
modelbuff shims install
스크롤 시 재생

GUI 의존성 없는 modelbuff CLI를 한 줄로 설치하고 폴더별 자동 전환 심을 활성화합니다.

  • 의존성 제로 · 초고속 — 네이티브 Rust 바이너리, 관리자 권한 불필요, macOS / Linux / WSL2 지원 (실행 오버헤드 < 15ms).

02

config.toml에 계정과 폴더 바인딩 선언

폴더 규칙, 시간대, 로캘을 적어두면 즉시 적용되며 데스크톱 앱과 실시간으로 공유됩니다.

격리 아이덴티티 및 폴더 바인딩 설정
~/.modelbuff/config.toml
bat ~/.modelbuff/config.toml
[identities.claude-us]
bindings = ["~/work/**"]
timezone = "America/Los_Angeles"
locale = "en_US.UTF-8"
 
[identities.claude-us.cli.claude]
mode = "official_auth"
스크롤 시 재생

로컬 ~/.modelbuff/config.toml 하나로 폴더 고정, 시간대·언어 정렬, 공식 CLI 인증 모드를 선언합니다.

  • 멀티홉 고정 출구 — egress 한 줄로 [proxies.<name>]를 지정하면 CLI와 전용 브라우저가 동일한 경로를 공유합니다.

03

샌드박스 로그인, 전용 브라우저, 환경 점검

샌드박스 안에서 공식 CLI로 로그인하고 터미널에서 전용 브라우저 실행과 진단을 바로 수행합니다.

샌드박스 로그인, 계정 브라우저 및 진단
terminal — zsh · ~/work/acme-core
modelbuff login --identity claude-us claude
modelbuff browser open --identity claude-us
modelbuff identity list
modelbuff doctor
스크롤 시 재생

격리 샌드박스에서 공식 CLI 로그인을 마치고 계정 브라우저 실행과 doctor 진단으로 상태를 검증합니다.

  • 출구 및 환경 진단 — modelbuff egress check --identity claude-us로 출구 IP·원격 DNS·지연을 확인하고, modelbuff doctor로 격리 상태를 점검합니다. 이상 시 직접 연결로 새지 않고 즉시 중단합니다.
  • 터미널에서 전용 브라우저 열기 — modelbuff browser open으로 동일 출구와 독립 0700 프로필을 쓰는 정품 Chrome / Edge를 바로 엽니다.

04

상태 확인과 로컬 보호 게이트웨이 실행

평소처럼 claude, codex를 실행하면 자동으로 격리 계정이 전환됩니다.

실시간 상태 점검 및 로컬 마스킹 게이트웨이 실행
terminal — zsh · ~/work/acme-core
modelbuff status
modelbuff gateway serve
스크롤 시 재생

현재 폴더에 매칭된 계정과 윈도우 잔량을 확인하고 주요 프로토콜을 지원하는 로컬 마스킹 게이트웨이를 실행합니다.

  • 로컬 전용 — 127.0.0.1:28330에서 OpenAI / Anthropic / Gemini 요청을 통합 수신하며 [gateway]에서 포트를 변경할 수 있습니다.
ModelBuff 다운로드macOS · Windows · Linux