Updated FAQ for launching Libra

jaypume · jaypume · commit 739ffaf58ab8 · 2025-11-17T17:02:24.000+08:00
Signed-off-by: Jie Pu &lt;i@jaypu.com&gt;
diff --git a/README.md b/README.md
@@ -4,27 +4,26 @@
 
 ## Overview
 The biggest differentiating capability of Libra.app compared to other AI Agent products is **localization**. The specific features and dependencies are as follows:
-* **Local Mode**: All chats are sent to the local model, requiring the download of a low-bit LLM model optimized for macOS by GreenBitAI, approximately `2.5GB`.
+* **Chat Mode**: All chats are sent to the local model, requiring the download of a low-bit LLM model optimized for macOS by GreenBitAI, approximately `2.5GB`.
 * **Enhanced Mode**: Capable of autonomously performing complex tasks such as file searching, web browsing, programming, charting, and report generation. To better protect user's local data and environment, these operations run in an isolated container environment, requiring the download of a container runtime environment, approximately `1GB` in size.
 
 ## FAQ
 
-### Network Proxy Configuration During Initialization
+### Notes on Starting Libra.app
 
-If you are in one of the following situations, you may need to configure a proxy to ensure that the local model, Enhanced mode, and local upload of documents in formats such as pdf, docx, xlsx can work properly:
-* Corporate intranet
-* Mainland China
+* When starting Libra.app for the first time, it will need to download the model, Agent runtime environment dependencies, etc. These are completed automatically during the startup process and do not require manual configuration by default.
+* Currently, the download of these dependencies comes with global CDN acceleration, so you do not need to use any VPN proxy software to make it work.
+* It is also recommended not to enable any VPN proxy, as this may affect the normal operation of Libra.app.
+* If you encounter similar abnormal situations as described below, you can try to resolve them yourself according to the FAQ instructions, or try to contact the Libra.app technical team via Slack, GitHub, email, etc. for support.
 
-Configure your proxy software to use global proxy mode, or add the following network addresses to the proxy whitelist rules:
-* huggingface.co
-* ghcr.io
-* docker.io
 
-After configuring the proxy, restart `Libra.app` and wait about 10 minutes (readiness time depends on your network). You can confirm whether the above issues exist through the Libra.app interface, or verify more specifically by executing the following commands in the macOS `Terminal` app.
 
-After initialization is complete, it is recommended to disable the proxy.
+## Issue Descriptions
 
-> Note: Some proxy software has features like "virtual network card" or "TUN" mode. These modes need to be disabled when using Libra.
+### Local Mode Cannot Be Used
+Error message: `Loading Local Model`
+
+![](docs/_images/loading-local-model.png)
 
 * Confirm if the local model has been downloaded:
 ```
@@ -36,43 +35,44 @@ If you see the following content, it indicates the local model has been download
 2.5G    /Users/libra/.cache/huggingface/hub/models--GreenBitAI--Qwen3-4B-Instruct-2507-layer-mix-bpw-4.0-mlx
 ```
 
+Before starting, make sure that the relevant VPN proxy software does not have TUN mode or global mode enabled. This may affect the internal process communication of Libra.app.
 
-* Confirm if the container runtime environment is ready:
-```
-/Applications/Libra.app/Contents/Resources/bin/limactl shell libra nerdctl images
-```
-
-If you see the following content, it indicates proper initialization:
-```
-REPOSITORY                         TAG       IMAGE ID        CREATED        PLATFORM       SIZE       BLOB SIZE
-ghcr.io/greenbitai/libra-runner    v0.6.3    59727661d104    2 days ago     linux/arm64    1.781GB    565.6MB
-mcp/markitdown                     latest    ac2cdd96f844    10 days ago    linux/arm64    982.2MB    353.9MB
-```
+Or you need to manually configure `localhost`, `127.0.0.1` outside the rules in your VPN software.
 
+If you find that the local model still has not started, you can try restarting Libra.app and wait, and check whether the model has been downloaded correctly.
 
+Alternatively, you can execute the following command to manually download the model:
 
-## Issue Descriptions
-
-### Local Mode Cannot Be Used
-Error message: `Loading Local Model`
-
-![](docs/_images/loading-local-model.png)
-
-Refer to [FAQ](./README.md#faq)
+```
+HF_ENDPOINT=https://hf-mirror.com /Applications/Libra.app/Contents/Resources/bin/gbx_lm.bin --model GreenBitAI/Qwen3-4B-Instruct-2507-layer-mix-bpw-4.0-mlx 
+```
 
 
 ### Cannot Click Execute Button
 Error message: `Execution Engine is not fully ready`
 
 ![](docs/_images/execution-engine-not-fully-ready.png)
 
-Refer to [FAQ](./README.md#faq)
 
 ### Unable to Parse Uploaded PDF Files
+
 Error message: `The file content is either empty`
 
 ![](docs/_images/the-file-content-is-either-empty.png)
 
-Refer to [FAQ](./README.md#faq)
+
+* Confirm if the container runtime environment is ready:
+```
+/Applications/Libra.app/Contents/Resources/bin/limactl shell libra nerdctl images
+```
+
+If you see the following content, it indicates proper initialization:
+```
+REPOSITORY                              TAG       IMAGE ID        CREATED         PLATFORM       SIZE       BLOB SIZE
+ghcr.gnbt.io/greenbitai/libra-runner    v0.6.9    b5c04942e7ec    18 hours ago    linux/arm64    1.785GB    566.9MB
+docker.gnbt.io/mcp/markitdown           latest    a93f01634ef9    19 hours ago    linux/arm64    990.8MB    355.6MB
+```
+
+If you cannot see two similar records as above, you can try exiting all VPN proxy software and then restarting Libra.app.
 
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -4,28 +4,25 @@
 
 ## 概述
 由于Libra.app相比其他同类AI Agent产品来说，最大差异化能力在于**本地化**，具体的特性和其依赖说明如下：
-* **Local模式**: Chat都会发送到本地模型，因此需要下载由GreenBitAI针对macOS优化的低比特LLM模型，大约`2.5G`左右。
+* **Chat模式**: Chat都会发送到本地模型，因此需要下载由GreenBitAI针对macOS优化的低比特LLM模型，大约`2.5G`左右。
 * **Enhanced模式**：能自主的进行文件查找、联网搜索、编程绘图、报告生成等复杂指令，为了更好保护用户本地数据和环境，这里通过容器运行环境进行了隔离，因此需要下载容器运行环境，大约`1G`大小。
 
 ## FAQ
 
-### 初始化阶段网络代理配置
+### 启动Libra.app注意事项
 
-如果您是如下情况之一，可能需要配置代理，以保障本地模型、Enhanced模式、本地上传pdf,docx,xlsx等格式文档能正常工作。
-* 公司内网
-* 中国大陆
+* 首次启动Libra.app会需要下载模型、Agent运行环境依赖组件等，这些是启动过程自动完成的，默认情况下不需要手动配置。
+* 目前这些依赖的下载已经自带全球CDN加速，所以不需要使用任何VPN代理软件即可工作。
+* 而且也建议不要开启任何VPN代理，这可能会影响Libra.app的正常工作。
+* 如果碰到类似如下异常情况，可以尝试按照FAQ中的说明自行解决，或者尝试通过 slack, github, mail等方式给Libra.app的技术团队留言以获取支持。
 
 
-代理软件使用全局代理，或者将以下网络配置在代理白名单规则：
-* huggingface.co
-* ghcr.io
-* docker.io
-
-配置好代理后，重启`Libra.app`,等待10min左右（就绪时长取决于您的网络），可以通过Libra.app界面确定上述问题是否存在，或者通过在macos中的`Terminal`APP中执行如下命令来更具体的进行确认。
+## 现象说明
 
-初始化完成后，建议关闭代理使用。
+### Local模式无法使用
+错误提示：`Loading Local Model`
 
-> 注意：某些代理软件有类似 "虚拟网卡"，"TUN"模式，使用Libra的时候需要关闭这两种模式。
+![](docs/_images/loading-local-model.png)
 
 * 确认本地模式是否下载完成：
 ```
@@ -37,43 +34,45 @@ du -hd0 ~/.cache/huggingface/hub/models--GreenBitAI--Qwen3-4B-Instruct-2507-laye
 2.5G    /Users/libra/.cache/huggingface/hub/models--GreenBitAI--Qwen3-4B-Instruct-2507-layer-mix-bpw-4.0-mlx
 ```
 
+启动之前需要确保相关的VPN代理软件不要开启 TUN 模式 、以及 全局模式。这可能会影响Libra.app内部的进程通信。
 
-* 确认容器运行环境是否就绪：
-```
-/Applications/Libra.app/Contents/Resources/bin/limactl shell libra nerdctl images
-```
-
-看到如下内容则表明已经正确初始化：
-```
-REPOSITORY                         TAG       IMAGE ID        CREATED        PLATFORM       SIZE       BLOB SIZE
-ghcr.io/greenbitai/libra-runner    v0.6.3    59727661d104    2 days ago     linux/arm64    1.781GB    565.6MB
-mcp/markitdown                     latest    ac2cdd96f844    10 days ago    linux/arm64    982.2MB    353.9MB
-```
-
-
-
-## 现象说明
+或者需要手动在您的VPN软件中，将`localhost`, `127.0.0.1`配置在规则之外。
 
-### Local模式无法使用
-错误提示：`Loading Local Model`
+如果发现本地模型仍然没有启动，您可以尝试重启Libra.app然后等待，并检查模型是否有正确下载。
 
-![](docs/_images/loading-local-model.png)
+或者您也可以执行如下命令，进行手动下载模型。
 
-参考 [FAQ](./README.zh-CN.md#faq)
+```
+HF_ENDPOINT=https://hf-mirror.com /Applications/Libra.app/Contents/Resources/bin/gbx_lm.bin --model GreenBitAI/Qwen3-4B-Instruct-2507-layer-mix-bpw-4.0-mlx 
+```
 
 
 ### 无法点击Execute按钮
 错误提示：`Execution Engine is not fully ready`
 
 ![](docs/_images/execution-engine-not-fully-ready.png)
 
-参考 [FAQ](./README.zh-CN.md#faq)
 
 ### 上传pdf等文件后无法解析
 
 错误提示：`The file content is either empty`
 
 ![](docs/_images/the-file-content-is-either-empty.png)
 
-参考 [FAQ](./README.zh-CN.md#faq)
+
+* 确认容器运行环境是否就绪：
+```
+/Applications/Libra.app/Contents/Resources/bin/limactl shell libra nerdctl images
+```
+
+看到如下内容则表明已经正确初始化：
+```
+REPOSITORY                              TAG       IMAGE ID        CREATED         PLATFORM       SIZE       BLOB SIZE
+ghcr.gnbt.io/greenbitai/libra-runner    v0.6.9    b5c04942e7ec    18 hours ago    linux/arm64    1.785GB    566.9MB
+docker.gnbt.io/mcp/markitdown           latest    a93f01634ef9    19 hours ago    linux/arm64    990.8MB    355.6MB
+```
+
+如果无法看到类似上面的两行记录，您可以尝试退出所有VPN代理软件后，重启Libra.app代理。
+
+
 
