빠른 시작
요구 사항
| 요구 사항 | 최소 | 권장 |
|---|---|---|
| Node.js | 22.22+ | 최신 LTS |
| RAM | 8 GB | 16 GB+ |
| 디스크 | 5 GB | 모델 사용 시 20 GB+ |
| GPU | 선택 사항 | 빠른 로컬 추론에는 8 GB+ VRAM |
| Docker | 선택 사항 | Work 작업에는 필수 |
Libre WebUI는 CPU 전용 Ollama에서도 작동하지만 CPU에는 더 작은 모델이 적합합니다. 클라우드 제공자 플러그인은 관련 API 키만 있으면 됩니다.
Chat, 문서, Artifacts 및 제공자 기반 기능에는 Docker가 필요하지 않습니다. Work에는 필요합니다. Libre WebUI 백엔드를 실행하는 컴퓨터에 Docker가 설치되어 있어야 하며 백엔드 프로세스가 Docker를 호출할 수 있어야 합니다. npx libre-webui 명령은 Docker를 설치하지 않습니다. Docker를 사용할 수 없어도 Libre WebUI의 나머지 기능은 계속 실행되지만 Work에는 런타임을 사용할 수 없음이 표시됩니다. 대체 방법으로 모델 명령을 호스트에서 직접 실행하는 일은 없습니다.
Libre WebUI 시작
npx libre-webui@latest
http://localhost:8080을 여세요. 첫 번째 계정을 만들면 해당 계정이 관리자가 됩니다. 이후의 공개 가입은 ENABLE_SIGNUP=true를 명시적으로 설정하지 않는 한 비활성화된 상태로 유지됩니다.
패키지 실행기는 영속 상태를 ~/.libre-webui에 보관합니다. 다른 위치를 선택하려면 절대 경로 DATA_DIR을 설정하세요. 상대 경로 값은 npx를 실행한 디렉터리를 기준으로 해석됩니다.
Ollama 설치
Ollama를 설치한 다음 작은 범용 모델을 가져옵니다.
ollama pull gemma4:12b
그 밖의 강력한 선택지는 gemma4:26b(MoE), gemma4:31b(dense), qwen3.8:27b입니다. Libre WebUI의 모델 관리자에서 설치된 모델을 둘러보고, 실시간 Ollama Library를 검색하고, 앱을 벗어나지 않고 모델을 가져올 수 있습니다.
시맨틱 문서 검색을 사용하려면 임베딩 모델도 설치하세요.
ollama pull nomic-embed-text
클라우드 제공자 추가
클라우드 제공자는 선택 사항입니다. 설정 → API 키에서 사용자별 키를 추가하거나 backend/.env에 서버 전체 키를 추가한 뒤(이후 백엔드를 다시 시작) 설정에서 제공자를 활성화하세요.
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
지원되는 경우 앱이 제공자 모델 목록을 새로 고칩니다. 최신 모델 이름을 확인하려고 문서를 계속 열어 둘 필요는 없습니다.
첫 Work 작업 시작
Work는 각 작업에 영속 대화와 별도의 컨테이너 기반 파일 시스템을 제공합니다. 인증된 관리자가 사용할 수 있습니다.
- Libre WebUI 백엔드를 실행하는 컴퓨터에 Docker를 설치하고 시작합니다.
- 사이드바 헤더의 Work 버튼, 탭 표시줄의
+메뉴, 홈 페이지 또는Cmd/Ctrl + Shift + U에서 작업을 시작합니다. - 도구 호출을 지원하는 모델을 선택합니다.
- 만들거나 변경할 내용을 설명한 다음 실행을 선택합니다.
- 워크스페이스 창의 파일, 활동, Git, 터미널, 미리보기 탭에서 결과를 확인합니다.
작업은 사이드바에 남으므로 나중에 같은 대화와 파일로 돌아갈 수 있습니다. 실행이나 미리보기를 중지해도 워크스페이스는 유지됩니다. 작업을 삭제하면 워크스페이스가 영구적으로 삭제됩니다.
Work는 설치된 Ollama 모델, Ollama Cloud 모델 또는 설정된 채팅/완성 제공자 플러그인을 사용할 수 있습니다. 원격 제공자를 선택하면 실행 전에 Libre WebUI가 고지 사항을 표시합니다. 제공자는 대화, 도구 정의 및 모델이 요청한 도구 결과를 받습니다. 자율 실행은 유료 제공자를 여러 번 호출할 수 있습니다.
런타임, 영속성, 네트워크, 미리보기 및 보안에 관한 자세한 내용은 Work: 격리된 워크스페이스를 참조하세요.
Docker
git clone https://github.com/libre-webui/libre-webui
cd libre-webui
docker compose up -d
브라우저에서 첫 번째 관리자를 만드세요. 가입 플래그나 다시 시작은 필요하지 않으며 이후 공개 가입은 기본적으로 닫힙니다.
Ollama가 이미 호스트나 다른 컴퓨터에서 실행 중이라면 다음을 사용하세요.
docker compose -f docker-compose.external-ollama.yml up -d
NVIDIA GPU 가속에는 저장소에서 제공하는 GPU Compose 파일을 사용하세요.
저장소의 Compose 파일은 Docker가 설치되어 있을 때 Work를 사용할 수 있도록 호스트 Docker 소켓을 마운트합니다. 이는 애플리케이션에 호스트의 root와 동등한 제어 권한을 부여하므로 먼저 Work: 격리된 워크스페이스를 읽으세요. Linux에서는 .env의 DOCKER_GID를 소켓 소유 그룹으로 설정합니다. Work가 필요하지 않으면 마운트를 제거하세요.
번들 Ollama도 내부 전용입니다. 다른 호스트 프로세스가 API를 사용해야 할 때만 -f docker-compose.ollama-host.yml을 추가하세요. 이 오버라이드는 기본적으로 루프백에 바인딩됩니다.
화면 둘러보기
홈 탭은 세 영역으로 구성됩니다. 시작(새 채팅, 시크릿 채팅, 새 Work 작업), 계속(최근 대화와 작업), 탐색(노트, 캘린더, 자동화, 모델, 페르소나, Imagine)입니다. 같은 목적지는 사이드바 탐색 행과 명령 팔레트(Cmd/Ctrl + K)에도 있습니다. 명령 팔레트는 채팅, Work 작업 및 앱 동작을 유사 검색하고 메시지, 노트 및 문서 내용도 전체 텍스트로 검색합니다.
키보드 단축키
| 단축키 | 동작 |
|---|---|
Cmd/Ctrl + K | 명령 팔레트(입력 중에도 작동) |
Cmd/Ctrl + Shift + O | 새 채팅 |
Cmd/Ctrl + Shift + U | 새 Work 작업 |
Cmd/Ctrl + B | 사이드바 전환 |
Cmd/Ctrl + , | 설정 |
Cmd/Ctrl + D | 테마 전환 |
? | 단축키 탭에서 설정 열기 |
Esc | 설정 모달 닫기 |
Enter | 메시지 보내기 |
Shift + Enter | 새 줄 |