lancelrq/llamapad repository overview

English⁠ | 中文⁠

⁠English

llamapad is a self-hosted, browser-based control panel for managing llama.cpp⁠ GGUF models with Docker. It runs as its own container, mounts docker.sock, and manages sibling llama.cpp containers — it does not do inference itself.

Features

• Model management: list, one-click start/stop (Docker + GPU acceleration); run several models at once, with automatic port shifting on clashes and model-based routing in the API relay
• MTP speculative decoding: detected from GGUF metadata; one switch for weights with built-in MTP layers, or link a separate MTP draft weight
• Models home: running models, recently updated repos, and Hugging Face trending/search for GGUF repos, with one-click download
• Parameter configuration: in-panel form editing with a merged-config preview; YAML import/export with automatic snapshots
• Namespaces: custom grouping, cross-namespace GGUF sharing, reference-safe deletion
• Model downloads: Hugging Face (official/mirror) and direct URL, resumable downloads, sha256 verification, configurable proxy; repo files are auto-grouped by quantization and shards are detected automatically
• Setup wizard: pick a repo, pick files, save the config in one flow
• File manager: unified directory browsing, move/rename with reference checks, disk usage overview
• Monitoring: container CPU/memory, llama.cpp inference metrics (slots/token rate), GPU memory & temperature, host disk & network, live logs
• Built-in chat Playground, plus an inference reverse proxy for scripts/SDKs
• Login authentication + REST API
• Bilingual UI (Chinese/English) with an in-app documentation center

⁠Supported tags

Built from the Dockerfile⁠ in this repository. linux/amd64 only.

⁠Prerequisites

• Docker Engine with the Compose v2 plugin (docker compose)
• For GPU acceleration: NVIDIA Container Toolkit (GPU support comes from layering docker-compose.gpu.yml in via .env's COMPOSE_FILE; a CPU-only deployment just needs COMPOSE_FILE=docker-compose.yml, no line to delete)
• Port 28960 reachable (or remapped via PANEL_PORT)

⁠Quick start

curl -fsSL https://raw.githubusercontent.com/LanceLRQ/llamapad/main/deploy/llamapad.sh | bash

The script checks Docker, installs to /opt/llamapad by default, walks you through the model library location (showing free space per disk), runtime identity, GPU, port and admin password (generated if left empty), detects the docker.sock gid, then pulls the image and starts the panel. Afterwards run llamapad from anywhere for the management menu (llamapad start|stop|status|logs -f|config|upgrade|doctor).

Prefer plain Compose? Download docker-compose.yml⁠, docker-compose.gpu.yml⁠ and .env.example⁠ (copy to .env), fill in the required values, then docker compose up -d.

⁠Environment variables

⁠Volumes

⁠Security notice

Mounting docker.sock is equivalent to granting host root privileges — anyone who can reach the panel can create privileged containers or mount arbitrary host paths. Never expose this panel directly to the public internet; put it behind an HTTPS reverse proxy and use a strong admin password. See the nginx reverse proxy guide⁠.

⁠Documentation

• Deployment & Operations⁠
• Quick Start⁠
• Chinese docs below, or browse docs/guide/zh⁠

Back to top⁠ · 中文版⁠

⁠中文

llamapad 是一个自托管的浏览器管理面板，用 Docker 管理 llama.cpp⁠ 的 GGUF 模型。面板自身以容器方式运行，挂载 docker.sock 管理平级的 llama.cpp 容器——自己不做推理。

特性

• 模型管理：列表、一键启动/停止（Docker + GPU 加速）；可同时运行多个模型，端口冲突自动顺延，API 中转按 model 字段路由
• MTP 投机解码：按 GGUF 元数据识别，权重自带 MTP 层时一个开关即可开启，也可关联单独的 MTP 加速权重
• 模型首页：正在运行的模型、最近更新的仓库，以及 HuggingFace 上热门/搜索的 GGUF 仓库，一键下载
• 参数配置：面板内表单编辑，展示合并后的最终参数；支持 YAML 导入/导出与自动快照
• 命名空间：自定义空间分组、跨空间共享 GGUF、按引用安全删除
• 模型下载：HuggingFace（官方/镜像）+ URL 直链，断点续传、sha256 校验、代理可配；输入仓库自动按量化识别分组，分片模型自动成组
• 新建向导：选仓库、挑文件、保存配置一步完成
• 文件管理：统一目录浏览、移动/重命名带引用检查、磁盘占用一览
• 监控：容器 CPU/内存、llama.cpp 推理指标（slots/token 速率）、GPU 显存与温度、宿主机磁盘与网络、实时日志
• 面板自建对话 Playground，另提供推理接口反代（供脚本/SDK 使用）
• 登录鉴权 + REST API
• 中/英双语界面，面板内置文档中心

⁠支持的标签

镜像基于本仓库的 Dockerfile⁠ 构建，仅提供 linux/amd64。

⁠前置条件

• Docker Engine + Compose v2 插件（docker compose）
• GPU 加速需要 NVIDIA Container Toolkit（GPU 由 .env 的 COMPOSE_FILE 是否叠加 docker-compose.gpu.yml 决定；纯 CPU 部署只需 COMPOSE_FILE=docker-compose.yml，不用删任何行）
• 放行 28960 端口（或用 PANEL_PORT 改映射）

⁠快速开始

curl -fsSL https://raw.githubusercontent.com/LanceLRQ/llamapad/main/deploy/llamapad.sh | bash

脚本会检查 Docker 环境，默认装到 /opt/llamapad，引导你选择模型库位置（列出各磁盘剩余空间）、运行身份、GPU、端口与管理员密码（留空随机生成），自动探测 docker.sock 的 gid，最后拉取镜像启动。之后在任意目录执行 llamapad 进入管理菜单（llamapad start|stop|status|logs -f|config|upgrade|doctor）。

想直接用 Compose：下载 docker-compose.yml⁠、docker-compose.gpu.yml⁠ 与 .env.example⁠（复制为 .env），填好必填项后 docker compose up -d。

⁠环境变量

⁠挂载卷

⁠安全提示

挂载 docker.sock 等价于赋予宿主机 root 权限——能访问面板的人就能创建特权容器、挂载宿主任意路径。不要把面板直接暴露到公网，务必放在 HTTPS 反代之后并使用强管理员密码。参见 nginx 反代文档⁠。

⁠文档

• 部署与运维⁠
• 快速开始⁠
• 英文文档见上方，或浏览 docs/guide/en⁠

回到顶部⁠ · English version⁠