Olares

English

简体中文

English

简体中文

Appearance

Install Olares on Windows (WSL 2) with Docker image ​

You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker and WSL 2, preparing the installation environment, completing the activation process, and managing the container lifecycle.

Not for production use

Currently, Olares on Windows has certain limitations including:

  • Lack of distributed storage support
  • Inability to add local nodes.

We recommend using it only for development or testing purposes.

Having trouble?

If you run into any issues, submit a GitHub Issue and include your platform, installation method, and error details.

System requirements ​

Required specifications ​

  • CPU: At least 4 cores.
  • RAM: At least 16 GB of available memory.
  • Storage: At least 150 GB of available SSD storage.

    SSD required

    The installation will fail if an HDD (mechanical hard drive) is used instead of an SSD.

  • Supported systems:
    • Windows 10 or 11
    • Linux (on WSL 2): Ubuntu 22.04 LTS or later; Debian 12 or later

Optional hardware ​

A GPU is not required to install Olares, but is necessary for most AI applications. Only NVIDIA GPUs are supported.

  • Architecture: Turing or newer (GTX 16xx, RTX 20xx, 30xx, 40xx, 50xx series, and later).

INFO

GPUs with older architectures are not recognized by Olares. AI applications that require GPU access will not run.

  • VRAM: At least 8 GB recommended. Even on a supported GPU, limited VRAM will prevent many AI applications from running.
Not sure if your GPU is supported?

Run the following command and check the code name prefix in the output:

bash
lspci | grep -i nvidia

Example output:

3b:00.0 VGA compatible controller: NVIDIA Corporation AD102 [GeForce RTX 4090] (rev a1)

The code name prefix maps to GPU architecture as follows:

Code name prefixArchitectureSupported
GBBlackwell✓
ADAda Lovelace✓
GAAmpere✓
TUTuring✓
GPPascal✗
GMMaxwell✗

You can also verify against the full compatible GPU list from the NVIDIA open driver repository.

Windows verification

You can also confirm your GPU in Task Manager > Performance. To verify the driver is accessible in WSL, run nvidia-smi in your WSL terminal.

Before you begin ​

Before you begin, ensure the following:

  • Docker Desktop is installed and running on your system.

    WSL 2 and Hyper-V

    If Docker Desktop is configured to use Hyper-V, GPU support for Olares cannot be enabled. Ensure Docker Desktop is set to run in the WSL 2 mode.

  • You know the IP address of the current device.

    View IP Address

    In PowerShell or Command Prompt, use the following command to confirm your IP address:

    bash
    ipconfig | findstr /i "IPv4.*192"
  • You have created an Olares ID via LarePass.

Configure WSL 2 ​

  1. Open PowerShell and run the following command to confirm the kernel version of WSL installed on your system:

    powershell
    wsl --version

    Example output:

    PowerShell
    WSL version: 2.4.8.0
Kernel version: 5.15.167.4-1
WSLg version: 1.0.65
MSRDC version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26100.3475

  2. Run docker info and look for the Cgroup version section as shown below. Make sure it is v2.

    powershell
    ...
Cgroup Driver: cgroupfs
Cgroup version: 2

  3. Use the link provided to download the appropriate kernel file matching your version: https://dc3p1870nn3cj.cloudfront.net/bzImage-<kernel-version>. For example, For kernel version 5.15.167.4, download the file from https://dc3p1870nn3cj.cloudfront.net/bzImage-5.15.167.4.

    Supported kernel versions (above 5.15.146.1) are:

    • linux-msft-wsl-5.15.146.1
    • linux-msft-wsl-5.15.150.1
    • linux-msft-wsl-5.15.153.1
    • linux-msft-wsl-5.15.167.4
    • linux-msft-wsl-6.6.75.1
    • linux-msft-wsl-6.6.36.6
    • linux-msft-wsl-6.6.36.3

  4. Set the default version of WSL to version 2:

bash
wsl --set-default-version 2
  1. In the directory C:\Users\<YourUsername>\, create a file named .wslconfig with the following content:
    txt
    [wsl2]
kernel=c:\\path\\to\\your\\kernel\\bzImage-<version> # Note: Use double backslashes (\\) as path separators
memory=8GB # Recommended: 16GB
swap=0GB

    INFO

    If you installed Docker Desktop before modifying the .wslconfig file, it is recommended to remove the docker-desktop distribution installed under WSL:

    bash
    wsl --unregister docker-desktop
wsl --unregister docker-desktop-data # If this version exists
  2. Restart your computer to apply the changes.

Prepare Docker ​

If you have installed Docker Desktop before modifying .wslconfig, remove docker desktop then restart Windows.

Run olaresd-proxy ​

  1. Download olaresd-proxyfrom the following link: https://dc3p1870nn3cj.cloudfront.net/olaresd-proxy-v0.1.0-windows-amd64.tar.gz.
  2. Extract the file and start the olaresd-proxy executable.

    Keep olaresd-proxy running

    Ensure that olaresd-proxy runs in the background during the installation and activation of Olares.

Run Olares using the Docker CLI ​

CUDA version requirements

CUDA 13.1 is required for GPU support. Ensure your NVIDIA driver is up to date to support CUDA 13.1.

Run the following command to pull the Olares image. Replace <host ip> with your device's IP address and <olares version> with the desired version of Olares:

bash
docker run -d --privileged -v oic-data:/var \
  -e HOST_IP=<host ip> \
  -p 80:80 \
  -p 443:443 \
  -p 30180:30180 \
  -p 18088:18088 \
  -p 41641:41641/udp \
  --name oic \
 beclab/olares:<olares version>
bash
docker run --gpus all -d --privileged -v oic-data:/var \
 -e HOST_IP=<host ip> \
 -p 80:80 \
 -p 443:443 \
 -p 30180:30180 \
 -p 18088:18088 \
 -p 41641:41641/udp \
 --name oic \
 beclab/olares:<olares version>

where:

  • -d: Starts the container in detached mode to allow it to run in the background.
  • --privileged: Grants the container elevated privileges.
  • -v oic-data:/var: Binds a Docker volume (oic-data) to the /var directory inside the container to persist data.
  • -e HOST_IP=<host ip>: Specifies the host device's IP address as an environment variable.
  • -p 80:80: Maps port 80 on the host to port 80 in the container.
  • -p 443:443: Maps port 443 on the host to port 443 in the container.
  • -p 30180:30180: Maps port 30180 on the host to port 30180 in the container.
  • -p 18088:18088: Maps port 18088 on the host to port 18088 in the container.
  • -p 41641:41641/udp: Maps UDP port 41641 on the host to UDP port 41641 in the container.
  • --name oic: Names the container oic (Olares in container) for easier reference.
  • beclab/olares:<olares version>: Specifies the Olares Docker image and version. For example: beclab/olares:1.11.5.

When the container is running, you will see a container ID output.

Do not add the --rm flag

The --rm flag automatically deletes the container after it stops. If this happens, you will not be able to restart the container and will need to reinstall Olares to run it again. Omitting this flag preserves the container after stoppage, enabling you to resume it with thedocker start command.

Finish installation and activate Olares ​

Same network required

To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network.

  1. Open LarePass app on your phone.

  2. On your Olares activation page, tap Discover nearby Olares. LarePass will list the detected Olares instances in the same network.

  3. Select the target Olares instance from the list and tap Install now. ISO Activate

  4. When the installation completes, click Activate now.

  5. In the Select a reverse proxy dialog, select a node that is closer to your geographical location. The installer will then configure HTTPs certificate and DNS for Olares.

    Note

    • You can change this setting later on the Change reverse proxy page in Olares.
    • If your Olares device is connected to a public IP network, this step will be skipped automatically.

  6. Follow the on-screen instructions to set the login password for Olares, then tap Complete.

    ISO Activate-2

Once activation is complete, LarePass will display the desktop address of your Olares device, such as https://desktop.marvin123.olares.com.

Log in to Olares ​

  1. Open the Olares desktop address in your browser, and press any key to continue.

  2. On the login page, enter your Olares login password.

    Log in

  3. You will be prompted to complete two-factor verification. You can confirm the login on LarePass, or manually enter the 6-digit verification code.

    Confirm login

    INFO

    The verification code is time-sensitive. Ensure you enter it before it expires.

Once you've logged in, you'll be directed to the Olares desktop.🎉

Manage the Olares container ​

Stop the container ​

To stop the running container:

bash
docker stop oic

Restart the container ​

To restart the container after it has been stopped:

bash
docker start oic

Uninstall the container ​

To completely remove the container and its associated data:

bash
docker stop oic
docker rm oic
docker volume rm oic-data

Next step: Protect your Olares ID ​

You're almost ready to start using Olares! Before diving in, it's crucial to ensure your Olares ID is securely backed up. Without this step, you won't be able to recover Olares ID if needed.