LobeHub
LobeHub

Automatic Synchronization with LobeHub Desktop

LobeHub Desktop provides users with an enhanced experience while also expanding the capabilities of LobeHub, allowing users to utilize LobeHub in offline environments. This document will guide you on how to configure LobeHub Desktop and connect it to your self-hosted instance.

System Requirements

LobeHub Desktop is built using Electron and supports the following operating systems:

  • Windows
  • macOS
  • Linux (certain distributions)

Desktop Version Information

The version release of LobeHub Desktop follows this logic:

  • Beta Version: All merges to the main branch that are automatically released will be created as Beta versions of LobeHub Desktop.
  • Stable Version: The development team will periodically release stable versions through manual tagging.

If you wish to access the latest features, you can use the Beta version; if you prioritize stability, please use the Stable version.

Connecting to a Self-Hosted Instance

LobeHub Desktop can connect to your self-hosted LobeHub instance, allowing you to use your self-hosted configuration on the desktop.

Preparations

Before connecting the desktop to your self-hosted instance, ensure that your self-hosted instance is correctly configured with the OIDC-related environment variables.

Please ensure that your self-hosted instance version is 1.83.6 or higher to support desktop connection features.

OIDC Environment Variable Configuration

OIDC is enabled automatically once the JWKS_KEY environment variable is configured on your self-hosted instance — there is no separate ENABLE_OIDC switch to set.

Click the button below to generate JWKS_KEY:

Shell
JWKS_KEY='Click button to generate'

Add the generated environment variable to your deployment configuration.

OIDC_JWKS_KEY has been renamed to JWKS_KEY. If your deployment still has OIDC_JWKS_KEY set, you need to manually rename it to JWKS_KEY — there is no automatic fallback.

If you are deploying LobeHub using one-click deployment methods (such as Vercel, Railway, etc.), you need to:

  1. Add the above environment variables to the environment variable configuration of your deployment platform.
  2. For Vercel deployments, ensure that the APP_URL environment variable is set to your domain URL, which is crucial for correctly handling authentication callbacks.

Connection Steps

  1. Open LobeHub Desktop.
  2. Click the Wi-Fi icon in the upper right corner.
  3. Enter the address of your self-hosted instance (e.g., https://your-LobeHub-instance.com).
  4. Click the "Connect" button.
  5. You will be redirected to the login page; after completing the authorization, you can use your self-hosted configuration.

Connecting the Device Gateway

The Device Gateway lets agents run local tools on this computer.

  1. Start the gateway using the Docker Compose guide. If you use a domain, proxy it to port 8788 with HTTPS and WebSocket support.

  2. To let clients get the address automatically, set this environment variable on your LobeHub server, then redeploy:

    *.txt
    Plaintext
    DEVICE_GATEWAY_PUBLIC_URL=https://device-gateway.example.com
  3. Sign in to that instance in the desktop app and turn on Device Gateway in the title bar. For the CLI, run:

    *.sh
    Shell
    lh login --server https://lobe.example.com
    lh connect

The device list shows this computer's online status after it connects.

Existing custom gateway addresses take priority. You can also specify an address with the desktop DEVICE_GATEWAY_URL environment variable or lh connect --gateway <url> without setting the server variable.

Frequently Asked Questions

502 Bad Gateway

Issue: After clicking the authorization button, a 502 Bad Gateway error occurs when redirected to the /oidc/consent path.

Solution:

  • Confirm that you have correctly set the JWKS_KEY environment variable.
  • Ensure that JWKS_KEY is in valid JSON format without extra single quotes.
  • Check your server logs for specific error messages.

If you are using Nginx as a reverse proxy, the issue may be due to oversized request headers. You can try adding the following settings to your Nginx configuration:

*.txt
Plaintext
proxy_buffer_size   16k;
proxy_buffers       8 16k;
proxy_busy_buffers_size 32k;

invalid_redirect_uri Error

Issue: Encountering the error "redirect_uri did not match any of the client's registered redirect_uris" during the authorization process.

Solution:

Check if the APP_URL environment variable matches the URL you are accessing.

Device Gateway Does Not Connect

  • Disconnects immediately: check that the gateway belongs to the instance you signed in to, including any custom address configured on the client.
  • Connection times out: run curl https://device-gateway.example.com/health on your computer. It should return OK; otherwise, check the gateway address, network and reverse proxy settings.

macOS Startup Hangs or Crashes

Issue: On macOS, the application hangs for a long time or crashes after startup.

Solution:

  • Check if you have downloaded the correct macOS architecture version:
    • For Apple Silicon (M3/M4, etc.) Macs, use the arm64 version.
    • For Intel Macs, use the x64 version.
  • Example file names:
    • Apple Silicon: LobeHub-Beta-1.83.6-arm64.dmg or LobeHub-Beta-1.83.6-arm64-mac.zip
    • Intel: LobeHub-Beta-1.83.6-x64.dmg or LobeHub-Beta-1.83.6-mac.zip

Image Loading Issues

Issue: When using a Docker-deployed server, the desktop client cannot load avatars or other image resources after connecting.

Solution:

  • If you are using Minio for storage, ensure that cross-origin requests are allowed in the Minio configuration.
  • Add appropriate CORS settings in your Minio service.