NiuTrans/ToFu

Tofu는 단 하나의 명령어로 실행할 수 있는 **완전한 셀프 호스팅 AI 어시스턴트 (fully self-hosted AI assistant)**입니다. 이 도구는 OpenAI 호환 LLM (Large Language Model)에 연결하여 단순한 질의응답부터 웹 검색, 코드베이스 편집, 브라우저 제어, 그리고 전문 에이전트 팀으로서의 협업이 가능한 자율적인 다단계 에이전트 (autonomous multi-step agents)에 이르기까지 완전한 AI 워크스페이스를 제공합니다.

모든 것은 사용자의 기기에서 실행됩니다. 데이터는 절대 사용자의 인프라를 벗어나지 않습니다. 단 한 번의 python server.py 실행으로

즉시 시작할 수 있습니다.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/rangehow/ToFu/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/rangehow/ToFu/main/install.ps1 | iex

또는 Python으로 직접 설치 (모든 OS):

git clone https://github.com/rangehow/ToFu.git && cd ToFu
python install.py

이 과정은 전용 conda 환경을 생성하고, conda-forge로부터 모든 의존성 (dependencies)을 설치하며, 서버를 시작합니다. 준비가 되면 **http://localhost:15000**을 여세요.

🐍

Conda 기반 설치 프로그램. 설치 프로그램은 conda-forge만을 독점적으로 사용합니다. conda가 없는 경우 Miniforge를 자동으로 설치하고, conda를 먼저 업데이트하며 (구버전은 솔버 (solver) 중단을 유발함), libmamba 솔버를 설치한 다음, Python 3.12 및 모든 의존성(lxml, playwright, postgresql 포함)을 갖춘 tofu 환경을 생성합니다. 이를 통해 오래된 호스트 (CentOS 7, glibc 2.17)에서 pip의 manylinux 휠 (wheels)이 겪는 GLIBC 불일치 문제를 방지합니다.

💾

데이터베이스: 제로 설정 (zero-config). Tofu는 기본적으로 SQLite (Python에 내장됨)를 사용합니다. 만약 postgresql을 사용할 수 있다면 (설치 프로그램이 conda-forge에서 이를 가져옵니다), Tofu는 100명 이상의 사용자와 더 나은 동시성을 위해 루트 권한이 없는 유저스페이스 PG 인스턴스를 자동으로 부트스트랩합니다. TOFU_DB_BACKEND=sqlite를 사용하여 SQLite를 강제할 수 있습니다 (레거시 CHATUI_DB_BACKEND=sqlite도 여전히 작동합니다).

# API 키 및 포트 사전 설정
python install.py --api-key sk-xxx --port 8080
# 설치만 수행, 실행은 하지 않음
...

git clone https://github.com/rangehow/ToFu.git && cd ToFu
docker compose up -d

**http://localhost:15000**을 여세요 — 완료되었습니다. 모든 데이터는 Docker 볼륨 (volumes)에 유지됩니다.

수동 설치 (Manual Install) (완전한 제어를 위해)

사전 요구 사항 (Prerequisites): 최신 버전의 conda (Miniforge를 강력히 권장합니다).
그 외에는 아무것도 필요하지 않습니다. 모든 런타임 의존성(ripgrep, fd-find, PostgreSQL, Chromium shared libs, lxml, trafilatura, playwright, …)은 conda-forge를 통해 설치되므로, sudo 권한이나 시스템 패키지가 전혀 필요하지 않습니다.

💡

왜 모든 것을 conda-forge로 설치하나요? 오래된 Linux 호스트(CentOS 7 / glibc 2.17)의 경우, lxml 등의 pip manylinux 휠(wheels)은 임포트(import) 시점에 GLIBC_2.25 not found 오류와 함께 충돌이 발생합니다. conda-forge 빌드는 더 오래된 sysroot glibc에 링크되어 구축되므로 어디에서나 작동합니다.

# 1. 아직 conda가 없다면 Miniforge를 설치하세요
wget -O /tmp/Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash /tmp/Miniforge3.sh -b -p ~/miniforge3
...

⚠️ 이 패키지들에 대해 pip와 conda를 절대 혼용하지 마세요. 이전 실행에서 pip로 설치된 lxml 휠이 환경에 남아 있다면, conda는 (버전이 이미 충족되었다고 판단하여) 아무 작업도 수행하지 않으며, 결과적으로 고장 난 휠이 계속 충돌을 일으킵니다. 만약 이런 일이 발생한다면:

pip uninstall -y lxml flask flask-compress requests psutil trafilatura playwright pillow python-pptx mcp
conda install -c conda-forge -y --force-reinstall <동일한 패키지 목록>

단일 명령어로 실행되는 install.sh / install.py는 이 과정을 자동으로 수행합니다.

데이터베이스 자동 감지 (Database auto-detection): 첫 실행 시, Tofu는 (최적의 동시성을 위해) PostgreSQL을 먼저 시도합니다. 만약 PostgreSQL을 사용할 수 없다면 자동으로 SQLite로 전환됩니다 — 별도의 조치가 필요 없습니다. PostgreSQL은 로컬 사용자 공간 프로세스로 실행됩니다 (sudo나 시스템 서비스가 필요 없음). SQLite를 강제하려면 TOFU_DB_BACKEND=sqlite를 설정하세요 (기존의 CHATUI_DB_BACKEND=sqlite도 여전히 작동합니다).

패키지가 누락된 경우? 만약 어떤 의존성이 누락되었다면, server.py가 자동으로 bootstrap.py에 작업을 위임합니다. bootstrap.py는 conda 환경 내에서 실행 중일 때는 (GLIBC 함정을 피하기 위해) 먼저 conda install -c conda-forge를 시도하며, 그렇지 않은 경우에는 LLM 가이드 기반의 pip install로 전환합니다.

⚙️ Settings → 🔗 Providers를 클릭하고 API 키를 추가하세요. Tofu는 모든 OpenAI 호환 API와 함께 작동합니다:

Provider	설정
OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, MiniMax, GLM, Doubao, Mistral, Grok, Baidu Qianfan, OpenRouter	⚡ 템플릿에서 추가 (원클릭)
...
제공자별 여러 키(Multiple keys per provider) — API 키를 여러 개 추가하면, 하나가 속도 제한에 도달했을 때 Tofu가 자동으로 그들 사이를 순환합니다. 제공자 간에는 스마트 디스패처(smart dispatcher)가 실시간 지연 시간 점수(real-time latency scoring)와 오류율 추적을 기반으로 요청을 라우팅합니다.

또는 헤드리스/Docker 설정을 위해 환경 변수를 설정할 수 있습니다:

export LLM_API_KEY=sk-xxx
export LLM_BASE_URL=https://api.openai.com/v1
export LLM_MODEL=gpt-4o

핵심 경험: 드롭다운에서 모델을 선택하고, 메시지를 입력하며, 스트리밍 응답을 받습니다. 하지만 Tofu는 기본적인 채팅 UI를 훨씬 뛰어넘습니다.

같은 질문에 대해 여러 모델을 사용해 보고 싶을 때 — 대화 중간에 모델을 전환할 수 있습니다. 각 메시지는 어떤 모델이 생성했는지 기억하므로, 출력을 자연스럽게 비교할 수 있습니다. 모든 것을 같은 스레드에서 할 수 있도록 다른 모델의 대체 응답이나 다른 매개변수를 가진 응답으로 어시스턴트 메시지를 분기(Branch)할 수 있습니다.

중국어로 작업하지만 영어 소스가 필요할 때 — 대화별 자동 번역 기능을 활성화합니다. 중국어 질문은 모델을 위해 영어로 번역되고, 영어 응답은 다시 한국어로 번역됩니다. 원본은 항상 보존되므로 토글(toggle)하여 확인할 수 있습니다. 더 빠르고 저렴한 번역을 위해서는 LLM을 사용하는 대신 전용 기계 번역 제공자(machine translation provider)를 연결하세요.

대화가 길어져서 맥락을 잃었을 때 — Tofu의 3단계 압축 파이프라인이 이를 자동으로 처리합니다:

마이크로 압축(Micro-compaction) (비용 0): 오래된 도구 결과는 요약으로 대체되어 최근의

대화를 정리하고 싶을 때 — 사이드바에 폴더를 생성하여 관련 스레드(threads)를 그룹화할 수 있습니다. 대화를 폴더 간에 드래그하거나, 분류하지 않은 상태로 둘 수 있습니다.

어시스턴트가 최신 정보(오늘의 뉴스, 문서 업데이트, API 레퍼런스 등)가 필요할 때 — 웹을 검색하고 페이지를 읽을 수 있습니다.

작동 방식: 툴바(toolbar)에서 🔍 토글을 활성화합니다. 어시스턴트는 여러 엔진(DuckDuckGo, Brave, Bing, SearXNG)을 병렬로 검색하고, 결과의 중복을 제거한 다음, 가장 관련성이 높은 페이지를 가져와 추출합니다. 콘텐츠 필터(LLM 기반, 선택 사항)가 내비게이션, 광고 및 불필요한 문구(boilerplate)를 제거합니다.

URL을 붙여넣을 때 — 어시스턴트가 HTML, PDF 및 일반 텍스트를 처리하여 직접 가져옵니다. 인증이 필요한 페이지의 경우, 대신 브라우저 확장 프로그램(browser extension)을 사용하세요(아래 참조).

설정(Configuration) — Settings → 🔍 Search & Fetch에서 설정 가능합니다:

• 자동으로 가져올 결과 수 (기본값: 6)
• 페이지당 타임아웃(timeout) 및 최대 글자 수
• 페처(fetcher)가 절대 방문해서는 안 되는 차단된 도메인
• LLM 콘텐츠 필터 사용 여부 (속도를 위해 비활성화 가능)

이 지점에서 Tofu는 단순한 챗봇 그 이상이 됩니다. 도구(tools)를 활성화하면, 어시스턴트는 웹 검색, 코드 실행, 파일 편집, 이미지 생성 등 여러 단계의 작업을 자율적으로 수행하며, 이를 체이닝(chaining)하여 복잡한 과제를 해결할 수 있습니다.

내장 도구(Built-in tools):

도구 (Tool)	기능 (What it does)
web_search	웹 검색 (다중 엔진 병렬 수행)
fetch_url	모든 URL 읽기 (HTML, PDF, 일반 텍스트)
run_command	셸 명령 (shell commands) 실행
generate_image	이미지 생성 또는 편집 (Gemini, GPT-image)
ask_human	작업 중간에 일시 중지하고 사용자에게 질문
list_conversations / get_conversation	과거 대화 내용 참조
create_memory / update_memory / delete_memory	향후 세션을 위해 지식 저장
check_error_logs / resolve_error	프로젝트 로그의 오류 검사 및 해결
브라우저 도구 (Browser tools)	브라우저 제어 (확장 프로그램을 통해)
데스크톱 도구 (Desktop tools)	로컬 머신 제어 (에이전트를 통해)
프로젝트 도구 (Project tools)	모든 코드베이스(codebase) 탐색, 검색, 편집
...

실시간 데이터가 포함된 빠른 답변이 필요할 때 — "NVDA의 현재 가격은 무엇인가요?"라고 물으면, 어시스턴트가 검색을 수행하고 관련 페이지를 가져와 답변합니다.

다단계 워크플로 (multi-step workflow)가 필요할 때 — "상위 5개의 React 상태 관리 라이브러리를 조사하고, 이를 비교하여 추천 문서를 작성해줘."라고 요청하면, 어시스턴트가 단계를 계획하고, 검색을 실행하며, 문서를 읽고, 결과를 합성합니다 — 이 모든 과정은 자율적으로 이루어집니다.

작업이 한 번에 처리하기에 너무 복잡할 때 — 엔드포인트 모드 (Endpoint mode) (Planner → Worker → Critic)를 활성화하세요. Planner가 사용자의 요청을 수락 기준(acceptance criteria)이 포함된 구조화된 브리프로 재작성하면, Worker가 이를 실행하고, Critic이 체크리스트를 바탕으로 검토합니다. 결과가 통과되지 않으면 Critic이 피드백을 보내고 Worker가 반복 수행하며, 이는 최대 10라운드까지 진행됩니다.

무언가 실패했을 때 — 어시스턴트는 지수 백오프 (exponential backoff) 방식으로 재시도합니다. 기본 모델이 완전히 실패할 경우, 자동으로 구성된 백업 모델로 전환(fallback)하여 재시도합니다.

Tofu를 어떤 코드베이스든 가리키면, 해당 프로젝트 내에서 읽기, 검색, 편집 및 명령 실행이 가능한 코딩 어시스턴트로 변모합니다.

시작하기: 사이드바에서 Project를 클릭하고 코드베이스의 경로(예: /home/you/myproject)를 입력하세요. 그러면 어시스턴트가 다음 도구들을 사용할 수 있게 됩니다:

도구 (Tool)	기능
list_dir	파일 크기 및 라인 수와 함께 디렉토리 구조 탐색
read_files	파일 읽기 (이미지, PDF, Office 문서, 코드 지원 — 라인 번호 포함)
grep_search	ripgrep을 사용하여 파일 전체 검색 (정규 표현식 (regex), 컨텍스트 라인, 카운트 모드 지원)
find_files	glob 패턴으로 파일 찾기
write_file	파일 생성 또는 덮어쓰기
apply_diff	정밀한 검색 및 교체 편집 (여러 편집을 위한 배치 모드 지원)
insert_content	앵커(anchor)를 교체하지 않고 그 앞/뒤에 코드 추가
run_command	프로젝트 디렉토리에서 쉘 명령 실행

새로운 코드베이스를 이해해야 할 때 — "이 프로젝트의 아키텍처(architecture)에 대한 개요를 알려줘."라고 요청하세요. 어시스턴트가 디렉토리 트리를 탐색하고, 주요 파일을 읽으며, 구조를 파악합니다.

버그를 수정해야 할 때 — "로그인 페이지를 제출한 후 빈 화면이 나타납니다."라고 요청하세요. 어시스턴트가 관련 코드를 grep으로 검색하고, 컴포넌트를 읽고, 문제를 식별한 뒤, apply_diff를 사용하여 수정을 적용합니다.

안전한 실험을 원할 때 — 모든 파일 수정 사항은 대화별로 추적되며 완전한 실행 취소(undo)를 지원합니다. 실행 취소 버튼을 클릭하여 어시스턴트가 수행한 모든 변경 사항을 되돌릴 수 있습니다.

멀티 루트 프로젝트 (Multi-root projects) — 여러 디렉토리를 루트로 추가할 수 있습니다 (예: 프론트엔드 + 백엔드 리포지토리). 어시스턴트는 모든 루트에 걸쳐 네임스페이스가 지정된 경로를 해결합니다.

스마트 토큰 관리 (Smart token management) — content_ref 메커니즘을 통해 어시스턴트는 이전 도구의 결과를 다시 생성하지 않고 파일에 쓸 수 있으며, emit_to_user는 결과를 반복하는 대신 기존 도구 출력으로 사용자를 안내함으로써 턴을 종료합니다. 이는 대용량 파일에서 토큰을 크게 절약해 줍니다.

일부 작업은 단일 에이전트가 수행하기에 너무 큽니다. 스웜(swarm) 시스템을 통해 마스터 오케스트레이터(master orchestrator)가 하위 작업(sub-tasks)을 계획하고 이를 병렬로 실행되는 전문 에이전트들에게 위임할 수 있습니다.

사용 시점: "이 마이크로서비스를 3개의 별도 서비스로 리팩터링하고, API 문서를 업데이트하며, 마이그레이션 스크립트를 작성해줘."라는 요청이 있을 때, 하나의 에이전트가 모든 작업을 순차적으로 수행하는 대신, 마스터(master)가 각 하위 작업(sub-task)을 위한 병렬 에이전트들을 생성합니다.

작동 방식:

• 마스터 LLM이 하위 작업(sub-tasks)을 계획하고 역할(코더, 연구원, 작가, 검토자 등)을 할당합니다.
• **스트리밍 DAG 스케줄러 (streaming DAG scheduler)**가 의존성이 완료되는 즉시 에이전트를 실행합니다. 즉, 전체 웨이브(wave)가 끝날 때까지 기다릴 필요가 없습니다.
• 에이전트들은 아티팩트 저장소 (artifact store)(모든 에이전트에게 보이는 키-값 쌍)를 통해 데이터를 공유합니다.
• 에이전트들이 작업을 완료하면 마스터가 결과를 검토하며, 필요에 따라 후속 에이전트를 생성할 수 있습니다.
• 최종 결과는 일관된 출력물로 합성됩니다.

에이전트 역할 (Agent roles) — 각 에이전트는 역할별 시스템 프롬프트(system prompts), 모델 계층(model tiers), 그리고 제한된 도구 접근 권한(scoped tool access)을 부여받습니다. "연구원 (researcher)" 에이전트는 검색 도구를, "코더 (coder)" 에이전트는 프로젝트 도구를, "검토자 (reviewer)"는 읽기 전용 권한을 가집니다.

속도 제한 (Rate limiting) — 공유 세마포어(semaphore)를 통해 에이전트들이 동시 요청으로 LLM API에 과부하를 주는 것을 방지합니다. 429 오류 발생 시 자동 지수 백오프 (automatic exponential backoff)가 적용됩니다.

번역을 빈번하게 수행하며 더 빠르고 저렴한 결과를 원한다면, 번역을 위해 LLM을 사용하는 대신 전용 기계 번역(machine translation) 제공업체를 연결하십시오.

작동 방식: 기본적으로 Tofu는 자동 번역을 위해 저렴한 LLM 모델을 사용합니다 (문맥은 이해하지만 속도는 더 느립니다). 기계 번역 제공업체를 설정하면 모든 번역 요청이 MT API로 직접 라우팅됩니다. 이는 프롬프트 오버헤드(prompt overhead) 없이 일반적으로 LLM 기반 번역보다 3~5배 더 빠르고 10~100배 더 저렴합니다.