**Olares is an open-source personal cloud OS you operate in plain language, built to run AI agents and LLMs on hardware you own.**
Powered by Kubernetes, it turns your machines into a self-hosted AI platform accessible from any browser, giving everyone from individual users to small teams a unified place for compute, storage, networking, and apps.
https://github.com/user-attachments/assets/3e4b0c5d-dcbe-47eb-8628-88b062411fa0
> 🌟 *If Olares is useful to you, consider giving the project a star. Your support encourages us to keep improving it.*
## Release highlights
- **[Olares 1.12.7](https://www.olares.com/blog/olares-1-12-7/):** Router, Lares, and a broader local AI model catalog.
- **[Olares 1.12.6](https://www.olares.com/blog/olares-1-12-6/):** Agent Skills, Model Console for local LLMs, and more reliable shared apps.
## Why Olares
Great AI needs to know you. That requires access to your files, messages, and history. Many cloud AI services store this sensitive data on third-party servers and charge based on usage.
Olares brings AI home, so you can use [Lares](https://www.olares.com/docs/use-cases/lares), the official Olares AI assistant, or agents like [OpenClaw](https://www.olares.com/docs/use-cases/openclaw) with local LLMs on hardware you own while still enjoying the access and convenience of the cloud.
Features include:
- **One-click local AI:** Install open-source AI apps and models from [Olares Market](https://www.olares.com/market/) with one click.
- **Accelerated computing management:** Pool GPUs and other accelerators across nodes, with time-slicing, memory-slicing, and exclusive GPU modes for AI, media, and gaming workloads.
- **[Files and storage management](https://www.olares.com/docs/manual/olares/files/):** Access local files, synced data, connected cloud storage, and external SMB/NFS shares through the built-in Files app, with [configurable backups](https://www.olares.com/docs/manual/olares/settings/backup).
- **[Private networking and access controls](https://www.olares.com/docs/developer/concepts/network):** Use a private VPN, reverse proxy, and public, private, or internal entrances to give apps HTTPS endpoints without manually exposing individual ports.
- **Anytime, anywhere access:** Access your apps and files from your phone, desktop, or browser.
- **A suite of system apps:** Files, Vault, Market, Dashboard, Control Hub, and more, ready the moment you log in.
## Get started
### Linux script requirements
To install Olares on an existing Linux system using the script below, your machine needs:
- **CPU:** At least 4 cores
- **RAM:** At least 8 GB of available memory
- **Storage:** At least 150 GB of available SSD storage; installation will fail on an HDD
- **OS:** Ubuntu 22.04 to 25.04, or Debian 12 or 13
A dedicated GPU is optional and enables local AI acceleration.
### Install on Linux
On your Ubuntu or Debian host, run the following command from an account with `sudo` access:
```bash
curl -fsSL https://olares.sh | bash -
```
This command downloads the official installer from `olares.sh` and runs it with Bash. See the [Linux script installation guide](https://www.olares.com/docs/manual/get-started/install-linux-script) for the full setup steps and troubleshooting.
For a fresh installation on an Intel or AMD x86-64 machine, use the [ISO image](https://www.olares.com/docs/manual/get-started/install-linux-iso). For a containerized installation on Linux, see the [Docker Compose guide](https://www.olares.com/docs/manual/get-started/install-linux-docker).
Once setup is complete, open your Olares desktop in a browser at its address, for example, `https://desktop.marvin123.olares.com`.
### Try your first AI task
Follow the [AI onboarding guide](https://www.olares.com/docs/one/olares-onboarding) to set up Router, Lares, and a local model, then start your first conversation. Try asking Lares: "Check this device's configuration."
## Key use cases
- **Use a personal AI agent.** Delegate research, file management, and routine automation to [Lares](https://www.olares.com/docs/use-cases/lares) through plain language, or use your preferred agent for coding and other tasks.
- **Run generative AI locally.** Chat with open models, generate images and video, and connect local models to other apps, all from your own hardware.
- **Manage smart home devices and media.** Connect home automation tools and stream your personal music and video libraries.
- **Build and host agentic apps.** Develop, test, and run apps and workflows in isolated environments on Olares.
- **Process audio locally.** Transcribe meetings, translate recordings, and generate speech without uploading audio to a third-party service.
- **Create a self-hosted workspace.** Give your family or team tools for documents, automation, project management, and communication.
- **Manage your personal data.** Store, sync, back up, and access files, photos, and documents across your devices.
## System architecture
Just as public clouds offer IaaS, PaaS, and SaaS layers, Olares provides open-source alternatives to each of these layers.
For a detailed description of each component, refer to [Olares architecture](https://www.olares.com/docs/developer/concepts/system-architecture).
> 🔍 **How is Olares different from traditional NAS?**
>
> Olares focuses on building an all-in-one self-hosted personal cloud experience. Its core features and target users differ significantly from Network Attached Storage (NAS) systems, which primarily focus on network storage. For more details, see [Compare Olares and NAS](https://www.olares.com/blog/compare-olares-and-nas/).
## Project navigation
The main directories in the Olares repository:
```
Olares/
├── apps/ # Built-in Olares system applications
├── cli/ # olares-cli: agent-native CLI with Agent Skills to install and operate Olares
├── daemon/ # olaresd, the system daemon process
├── docs/ # Project documentation
├── framework/ # Olares system services
├── infrastructure/ # Computing, storage, networking, and GPU components
├── platform/ # Cloud-native components like databases and message queues
└── vendor/ # Hardware-specific code for Olares devices
```
## Contributing
Olares welcomes contributions across the project. Choose the path that best matches what you want to improve:
- **Core development:** Browse [open issues](https://github.com/beclab/Olares/issues), or open an issue to discuss your proposal before starting a substantial change.
- **Documentation:** Improve the guides in [`docs/`](./docs). See the [documentation contributor guide](./docs/README.md) and [content and style guide](https://github.com/beclab/Olares/wiki/General-style-reference).
- **App distribution:** [Package and submit](https://www.olares.com/docs/developer/develop/distribute-index) an app to Olares Market.
- **Bug reports and feature requests:** Open a [GitHub issue](https://github.com/beclab/Olares/issues) with enough context for the team to investigate or evaluate it.
- **Security reporting:** Follow our [security policy](./SECURITY.md). Please do not report vulnerabilities through public issues, discussions, or community channels.
## Learn more
- **[Installation guide](https://www.olares.com/docs/manual/get-started/install-olares):** Choose an installation method and activate Olares.
- **[Use cases](https://www.olares.com/docs/use-cases/):** Explore local AI, media, productivity, and self-hosted workflows.
- **[CLI guide](https://www.olares.com/docs/developer/cli-overview):** Install, manage, and diagnose Olares from the command line.
- **[Agent Skills](https://www.olares.com/docs/developer/cli-agent-skills):** Let AI agents operate Olares through `olares-cli`.
## Community
- **[Discord](https://discord.gg/olares):** Get community support and discuss deployments and agent workflows.
- **[Olares Forum](https://www.olares.com/forum/):** Share product feedback and join longer-form discussions.
- Follow Olares on [X](https://x.com/Olares_OS) and [YouTube](https://www.youtube.com/@OlaresOS).
## Acknowledgements
The Olares project has incorporated numerous third-party open-source projects, including: [Kubernetes](https://kubernetes.io/), [Kubesphere](https://github.com/kubesphere/kubesphere), [Padloc](https://padloc.app/), [K3S](https://k3s.io/), [JuiceFS](https://github.com/juicedata/juicefs), [MinIO](https://github.com/minio/minio), [Envoy](https://github.com/envoyproxy/envoy), [Authelia](https://github.com/authelia/authelia), [Infisical](https://github.com/Infisical/infisical), [Dify](https://github.com/langgenius/dify), [Seafile](https://github.com/haiwen/seafile), [HeadScale](https://headscale.net/), [Tailscale](https://tailscale.com/), [Redis Operator](https://github.com/spotahome/redis-operator), [Nitro](https://nitro.jan.ai/), [RSSHub](http://rsshub.app/), [predixy](https://github.com/joyieldInc/predixy), [nvshare](https://github.com/grgalex/nvshare), [LangChain](https://www.langchain.com/), [Quasar](https://quasar.dev/), [TrustWallet](https://trustwallet.com/), [Restic](https://restic.net/), [ZincSearch](https://zincsearch-docs.zinc.dev/), [filebrowser](https://filebrowser.org/), [lego](https://go-acme.github.io/lego/), [Velero](https://velero.io/), [s3rver](https://github.com/jamhall/s3rver), [Citusdata](https://www.citusdata.com/).
---
### README (`docs/README.md`)
# Olares documentation
Welcome to the source repository for the official Olares documentation!
This directory includes the source files for the Olares documentation website, instructions for setting up the project locally, Markdown references, and style guides to ensure consistency and quality across all documentation.
## Quick links
* **Published documentation site**: https://docs.olares.com
* **Olares official website**: https://www.olares.com
* **Olares project on GitHub**: https://github.com/beclab/Olares
## Getting started with Olares documentation
We welcome community contributions! Follow these steps to preview, develop, and build the documentation locally.
### Install dependencies
First, ensure you have [Node.js](https://nodejs.org/) installed (LTS version recommended). Then, run the following command in the project's root directory to install the required dependencies:
```bash
npm install
````
### Start the development server
Start the local development server with hot-reloading. This allows you to see your changes live in the browser as you edit the source files.
```bash
npm run dev
```
Once running, open your browser and navigate to `http://localhost:5173/` to see the local preview.
### Build the site locally
To generate a production-ready build for final review or debugging, run:
```bash
npm run build
```
This command will build the static site into the `dist` directory.
### Document share previews
Production builds automatically generate a separate share image for each page.
Images are included in `.vitepress/dist/og/` and deployed with the site.
See [share image configuration](.vitepress/og/README.md) for the template,
font licenses, preview URLs, and optional `ogTitle` frontmatter.
## Versioning and branching strategy
To manage documentation for different product versions effectively, we use the following branching strategy:
* **`main` branch**:
This branch contains the latest documentation for the **next, in-development version** of Olares. All documentation for new features should be submitted here.
* **`release-{version}` branch**:
These branches hold the documentation for **recent, stable versions**. For example, the `release-1.11` branch corresponds to the `Olares 1.11` documentation. Fixes or clarifications for a specific stable version should be submitted to its corresponding release branch.
Creating a PR to a corresponding branch will automatically trigger the documentation build for that version.
## Style guide
To ensure clarity, accuracy, and a consistent tone, please read our **[Content and style guide](https://github.com/beclab/Olares/wiki/General-style-reference)** before contributing.
---
### Index (`docs/index.md`)
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
# /docs/ 301-redirects to /manual/overview (see theme/redirects.ts), so keep this
# redirecting URL out of the sitemap and search index.
noindex: true
hero:
name: "Olares"
text: "An open-source personal cloud OS"
tagline: "Let people own their data again"
actions:
- theme: brand
text: What is Olares?
link: /manual/overview
- theme: alt
text: Star us on GitHub
link: https://github.com/beclab/olares
features:
- icon: 🚀
title: Get started with Olares
details: Install Olares on your hardware and begin taking control of your data in minutes.
link: /manual/get-started/
- icon: ⚙️
title: Master your system
details: Dive into Olares' system apps to configure, personalize, and access your personal cloud.
link: /manual/olares/
- icon: 📱
title: Hands-on with LarePass
details: Securely access and manage your Olares from LarePass, the cross-platform client for Olares.
link: /manual/larepass/
- icon: 💡
title: Explore Use Cases
details: Discover various ways you can leverage Olares in daily life with real-life tutorials and use cases.
link: /use-cases/
---
---
### Developer Cli Overview (`docs/developer/cli-overview.md`)
---
outline: [2, 3]
description: Use olares-cli to maintain Olares OS, manage a running Olares, and let AI agents perform tasks through bundled Agent Skills.
head:
- - meta
- name: keywords
content: Olares, olares-cli, CLI overview, cluster management, Agent Skills, AI agent integration
---
# Olares CLI overview
`olares-cli` is the official command-line tool for Olares. Use it to install, upgrade, and maintain Olares OS, or manage files, apps, settings, and system status on a running Olares. Its bundled Agent Skills let AI agents turn natural-language requests into CLI commands.
Install the standalone CLI on macOS, Windows, or Linux to let an AI agent manage a running Olares from another computer. Olares OS also includes a host CLI for system maintenance.
## Get started
### Manage a running Olares with an AI agent
Install Olares CLI and its Agent Skills on the computer where your AI agent runs, then log in with your Olares ID. The agent can translate natural-language requests into commands for managing files, apps, settings, models, and system status. Follow [Use Olares CLI with AI agents](./cli-install.md) to complete setup and run your first task in one flow.
AI agent apps that run on Olares, such as [Lares](../use-cases/lares.md), [Hermes Agent](../use-cases/hermes.md), and [OpenClaw](../use-cases/openclaw.md), already include Olares CLI and the Agent Skills. Follow your app's guide to get started.
### Maintain Olares OS
On the Linux host running Olares OS, use the bundled CLI at `/usr/local/bin/olares-cli` to install or upgrade Olares, manage nodes and hardware, collect logs, and diagnose system problems. These operations use the host's root access and kubeconfig, so they do not require an Olares ID login.
Start with [Common Olares CLI commands](./install/cli/olares-cli.md) for status checks, log collection, and troubleshooting. See [Cluster management](./install/index.md) for installation architecture, environment variables, and versioning.
## Learn more
- [Olares CLI Agent Skills](./cli-agent-skills.md): browse the skill catalog and learn how the bundles are distributed and kept in sync.
- [Use Any AI Agent to Manage Olares, with Olares CLI](https://www.olares.com/blog/olares-cli-ai-agents-explained/): understand how Olares, the CLI, Agent Skills, and AI agents work together.
---
### Manual Feature Overview (`docs/manual/feature-overview.md`)
---
noindex: true
description: Compare Olares with Synology, TrueNAS, CasaOS, and Unraid across apps, networking, storage, and multi-user features to see how this personal cloud OS differs.
---
# Feature comparison
:::tip Legend
- 🚀: **Auto**, indicates that the system completes the task automatically.
- ✅: **Yes**, indicates that users without a developer background can complete the setup through the product's UI prompts.
- 🛠️: **Manual Configuration**, indicates that even users with an engineering background need to refer to tutorials to complete the setup.
- ✖️: **No**, indicates that the feature is not supported.
:::
| | Olares | Synology | TrueNAS | CasaOS | Unraid |
|---------------------------|------------------------------------------------------------------------------------------------------------|---------------------------------------------|---------------------------------------------|-------------------------|-----------------------------------------------|
| Multi-node | ✅ | ✖️ | ✅ | ✖️ | ✖️ |
| Build-in apps | ✅ (Rich desktop apps) | ✅ (Rich desktop apps) | ✖️ (CLI) | ✅ (Simple desktop apps) | ✅ (Dashboard) |
| Free domain name | ✅ | ✅ | ✖️ | ✖️ | ✖️ |
| Auto SSL certificate | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ |
| Reverse proxy | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ |
| VPN management | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ |
| Graded app entrance | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ |
| Multi-user management | ✅ User management 🚀 Resource isolation | ✅ User management 🛠️ Resource isolation | ✅ User management 🛠️ Resource isolation | ✖️ | ✅ User management 🛠️ Resource isolation |
| Single login for all apps | 🚀 | ✖️ | ✖️ | ✖️ | ✖️ |
| Cross-node storage | 🚀 (Juicefs+ MinIO) | ✖️ | ✖️ | ✖️ | ✖️ |
| Database solution | 🚀 (Built-in cloud-native solution) | 🛠️ | 🛠️ | 🛠️ | 🛠️ |
| Disaster recovery | 🚀 (MinIO's [**Erasure Coding**](https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html)) | ✅ RAID | ✅ RAID | ✅ RAID | ✅ Unraid Storage |
| Backup | ✅ App Data ✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data |
| App sandboxing | ✅ | ✖️ | ✖️ (K8S's namespace) | ✖️ | ✖️ |
| App ecosystem | ✅ (Official + third-party) | ✅ (Majorly official apps) | ✅ (Official + third-party submissions) | ✅ Majorly official apps | ✅ (Community app market) |
| Developer friendly | ✅ IDE ✅ CLI ✅ SDK ✅ Doc | ✅ CLI ✅ SDK ✅ Doc | ✅ CLI ✅ Doc | ✅ CLI ✅ Doc | ✅ Doc |
| Local LLM hosting | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ |
| Local LLM app development | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ |
| Client platforms | ✅ Android ✅ iOS ✅ Windows ✅ Mac ✅ Chrome Plugin | ✅ Android ✅ iOS | ✖️ | ✖️ | ✖️ |
| Client functionality | ✅ (All-in-one client app) | ✅ (14 separate client apps) | ✖️ | ✖️ | ✖️ |
---
### Manual Overview (`docs/manual/overview.md`)
---
description: Documentation for Olares, the open-source personal cloud OS that runs AI agents and LLMs on your own hardware.
aside: false
head:
- - meta
- name: keywords
content: Olares, documentation, personal cloud OS, AI agents, LLMs, self-hosting
---
# Olares documentation
## What is Olares?
Olares is an open-source personal cloud OS you operate in plain language, built to run AI agents and LLMs on hardware you own.
Use this documentation to install and activate Olares, manage apps, files, identity, and access, and extend your setup with the CLI, Agent Skills, and real-world workflows.
## Olares OS, LarePass, and Olares Space
**Olares OS** runs on your device and hosts your apps, files, and AI services. **LarePass** is the client you use to create and protect your Olares ID, activate Olares, and access it securely from your devices. **Olares Space** is the web service for managing your Olares devices and optional cloud-assisted features such as custom domains, backup storage, and billing.
## Set up Olares
Get Olares running, whether you install the OS yourself or use a dedicated device.
---
### One Access Overview (`docs/one/access-overview.md`)
---
outline: [2, 3]
description: Learn how to access the Olares One host terminal for command-line usage via Control Hub, SSH, or direct physical access.
head:
- - meta
- name: keywords
content: Olares One, terminal, Olares CLI, SSH access, direct physical access
---
# Access Olares One terminal
Connecting to the Olares One terminal is required for system tasks such as cluster setup, system configuration, and maintenance.
Choose the method that best fits your current task, network environment, and available tools:
- [Access from Control Hub](access-terminal-control-hub.md): Use the built-in Olares CLI for direct `root` access from the Control Hub application. This is recommended for quick or occasional tasks.
- [Access over the network (SSH)](access-terminal-ssh.md): Use the standard Secure Shell (SSH) protocol to connect from either your local network or a remote network.
- [Access directly on the device](access-physical-console.md): Log in on the device itself using a connected monitor and keyboard. This method is useful when SSH access is unavailable.
---
### One Index (`docs/one/index.md`)
---
description: Set up and manage Olares One, run AI agents and LLMs locally, and operate your personal AI cloud through plain language.
aside: false
head:
- - meta
- name: keywords
content: Olares One, Olares, personal AI cloud, local AI, edge computing, data privacy
---
# Olares One documentation
Olares One combines workstation-grade hardware with Olares OS to give you a personal AI cloud you control. Run AI agents and LLMs locally, and operate your cloud simply by describing what you want in plain language.
This documentation focuses on Olares One-specific workflows, from first boot and natural-language onboarding to device access, system updates, storage and eGPU expansion, recovery, and dual-boot configurations. For general Olares features, applications, and use cases, see [Olares OS](../manual/overview) or [Use cases](../use-cases/).
New to Olares One? Start with [First boot](./first-boot), then learn how to [manage Olares through natural language](./olares-onboarding).
## Your Olares One journey
Follow the path from first boot to everyday use and advanced customization.
---
### Reusables README (`docs/reusables/README.md`)
# Reusables
This directory holds shared content included in multiple docs via ``.
Add new reusable fragments here and wrap each reusable block in a named VS Code region:
```markdown
Reusable content.
```
Use stable, descriptive region names so source line changes do not break references.
- **local-domain.md**: Host mappings setup, URL formats, and troubleshooting for direct LAN access. Used by `manual/get-started/local-access.md`, `manual/best-practices/local-access.md`, and `one/access-olares-via-local-domain.md`.
- **larepass-vpn.md**: LarePass VPN procedure (Download, Enable, Verify connection type) and FAQs linking to the troubleshooting doc. Used by `manual/get-started/local-access.md`, `manual/best-practices/local-access.md`, and `one/access-olares-via-vpn.md`.
- **sync-files.md**: Sync files to local (intro, Create a library, Enable synchronization, Manage synchronization). Used by `manual/larepass/manage-files.md` and `manual/olares/files/sync-files.md`.
- **export-system-logs.md**: Steps to export system logs via Settings > Advanced > Logs. Used by `manual/help/request-technical-support.md`.
- **custom-domain.md**: Custom domain setup procedures (Create DID, Add domain with TXT/NS verification, Create organization, Add user, Join organization). Used by `manual/best-practices/set-custom-domain.md`, `manual/larepass/create-org-account.md`, `manual/space/host-domain.md`, and `manual/space/manage-domain.md`.
- **ai-service-connections.md**: Reusable explanations and steps for connecting AI clients to models or apps. Use `model-connection-overview` and `get-model-connection-details` when connecting a standalone model on Olares. Use `app-endpoint-overview` when connecting another Olares app through its endpoint.
---
### Use Cases Index (`docs/use-cases/index.md`)
---
description: Explore Olares use cases for AI agents, local models, creative tools, productivity, media, virtual machines, and self-hosted apps.
aside: false
head:
- - meta
- name: keywords
content: Olares, use cases, open-source apps, local AI, media server, self-hosting
---
# Use cases
Use cases are end-to-end guides for running popular open-source apps on Olares, from local AI and private media servers to self-hosted workspaces and developer tools. Pick a category or search by keyword to find an application, then open its full step-by-step guide.
:::tip Using an AI agent on your own computer?
You can use your existing agent to help set up apps, deploy models, and troubleshoot Olares. Follow [Use Olares CLI with AI agents](../developer/cli-install.md) to install Olares CLI and Agent Skills on that computer and log in. You can also ask your agent:
```plain
Install Olares CLI and Agent Skills, then help me log in to manage my Olares.
```
Agent apps running on Olares already include Olares CLI and Agent Skills. Follow the app's guide to get started.
:::
---
### Zh Index (`docs/zh/index.md`)
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
# /docs/zh/ 301-redirects to /zh/manual/overview (see theme/redirects.ts), so keep
# this redirecting URL out of the sitemap and search index.
noindex: true
hero:
name: "Olares"
text: "开源个人云操作系统"
tagline: "让数据主权回归个人"
actions:
- theme: brand
text: 什么是 Olares？
link: /zh/manual/overview
- theme: alt
text: 在 GitHub 上关注我们
link: https://github.com/beclab/olares
features:
- icon: 🚀
title: Olares 快速上手
details: 在你的硬件上快速部署 Olares，即刻开始掌控你的数据。
link: /manual/get-started/
- icon: ⚙️
title: 驾驭你的系统
details: 深入了解 Olares 的系统应用，随心配置、个性化和访问你的个人云。
link: /manual/olares/
- icon: 📱
title: 熟悉 LarePass 客户端
details: 通过 LarePass—Olares 的跨平台客户端，安全访问和管理 Olares。
link: /manual/larepass/
- icon: 💡
title: 探索使用场景
details: 通过真实的教程和使用案例，探索 Olares 丰富多样的应用方式。
link: /use-cases/
---
---
### .Vitepress Og README (`docs/.vitepress/og/README.md`)
# Document share images
Every rendered page gets a 1200 × 630 PNG using the approved light design:
a softly shaded gray dot background, the black Olares logo, black title,
gray description, documentation URL, and a 12 px black strip along the bottom.
Text is placed directly on the background, without a separate content panel.
There is no category label. The header, text, and footer have 72 px side margins.
`background.svg` contains the background texture and bottom strip. `logo.svg`
is the original black brand logo. `generate.mjs` controls text layout and export.
`transformHead` registers the image and inserts Open Graph and Twitter metadata.
`buildEnd` writes the PNG files into `.vitepress/dist/og/`, including archived
and noindex pages. Deploy the complete build output as usual. No image service,
browser installation, external font request, or manual image upload is needed.
Images are named using a hash of the page path, title, image description,
language, renderer, background, logo, and font files. Generated files are cached
in `.vitepress/cache/og/` and copied
back into each fresh build. The cache and output are already ignored by Git.
Changes to text or design produce new image URLs. Social platforms may still
cache the page's metadata until they recrawl it.
The production URL defaults to `https://www.olares.com/docs/`. A non-root
`BASE_URL` is preserved, including versioned deployments. For a separately
hosted preview, set `DOCS_SITE_URL` to its full public site URL, including the
base path (for example `https://preview.example.com/docs/`).
The page title comes from VitePress (frontmatter title or the first heading).
For long text, set shorter image-only copy in frontmatter:
```yaml
ogTitle: Install and activate Olares
ogDescription: Choose an installation method and set up Olares on your hardware.
```
Descriptions come from the page's `description`, with the localized site tagline
as a fallback. Optional `ogDescription` overrides the image text only (an empty
string hides it). The full page description remains in Open Graph/Twitter metadata.
Titles use Manrope at weight 650 for Latin text and Noto Sans SC at weight 550
for Chinese text. Chinese pages use 0 px title tracking; English pages use
-0.6 px. Descriptions use the same font families at weight 400.
Titles use the full 1056 px text width, with a 184 px height budget, and wrap
into up to three lines, shrinking from 64 px when necessary. Descriptions use
29 px text in a separate area, at least 36 px below the title, with up to three lines. Overlong
image descriptions end with an ellipsis; neither the title nor description can
overlap the footer. Lines fill the available width naturally rather than being
balanced into a narrower column, matching the selected English and Chinese previews.
An unrenderable or excessively long title fails the build instead of publishing
a broken image. Metadata is inserted during the production build; inspect it
with `npm run build` followed by `npm run preview`, not the development server.
Run focused checks with `npm run test:og`, and validate integration with
`npm run build`.
## Fonts and logo
Manrope and Noto Sans SC are unmodified variable fonts from the Google Fonts
repository. Manrope was downloaded on 2026-10-19; Noto Sans SC on 2026-10-16.
Their complete SIL OFL 1.1 licenses and copyright notices are preserved beside the font files in `fonts/`:
- https://github.com/google/fonts/tree/main/ofl/manrope
- https://github.com/google/fonts/tree/main/ofl/notosanssc
The license allows commercial use and embedding. Keep these license files when
redistributing the fonts. The generated images do not need to use the OFL.
Fonts are build inputs only and are not copied to the deployed website.
The black logo is the original SVG supplied by the Olares brand owner.
---
### Developer Concepts Index (`docs/developer/concepts/index.md`)
---
description: Explore core Olares concepts for developers, including system architecture, identity, application management, networking, and data security.
head:
- - meta
- name: keywords
content: Olares, Olares developer concepts, system architecture, identity, application management, data security
---
# Overview
The Concepts section helps you learn about the parts of the Olares system and obtain a deeper understanding of how Olares works. Read this section as needed to:
- Develop applications for Olares
- Manage system deployments
- Troubleshoot issues
- Optimize system performance
Understand Olares with the following concepts:
- [Architectural components](system-architecture.md)
- [Olares ID](olares-id.md)
- [Account](account.md)
- [Application](application.md)
- [Network](network.md)
- [Data](data.md)
- [Secrets](secrets.md)
---
### Developer Develop App Env Index (`docs/developer/develop/app-env-index.md`)
---
outline: [2, 3]
description: Learn how Olares injects app environment variables through declarative .Values.olaresEnv settings and system-provided .Values runtime values.
head:
- - meta
- name: keywords
content: Olares, app environment variables, .Values.olaresEnv, runtime values, Olares app development
---
# Environment variables overview
Olares apps use app-service to inject runtime context and configuration into the app's `values.yaml`. In Helm templates, you can reference these values via `.Values.*`.
:::info Variables and Helm values
In this document, "variables" mainly refer to Helm values. They are not automatically passed into container environment variables. If you need them inside containers, explicitly map them to `env:` in your templates.
:::
## How variables are injected
Olares injects variables through two channels:
- **Declarative environment variables**: The developer declares variables under `envs` in `OlaresManifest.yaml`. At deployment, app-service resolves and injects the values into `.Values.olaresEnv` in `values.yaml`.
- **System-injected runtime variables**: Injected automatically by Olares at deployment time. No declaration is required, though some values are only available after you declare the relevant dependency, such as middleware.
## Next steps
1. [Declarative environment variables](app-env-vars.md): Field reference for the `envs` schema, including variable mapping and variable references.
2. [System-injected runtime variables](app-sys-injected-variables.md): Full reference for all system-injected runtime variables.
---
### Developer Develop Distribute Index (`docs/developer/develop/distribute-index.md`)
---
outline: [2, 3]
description: Understand how application distribution works in Olares.
head:
- - meta
- name: keywords
content: Olares, distribute Olares applications, app distribution, Olares Market, publish app
---
# Distribute Olares applications
Distributing applications on Olares is based on open standards and automated validation.
If your application is already packaged as an Olares Application Chart (OAC), you can publish it to Olares Market and make it available to users with minimal friction.
This guide walks you through the distribution lifecycle of an Olares application, from understanding how Market indexing works to publishing, maintaining, and promoting your app.
## Before you begin
Before distributing your application, it helps to understand a few core concepts:
- **[Olares Application Chart (OAC)](/developer/develop/package/chart.md)**
The packaging format used to describe an Olares application, including metadata, ownership, versioning, and installation configuration.
- **Application index**
A service that provides application metadata to Olares Market. Olares includes a default public index, and developers can deploy their own.
- **Terminus-Gitbot**
The automated validation system that checks application submissions and enforces distribution rules.
- **Owners file (`owners`)**
A file in the OAC root directory used to validate ownership and permissions. The file has no extension.
```text
owners:
-
-
-
```
- **Control files**
Special empty files in the OAC root directory that control distribution status:
- `.suspend`: suspend distribution
- `.remove`: remove an app from the Market
For details, see [Manage the app lifecycle](/developer/develop/manage-apps.md#control-files).
## Ownership and collaboration
To collaborate as a team:
- Add all maintainers to the owners file (recommended). Each listed owner can independently fork the repo and submit changes for that app.
- Add teammates as collaborators to your forked repository so they can push commits to your PR branch.
## App distribution workflow
### 1. Prepare your app package
Before an app can be distributed, it must be packaged as an **Olares Application Chart (OAC)**.
At this stage, developers typically:
- Develop and test the app on an Olares host.
- Verify installation and upgrade behavior.
- Finalize chart metadata and structure.
For details, see [Olares Application Chart (OAC)](/developer/develop/package/chart.md).
### 2. Submit the app to the default index
Olares Market indexes applications from Git repositories.
To publish an app to the default public index, developers submit their OAC by opening a PR to the official repository.
During submission:
- The PR title declares the action type.
- Terminus-Gitbot validates file scope, ownership, and version rules.
- Valid PRs are merged automatically without manual review.
For details, see [Submit applications](/developer/develop/submit-apps.md).
### 3. Automated validation and indexing
After a PR is submitted, Terminus-Gitbot performs automated checks to ensure the submission follows distribution rules.
If all checks pass, the PR is merged automatically.
After a short delay, the application becomes visible in Olares Market.
### 4. Manage the application lifecycle
After an application is published, developers continue to manage its lifecycle through Pull Requests.
Lifecycle actions include:
- Releasing new versions.
- Temporarily suspending distribution.
- Permanently removing an application from the Market.
These actions are controlled using PR types and special control files in the OAC.
For details, see [Manage the app lifecycle](/developer/develop/manage-apps.md).
### 5. Optimize your Market listing
Once published, you can improve how your app is presented in Olares Market by adding icons, screenshots, and featured images.
For details, see [Promote your apps](/developer/develop/promote-apps.md).
---
### Developer Develop Index (`docs/developer/develop/index.md`)
---
description: Developing applications on Olares leverages standard web technologies and containerization.
head:
- - meta
- name: keywords
content: Olares, develop Olares applications, app development, web technologies, containerization, Olares developer guide
---
# Develop Olares applications
Developing applications on Olares leverages standard web technologies and containerization. If you are familiar with building web applications or Docker containers, you already have the skills needed to build for Olares.
This guide takes you through the complete lifecycle of an Olares application, from planning the package structure to publishing on the Market.
## Before you begin
Before getting started, it's helpful to review some concepts:
- [Application](../concepts/application.md)
- [Network](../concepts/network.md)
## Step 1: Package your application
To publish your application to the Olares Market, you must structure it according to the Olares Application Chart (OAC) specification. This format extends Helm Charts to support Olares-specific features like permission management and sandboxing.
* **[Understand the Olares Application Chart](./package/chart.md)**: Understand the file structure and requirements of an application package.
* **[Understand `OlaresManifest.yaml`](./package/manifest.md)**: A comprehensive guide to the `OlaresManifest.yaml` file, which defines your app's metadata, permissions, and system integration points.
* **[Understand Helm extensions](./package/extension.md)**: Learn about the custom fields and capabilities Olares adds to standard Helm deployments.
## Step 2: Submit your application
Once your application is built and packaged, the final step is to share it with the Olares community.
* **[Submit to Market](/developer/develop/distribute-index.md)**: Learn how to submit your application to the Olares Market for review and distribution.
---
### Developer Develop Mw Overview (`docs/developer/develop/mw-overview.md`)
---
outline: [2, 3]
description: Learn what middleware is in Olares and navigate to access and integration guides for each supported service.
head:
- - meta
- name: keywords
content: Olares, Middleware in Olares, Olares middleware, middleware services, app integration, database middleware
---
# Middleware in Olares
Middleware refers to infrastructure services that sit between your application and the system, providing data storage, messaging, and other common capabilities.
Our middleware documentation is organized into two types of guides:
- **Access and manage data**: Connect to a running service to inspect data and troubleshoot issues.
- **App integrate**: Configure your app to use a middleware service in Olares using `OlaresManifest.yaml`.
## Document types
### Access and manage data
Access and manage data guides explain how to connect to a running middleware service for administration.
Use these guides when you want to:
- Inspect stored data or indexes.
- Run queries or commands.
- Debug application behavior.
- Verify service status.
The access method (e.g., CLI, Dashboard, or Bytebase) depends on the service.
### App integration
App integration guides explain how to connect your application to a middleware service.
Use these guides when you want your application to:
- Declare dependencies in `OlaresManifest.yaml`.
- Request service resources.
- Read system-injected connection values in your application.
Integration is declarative and handled by Olares at deployment time.
## Supported services
### Databases and caching
| Service | Access and manage data | App integration |
| --- | --- | --- |
| Elasticsearch | [Access](./mw-view-es-data.md) | [Integrate](./mw-integrate-with-es.md) |
| MariaDB | [Access](./mw-view-mariadb-data.md) | [Integrate](./mw-integrate-with-mariadb.md) |
| MongoDB | [Access](./mw-view-mongodb-data.md) | [Integrate](./mw-integrate-with-mongodb.md) |
| MySQL | [Access](./mw-view-mysql-data.md) | [Integrate](./mw-integrate-with-mysql.md) |
| PostgreSQL | [Access](./mw-view-pg-data.md) | [Integrate](./mw-integrate-with-pg.md) |
| Redis | [Access](./mw-view-redis-data.md) | [Integrate](./mw-integrate-with-redis.md) |
### Messaging and streaming
| Service | Access and manage data | App integration |
| --- | --- | --- |
| RabbitMQ | [Access](./mw-view-rabbitmq-data.md) | [Integrate](./mw-integrate-with-rabbitmq.md) |
| NATS | [Access](./mw-view-nats-data.md) | — |
### Storage and observability
| Service | Access and manage data | App integration |
| --- | --- | --- |
| MinIO | [Access](./mw-view-minio-data.md) | [Integrate](./mw-integrate-with-minio.md) |
| Grafana | [Access](./mw-view-grafana-data.md) | — |
| OpenTelemetry | [Access](./mw-view-otel-data.md) | — |
---
### Developer Install Index (`docs/developer/install/index.md`)
---
description: Manage Olares clusters with olares-cli. Learn installation paths, environment variables, versioning, and host maintenance.
head:
- - meta
- name: keywords
content: Olares, cluster management, olares-cli, installation guide, Olares Home, versioning, host maintenance
---
# Cluster management
This section covers everything you do with `olares-cli` on the Olares host itself: install Olares on a fresh machine, understand its file layout and environment variables, follow versioning rules, and maintain the host.
- [Installation architecture](installation-overview.md): how Olares is installed from the perspective of overall architecture and core components.
- [Installation process](installation-process.md): the install pipeline in detail, broken down into four key phases.
- [Olares Home](olares-home.md): the structure of the base installation directory.
- [Environment variables](environment-variables.md): the variables you can set to customize the install.
- [Olares versioning](versioning.md): versioning rules, release types, branch management practices, and upgrade guidelines.
- [Common Olares CLI commands](cli/olares-cli.md): commands you run in the host terminal for status checks, diagnostics, password recovery, and storage maintenance.
- [Olares CLI overview](../cli-overview.md): choose between maintaining Olares OS on its host and managing a running Olares from another computer.
To manage a running Olares through an AI agent on another computer, see [Use Olares CLI with AI agents](../cli-install.md).
---
### Developer Install Installation Overview (`docs/developer/install/installation-overview.md`)
---
outline: [2, 3]
description: Understand Olares installation architecture across the native system layer, Kubernetes orchestration, and containerized services.
head:
- - meta
- name: keywords
content: Olares, installation architecture, K3s, Kubernetes, containerd, olaresd, JuiceFS, native layer
---
# Olares installation architecture
This document provides a high-level overview of the Olares installation process, focusing on its overall architecture and core components. It is intended for system administrators and developers who need a foundational understanding of how Olares operates and is installed.
## Three layers of Olares installation
The Olares installation is structured into three key layers:
- **Native layer**: Manages Linux system configurations and installs essential environment dependencies.
- **Container orchestration layer**: Deploys the Kubernetes cluster to enable automated service management and scaling.
- **Containerization layer**: Launches containerized core system services and user applications, providing the final runtime environment.
The installation process is managed by the `olares-cli` tool. This command-line tool orchestrates the installation, configuration, and lifecycle management of all components.
::: tip
To understand the detailed installation process phase-by-phase, refer to [Olares installation breakdown](installation-process.md).
:::
## Native layer
The Olares installation process begins at the native layer, ensuring that the underlying Linux environment supports distributed storage, container runtimes, and Kubernetes cluster management.
This layer's configuration includes core Linux system settings, file system initialization, container runtime installation, and deployment of critical system services.
### Environment configuration
The installation first configures the basic Linux installation environment. This includes setting up Domain Name System (DNS), Secure Shell (SSH), and Network Time Protocol (NTP) services to ensure time synchronization and remote management capabilities.
Additionally, necessary dependencies such as the GNU Compiler Collection (GCC) and Network Tools (net-tools) are installed to ensure a robust runtime environment.
### File system configuration
The root file system (rootfs) is used to store and access system core components and user data. Olares supports the following two file systems based on deployment needs:
- **LocalFS** (default): Uses the local Linux disk for storage. It is ideal for single-node deployments that require high data throughput without the need for network sharing.
- **JuiceFS**: Provides a distributed file system for multi-node cluster. File data are stored in locally installed MinIO instances or remote storage buckets such as Amazon S3. This setup allows different storage nodes to share a unified storage view.
:::tip Enable JuiceFS
JuiceFS and MinIO are not installed by default. To enable them, set the necessary [environment variables](environment-variables.md#juicefs) or use `olares-cli` with JuiceFS-specific flags.
:::
### Container runtime: containerd
Olares uses containerd, a lightweight container runtime, for containerized deployments. Its features include:
- **Container image management**:
- Downloads packaged container images from the Content Delivery Network (CDN)
- Imports them into containerd during the "prepare" phase
- Starts the images as container processes during the "install" phase
- **Container lifecycle management**: Starts, stops, restarts, and monitors containerized application services.
::: tip Compatibility issue
If containerd is already installed on your machine (for example, as part of Docker), it may cause compatibility issues with the containerd used by Olares. Please uninstall the existing containerd before installing Olares.
:::
### System daemon: olaresd
olaresd is the system daemon that runs in the background, providing essential management functionalities such as:
- **Automated configuration updates**: Automatically adjusts configurations when system changes (e.g. IP changes) are detected.
- **Remote system management**: Executes remote system operations, such as Olares installation and activation, based on requests issued from the LarePass client or `olares-cli`.
### CUDA support
To enable GPU acceleration for local AI models and applications, Olares supports automatic installation of the CUDA toolkit and drivers through `olares-cli`.
## Container orchestration layer
The container orchestration layer integrates system components into an efficient runtime environment using Kubernetes.
### Roles of Kubernetes
Kubernetes serves as the backbone of the container orchestration layer, providing automated deployment, operation, scaling, and management of multi-component services.
Compared to tools like Docker Compose or Docker Swarm, Kubernetes offers:
- High scalability and production-grade reliability.
- Robust community support and a rich ecosystem for integrating applications via Helm Charts, Operators, and Custom Resource Definitions (CRDs).
### Kubernetes options in Olares
Olares supports the following Kubernetes setups:
- **K3s** (default): A lightweight Kubernetes distribution optimized for resource efficiency on local hardware.
- **Kubernetes**: The full-featured Kubernetes distribution for advanced or custom deployments.
- **minikube** (macOS only): A tool that sets up a single-node Kubernetes cluster, ensuring consistent features and user experience.
## Containerization layer
The containerization layer is where Olares' components and applications come together to provide the system's full functionality. All Olares components and user applications run within containers, with the full lifecycle managed via Kubernetes. This ensures that the system remains efficient, stable, and scalable.
Once Olares is installed and activated, you can view the running containers through a graphical user interface provided by the Control Hub app:
{width=90%}
## Learn more
- [Olares installation breakdown](installation-process.md)
- [Olares Home](olares-home.md)
- [Olares CLI](../cli-overview.md)
- [Olares environment variables](environment-variables.md)
---
### Manual Get Started Index (`docs/manual/get-started/index.md`)
---
description: Choose your path to begin using Olares for personal or team use.
head:
- - meta
- name: keywords
content: Olares, get started, first time, join Olares, use cases, setup guide
---
# Get started
Welcome to Olares! This guide will help you quickly set up and start using Olares on your preferred platform.
---
### Manual Help Index (`docs/manual/help/index.md`)
---
outline: [2, 3]
description: Find Olares troubleshooting guides by symptom and check current known issues.
---
# Help and troubleshooting
Use this section when Olares does not behave as expected. Start with the symptom-based troubleshooting index, or check whether a recent release has a documented issue.
## Find the right help
| What you need | Start here |
|---|---|
| Match an error or unexpected behavior to a solution | [Troubleshoot Olares](./troubleshooting-guide.md) |
| Check a release-specific problem and its workaround | [Known issues](./known-issues.md) |
## Search the docs
Use the search box at the top of the page. Search for the shortest exact phrase that describes the symptom, such as an error message, product name, or action:
- `Authentication failed, disk space is full`
- `LarePass VPN`
- `app status`
- `disk space is full`
If the first search is too broad, combine the product and symptom, for example `Market missing apps` or `Ollama disk space`.
---
### Manual Larepass Index (`docs/manual/larepass/index.md`)
---
description: Download LarePass for mobile, desktop, or Chrome, change its language, and find account setup guides.
outline: [2, 3]
head:
- - meta
- name: keywords
content: Olares, LarePass, client, browser extension, Chrome, iOS, Android, macOS, Windows, Linux, download
---
# Download LarePass
LarePass is the official client for creating and managing your Olares ID, activating Olares, and accessing Olares from mobile and desktop devices. Download the client for your device, then follow the task-specific account guides below.
## Choose your platform
### iOS
Visit the [App Store product page](https://apps.apple.com/us/app/larepass/id6448082605) to download LarePass.
### Android
Visit the [Google Play product page](https://play.google.com/store/apps/details?id=com.terminus.termipass), or download the latest APK directly from the [LarePass website](https://www.olares.com/larepass).
### macOS and Windows
Download the latest desktop client from the [LarePass website](https://www.olares.com/larepass).
### Linux
:::info System requirements
- **Architecture**: The Linux package is available for x86_64 (amd64) systems only.
- **Environment**: A graphical desktop environment is required.
:::
Download the latest Linux desktop client from the [LarePass website](https://www.olares.com/larepass).
### Chrome browser extension
Download the ZIP package from the [LarePass website](https://www.olares.com/larepass). The extension must be installed manually in Chrome. See [Install the LarePass browser extension](../install-larepass-browser-extension.md) for instructions.
## Change the language
LarePass is available in English, Simplified Chinese, German, Spanish, Italian, French, and Japanese. Changing the language affects only LarePass on that device. It does not change the language of your Olares system.
- **Mobile**: Go to **Settings** > **General** > **Language**, then select a language.
- **Desktop**: Go to **Settings** > **Language**, then select a language.
The change applies immediately.
## Set up your account
- On mobile devices, you can [create an Olares ID](../get-started/create-olares-id.md) directly in LarePass. To use a custom domain, see [Create an Olares ID with a custom domain](create-org-account.md).
- On the desktop client, [import an existing account](manage-accounts.md#import-an-account).
- In the Chrome browser extension, [import an existing account](manage-accounts.md#chrome-extension).
On the desktop client, you can also [save remote resources directly to Olares](save-resources-to-olares.md).
---
### Manual Olares Index (`docs/manual/olares/index.md`)
---
description: Explore Olares system apps with guides to Desktop, Market, Files, Vault, Wise, Profile, Control Hub, and team collaboration.
aside: false
head:
- - meta
- name: keywords
content: Olares, system applications, Desktop, Market, Files, Vault, Settings, Control Hub, Dashboard
---
# Olares system applications
Olares system applications are a core part of the Olares ecosystem. Pre-installed on your device, they provide the essential tools for managing files, applications, security, and settings from a single place.
## Explore the apps
---
### Zh Reusables README (`docs/zh/reusables/README.md`)
# Reusables（可复用片段）
本目录存放通过 `` 在多个文档中引用的共享内容。
新增可复用片段时，请使用命名 VS Code region 包裹：
```markdown
可复用内容。
```
region 名称应稳定且具备描述性，避免源文件行号变化后影响引用。
- **local-domain.md**：局域网直连、hosts 映射、地址格式和故障排除。被 `manual/get-started/local-access.md`、`manual/best-practices/local-access.md` 和 `one/access-olares-via-local-domain.md` 引用。
- **larepass-vpn.md**：LarePass 专用网络步骤（下载、启用、确认连接类型）及常见问题（链接至故障排查文档）。被 `manual/get-started/local-access.md`、`manual/best-practices/local-access.md` 和 `one/access-olares-via-vpn.md` 引用。
- **sync-files.md**：同步文件至本地（引言与提示、创建库、开启同步、管理同步）。被 `manual/larepass/manage-files.md`、`manual/olares/files/sync-files.md` 引用。
- **export-system-logs.md**：通过设置 > 高级 > 日志导出系统日志的步骤。被 `manual/help/request-technical-support.md` 引用。
- **custom-domain.md**：自定义域名设置流程（创建 DID、添加域名并验证 TXT/NS、创建组织、添加用户、加入组织）。被 `manual/best-practices/set-custom-domain.md`、`manual/larepass/create-org-account.md`、`manual/space/host-domain.md`、`manual/space/manage-domain.md` 引用。
- **ai-service-connections.md**：AI 客户端连接模型或应用时可复用的说明和步骤。连接 Olares 上的独立模型时使用 `model-connection-overview` 和 `get-model-connection-details`。通过端点连接另一个 Olares 应用时使用 `app-endpoint-overview`。
---
### Zh Use Cases Index (`docs/zh/use-cases/index.md`)
---
description: 了解 Olares 在 AI 流程、创意工具和自托管应用中的实际用例，充分释放 Olares 的潜力。
aside: false
head:
- - meta
- name: keywords
content: Olares, 应用示例, 使用案例, 本地 AI, 自托管应用, 媒体服务器, 开发者工具
---
# 应用示例
应用示例是 Olares 上热门开源应用的端到端指南，涵盖本地 AI、私人媒体服务器、自托管工作空间和开发者工具。选择一个分类或通过关键词搜索，然后打开完整指南。
:::tip 已在自己的电脑上使用 AI Agent？
你可以让现有的 Agent 帮你配置应用、部署模型和排查 Olares 问题。按照[通过 AI Agent 使用 Olares CLI](../developer/cli-install.md)，在这台电脑上安装 Olares CLI 和 Agent Skills 并登录。也可以直接告诉 Agent：
```plain
安装 Olares CLI 和 Agent Skills，然后帮我登录，以便管理我的 Olares。
```
运行在 Olares 上的 Agent 应用已经内置 Olares CLI 和 Agent Skills，请按照所用应用的指南开始使用。
:::
---
### Framework Kube State Metrics Docs README (`framework/kube-state-metrics/docs/README.md`)
# Documentation
This documentation is intended to be a complete reflection of the current state of the exposed metrics of kube-state-metrics.
Any contribution to improving this documentation or adding sample usages will be appreciated.
## Table of Contents
- [Metrics Stages](#metrics-stages)
- [Exposed Metrics](#exposed-metrics)
- [Join Metrics](#join-metrics)
- [CLI arguments](#cli-arguments)
## Metrics Stages
Stages about metrics are grouped into three categories：
| Stage | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| EXPERIMENTAL | Metrics which normally correspond to the Kubernetes API object alpha status or spec fields and can be changed at any time. |
| STABLE | Metrics which should have very few backwards-incompatible changes outside of major version updates. |
| DEPRECATED | Metrics which will be removed once the deprecation timeline is met. |
## Exposed Metrics
Per group of metrics there is one file for each metrics. See each file for specific documentation about the exposed metrics:
- [CertificateSigningRequest Metrics](certificatesigningrequest-metrics.md)
- [ConfigMap Metrics](configmap-metrics.md)
- [CronJob Metrics](cronjob-metrics.md)
- [DaemonSet Metrics](daemonset-metrics.md)
- [Deployment Metrics](deployment-metrics.md)
- [Endpoint Metrics](endpoint-metrics.md)
- [Horizontal Pod Autoscaler Metrics](horizontalpodautoscaler-metrics.md)
- [Ingress Metrics](ingress-metrics.md)
- [Job Metrics](job-metrics.md)
- [Lease Metrics](lease-metrics.md)
- [LimitRange Metrics](limitrange-metrics.md)
- [MutatingWebhookConfiguration Metrics](mutatingwebhookconfiguration-metrics.md)
- [Namespace Metrics](namespace-metrics.md)
- [NetworkPolicy Metrics](networkpolicy-metrics.md)
- [Node Metrics](node-metrics.md)
- [PersistentVolume Metrics](persistentvolume-metrics.md)
- [PersistentVolumeClaim Metrics](persistentvolumeclaim-metrics.md)
- [Pod Disruption Budget Metrics](poddisruptionbudget-metrics.md)
- [Pod Metrics](pod-metrics.md)
- [ReplicaSet Metrics](replicaset-metrics.md)
- [ReplicationController Metrics](replicationcontroller-metrics.md)
- [ResourceQuota Metrics](resourcequota-metrics.md)
- [Secret Metrics](secret-metrics.md)
- [Service Metrics](service-metrics.md)
- [StatefulSet Metrics](statefulset-metrics.md)
- [StorageClass Metrics](storageclass-metrics.md)
- [ValidatingWebhookConfiguration Metrics](validatingwebhookconfiguration-metrics.md)
- [VerticalPodAutoscaler Metrics](verticalpodautoscaler-metrics.md)
- [VolumeAttachment Metrics](volumeattachment-metrics.md)
## Join Metrics
When an additional, not provided by default label is needed, a [Prometheus matching operator](https://prometheus.io/docs/prometheus/latest/querying/operators/#vector-matching)
can be used to extend single metrics output.
This example adds `label_release` to the set of default labels of the `kube_pod_status_ready` metric
and allows you select or group the metrics by Helm release label:
```
kube_pod_status_ready * on (namespace, pod) group_left(label_release) kube_pod_labels
```
Another useful example would be to query the memory usage of pods by its `phase`, such as `Running`:
```
sum(kube_pod_container_resource_requests{resource="memory"}) by (namespace, pod, node)
* on (namespace, pod) group_left() (sum(kube_pod_status_phase{phase="Running"}) by (pod, namespace) == 1)
```
## CLI Arguments
Additionally, options for `kube-state-metrics` can be passed when executing as a CLI, or in a kubernetes / openshift environment. More information can be found here: [CLI Arguments](cli-arguments.md)
---
### Developer Develop Submit Index (`docs/developer/develop/submit/index.md`)
---
noindex: true
outline: [2, 3]
description: Understand how application distribution works in Olares.
---
# Submit an Olares application
Distributing applications on Olares is based on open standards and automated validation.
If your application is already packaged as an Olares Application Chart (OAC), you can publish it to Olares Market and make it available to users with minimal friction.
This guide walks you through the distribution lifecycle of an Olares application, from understanding how Market indexing works to publishing, maintaining, and promoting your app.
## Before you begin
Before distributing your application, it helps to understand a few core concepts:
- **[Olares Application Chart (OAC)](/developer/develop/package/chart.md)**
The packaging format used to describe an Olares application, including metadata, ownership, versioning, and installation configuration.
- **Application index**
A service that provides application metadata to Olares Market. Olares includes a default public index, and developers can deploy their own.
- **Terminus-Gitbot**
The automated validation system that checks application submissions and enforces distribution rules.
## App distribution workflow
### 1. Prepare your app package
Before an app can be distributed, it must be packaged as an **Olares Application Chart (OAC)**.
At this stage, developers typically:
- Develop and test the app on an Olares host.
- Verify installation and upgrade behavior.
- Finalize chart metadata and structure.
For details on packaging and chart structure, see:
- [Olares Application Chart (OAC)](/developer/develop/package/chart.md)
### 2. Submit the app to the default index
Olares Market indexes applications from Git repositories.
To publish an app to the default public index, developers submit their OAC by opening a Pull Request (PR) to the official repository.
During submission:
- The PR title declares the action type.
- GitBot validates file scope, ownership, and version rules.
- Valid PRs are merged automatically without manual review.
### 3. Automated validation and indexing
After a PR is submitted, **Terminus-Gitbot** performs automated checks to ensure the submission follows distribution rules.
If all checks pass, the PR is merged automatically.
After a short delay, the application becomes visible in Olares Market.
### 4. Manage the application lifecycle
After an application is published, developers continue to manage its lifecycle through Pull Requests.
Lifecycle actions include:
- Releasing new versions.
- Temporarily suspending distribution.
- Permanently removing an application from the Market.
These actions are controlled using PR types and special control files in the OAC.
### 5. Optimize your Market listing
Once published, you can improve how your app is presented in Olares Market by adding icons, screenshots, and featured images.
### 6. (Optional) Publish paid applications
Olares Market also supports paid application distribution.
Paid apps require additional identity registration, pricing configuration, and license management.
---
### Manual Olares Controlhub Index (`docs/manual/olares/controlhub/index.md`)
---
outline: [2, 3]
description: Understand Control Hub UI to manage applications, monitor resources, configure networking, and maintain system settings in Olares.
head:
- - meta
- name: keywords
content: Olares, Control Hub, Kubernetes, workloads, resources, terminal
---
# Manage Olares with Control Hub
**Control Hub** is Olares' visual console, providing developers and operators with precise control over the cluster and its underlying Kubernetes environment. With multi-dimensional views, you can quickly browse application workloads, view resource status, and perform maintenance operations on key objects.
Use the modular entries in the side navigation bar to access the appropriate management page for your needs.
## Module overview
Control Hub modules give you clear entry points to monitor workloads, manage resources, and access the terminal for advanced maintenance operations in Olares.
### Olares
* **Browse**: A three-column workload resource navigator. Use the left column to select the namespace for applications and services, the center to expand workloads and configurations, and the right to view real-time details and monitoring charts.
* **Namespaces**: Lists all resources by Kubernetes namespace. You can sort and filter by metrics like CPU and memory to easily troubleshoot resource hotspots.
* **Pods**: Monitors the number of pods, their status, node distribution, and resource consumption in real-time through a dual-view of a pod list and resource charts.
### Resources
* **Storage**: View persistent volume claims (PVCs), PVs, and StorageClass usage and capacity trends.
* **Network**: Monitor network security policies implemented in the system and the network connectivity of each namespace.
* **Jobs**: Manage the execution status and logs of jobs and cron jobs.
* **CRDs**: Browse and manage custom resources (CRD) and their instances.
### Middleware
Quickly view a list of integrated database and caching components (such as **Postgres**, **MongoDB**, **Redis**), including their instance information, connection details, and runtime metrics.
### Terminal
Gain one-click access to the Olares host terminal to perform debugging, view logs, and modify configurations.
---
### Manual Olares Files Index (`docs/manual/olares/files/index.md`)
---
description: Manage files efficiently in Olares with secure storage, seamless synchronization across devices, and centralized file management capabilities.
head:
- - meta
- name: keywords
content: Olares, Files, file management, Drive, Sync, cloud storage, Common
---
# Manage files in Olares
Olares's built-in Files app offers users a secure and efficient solution for file storage and synchronization, allowing access to various file types from any device or browser. It has the following advantages:
* **Access anywhere**: View, download, or share files stored in Olares from any location using any device or browser.
* **Seamless synchronization**: Ensures data remains up-to-date across all your devices.
* **Centralized storage**: Simplifies information retrieval and integration, making it easier to access, manage, and update your data, whether personal documents or team-shared materials.
## Understand the interface
The interface is similar to Windows Explorer or macOS Finder, allowing you to organize and access documents, images, videos, or any other files you own.
It mainly consists of the following components:
* **Drive**: Stores personal files that don’t require constant synchronization or frequent edits. Each user has a Home directory with default folders such as Documents, Pictures, Videos, and Downloads. External storage (e.g., USB drives or SMB shares) appears under External.
* **Sync**: A library-based high-efficiency storage area providing file synchronization services. You can create multiple independent libraries, each serving as a separate file entry point (similar to an independent cloud drive). Ideal for storing files and data requiring frequent modifications, real-time cross-device synchronization, or team collaboration.
* **Application**: Stores application-related data and system-level shared assets. It includes isolated data directories for individual applications (primarily for development and debugging) and a Common directory that stores shared AI models accessible across multiple applications and users.
* **Cloud drive**: Connected through [Integrations](mount-cloud-storage.md), including Google Drive, AWS S3, and Tencent Cloud Object Storage (COS). These allow you to link, access, and manage remote files directly from Olares.
* **Share**: The centralized hub for managing all shared folders, including Internal shares, SMB shares, and Public shares, allowing you to monitor sharing status, adjust permissions, or cancel shares in one place.
---
Learn how to mount and access third party cloud storage services in Olares.
---
### Manual Olares Vault Index (`docs/manual/olares/vault/index.md`)
---
description: Use Olares Vault to manage passwords and sensitive data with end-to-end encryption, shared vaults, sync, autofill, and two-factor authentication.
head:
- - meta
- name: keywords
content: Olares, Vault, password manager, sensitive data, OTP, 2FA, autofill, shared vault
---
# Secure sensitive data with Vault
Vault is a password manager in Olares, designed for secure storage and management of sensitive data. With Vault, you can safely store and organize private keys and passwords, digital identities (DIDs) and Olares IDs, one-time passwords (OTPs), and other confidential data.
Key features of Vault include:
* End-to-end encryption for maximum security
* Private and shared vaults for personal and organizational use
* Seamless synchronization across devices
* Autofill functionality for easy credential input
* Strong password suggestions for enhanced account security
* Two-factor authentication (2FA) support with OTP management
## Clients
Vault's server component runs on Olares, synchronizing data across multiple client devices of a single user. Data is encrypted with a private key during transmission and storage to ensure security.
You can access Vault in Olares, or through LarePass on mobile, desktop for a consistent user experience across platforms.
Visit the [official page](https://www.olares.com/larepass) for LarePass details and download options.
---
Learn how to set up and use autofill for logins with different LarePass clients.
---
### Manual Olares Wise Index (`docs/manual/olares/wise/index.md`)
---
outline: [2, 3]
description: Transform your Olares into a powerful information hub with Wise, featuring cross-platform aggregation, and seamless bookmarking capabilities.
head:
- - meta
- name: keywords
content: Olares, Wise, information hub, content aggregation, bookmarking, RSS reader
---
# Curate your information hub with Wise
Wise is a local-first modern reader designed to turn scattered information into a personal information hub. As a core application within the Olares ecosystem, it serves as your central repository for managing digital content securely and efficiently.
Wise empowers you to build this hub through two main capabilities:
- **Cross-platform content aggregation**: Centralize your reading by integrating articles, videos, audio, and feeds from various sources into a single, distraction-free interface.
- **One-click bookmarking**: Save web pages directly to Olares using the LarePass browser extension, ensuring your content is always accessible and owned by you.
## Install and open Wise
1. Open the Market, and search for "Wise".
2. Click **Get**, then **Install**.
3. Once installed, open Wise from the Launchpad.
## Understand the interface
The Wise interface is designed to help you organize and consume content efficiently.
### Sidebar navigation
The sidebar organizes your content into the following sections:
- **Feeds:** Contains your subscribed sources, including websites, blogs, and video channels.
- **Inbox:** Your central workspace for active content. It aggregates items from all sources, including saved web pages, uploaded files like PDFs or EPUBs, and feed items added to your library.
- **Content types:** Automatically categorizes your content by format, such as **Articles**, **Videos**, and **Books**.
### Item status
Every item in Wise has a status that can be either **Inbox** or **Read Later**. You can change an item's status using the icons in the list view or the reader view.
- **inbox Inbox**: Your primary collection for content you want to read soon.
- **schedule Read Later**: Your backlog for content to revisit in the future.
## Next steps
Explore the following guides to master your Wise workflow:
---
### Developer Contribute Olares Id Verifiable Credential Overview (`docs/developer/contribute/olares-id/verifiable-credential/overview.md`)
---
description: The purpose of this documentation is to help you understand how to configure various schemas and create Issuers and Verifiers for your own scenarios using
head:
- - meta
- name: keywords
content: Olares, VC Service, verifiable credential service, Issuer, Verifier, credential schema
---
# VC Service
The purpose of this documentation is to help you understand how to configure various schemas and create Issuers and Verifiers for your own scenarios using:
- [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) and [did-gate](https://github.com/Above-Os/did-gate) by Terminus.
- [SSI Service](https://github.com/TBD54566975/ssi-service) by the tbd team.
::: tip
If you want to engage in lower-level development, read the [protocol standard](#reference) together with the source code in [SSI SDK](https://github.com/TBD54566975/ssi-sdk).
:::
## Introduction
We have learned about [VC](/developer/concepts/vc.md) and the basic process for applying VCs.
Before we get into the implementation details, we can familiarize ourselves with the terms that we will encounter in the real communication process of Wallet, Verifier and Issuer.
| Term | Definition |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Holder | Holders are entities that have one or more verifiable credentials in their possession. Holders are also the entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. |
| Issuer | A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. |
| Verifier | Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. |
| Verifiable Credential | Is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build Verifiable Presentations, which can also be cryptographically verified. The claims in a credential can be about different subjects. PEX accepts Verifiable credential in 3 forms: 1. JSON_LD which is known in our system as IVerifiableCredential, 2. JWT-Wrapped VC which is known in our system as JwtWrappedVerifiableCredential or string which is a valid Verifiable credential jwt |
| Verifiable Presentation | s a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. |
| Manifest | Credential Manifests are used to describe which credentials are available for issuance. |
| Application | The format provided by Holder to Issuer, including |
| Presentation Definition | Presentation Definitions are objects that articulate what proofs a Verifier requires. |
| Presentation | Data derived from one or more verifiable credentials, issued by one or more issuers |
| Submission | TBC |
| Definition | TBC |
| Schema | All different Manifest, Application, Credential, Presentation, Definition need to define Schema with JSON. The service will verify the correctness of submitted data and then go into business process. |
## Reference
The following reference materials come from the [SSI SDK](https://github.com/TBD54566975/ssi-sdk) project.
### Specifications
Here are a set of references to specifications that this library currently supports. It is a dynamic set that will change as the library evolves.
- [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C Proposed Recommendation 03 August 2021
- [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) W3C Recommendation 09 November 2021
- Supports [Linked Data Proof](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) formats.
- Supports [VC-JWT and VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) formats.
- [Verifiable Credentials JSON Schema Specification](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Draft Community Group Report, 21 September 2021
- [Presentation Exchange 2.0.0](https://identity.foundation/presentation-exchange/) Working Group Draft, March 2022
- [Wallet Rendering Strawman](https://identity.foundation/wallet-rendering/), June 2022
- [Credential Manifest](https://identity.foundation/credential-manifest/) Strawman, June 2022
- [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) Draft Community Group Report 04 April 2022
### Signing Methods
> - [Data Integrity 1.0](https://w3c.github.io/vc-data-integrity/) Draft Community Group Report
> - [Linked Data Cryptographic Suite Registry](https://w3c-ccg.github.io/ld-cryptosuite-registry/) Draft Community Group Report 29 December 2020
> - [JSON Web Signature 2020](https://w3c-ccg.github.io/lds-jws2020/) Draft Community Group Report 09 February 2022
> - [VC Proof Formats Test Suite, VC Data Model with JSON Web Signatures](https://identity.foundation/JWS-Test-Suite/) Unofficial Draft 09 March 2022 This implementation's compliance with the JWS Test Suite can be found here.
> - Supports both JWT and Linked Data proof formats with [JOSE compliance](https://jose.readthedocs.io/en/latest/).
---
### Zh Developer Develop Submit Index (`docs/zh/developer/develop/submit/index.md`)
---
noindex: true
outline: [2, 3]
description: 了解 Olares 中的应用分发机制。
---
# 分发 Olares 应用
Olares 的应用分发基于开放标准和自动化校验机制。如果你的应用已经打包为Olares 应用图表（OAC），即可发布到 Olares 应用市场，让用户能够轻松获取和安装。
本指南将带你了解 Olares 应用分发的生命周期，理解应用市场的索引机制，如何发布、维护与推广应用。
## 开始之前
在分发应用之前，先来了解以下核心概念：
- **[Olares 应用图表（OAC）](/zh/developer/develop/package/chart.md)**
用于描述 Olares 应用的打包格式，包含元数据、所有权、版本信息与安装配置等。
- **Olares 应用市场**
用于索引、展示、分发与安装 Olares 应用的市场平台。
- **应用索引**
向 Olares 应用市场提供应用元数据的服务。Olares 提供默认的公共索引服务，你也可以部署自己的索引服务。
- **GitBot**
自动验证系统，负责校验提交的应用并执行分发规则。
## 应用分发流程
要将应用提交到 Olares 默认索引，请按以下步骤操作：
1. 在 Olares 上开发并测试你的应用，并根据[指南](/zh/developer/develop/package/chart.md)创建 OAC。
2. Fork [官方 Olares 应用市场仓库 `beclab/apps`](https://github.com/beclab/apps)，并将你的应用 OAC 添加到你的 Fork 仓库中。
3. 创建一个指向 `beclab/apps:main` 的拉取请求（Pull Request，PR），并等待 GitBot 校验你的 OAC 是否符合要求。
4. 如有需要，根据反馈更新 PR，直到所有检查通过并自动合并。
5. 稍等片刻，你就可以在 Olares 应用市场中找到你提交的应用。
---
### Zh Manual Olares Controlhub Index (`docs/zh/manual/olares/controlhub/index.md`)
---
outline: [2, 3]
description: 熟悉 Olares 中控制面板应用的操作界面，了解如何导航资源视图、管理工作负载和服务等。
head:
- - meta
- name: keywords
content: Olares, 控制面板, Control Hub, Kubernetes, 工作负载, 资源管理, 终端
---
# 通过控制面板管理 Olares
**控制面板** 是 Olares 的可视化控制台，为开发者和运维人员提供对集群与底层环境的精准管控界面。借助多维度视图，你可以快速浏览应用负载、查看资源状态，并对关键对象执行运维操作。
通过侧边导航栏的模块化入口，你可以按所需功能功能进入相应管理页面。
## 模块介绍
控制面板的不同模块为你提供清晰的入口，用于监控工作负载、管理资源，以及访问终端以执行高级维护操作。
### Olares
- **浏览**
三列式工作负载资源导航。左侧选择应用和服务对应的命名空间，居中展开工作负载和配置等资源，右侧查看实时详情与监控图表。
- **命名空间**
以 Kubernetes 命名空间维度列出所有资源，支持按 CPU / 内存等指标排序、过滤，便于排查资源热点。
- **容器组**
通过容器组列表和资源图表双视图，实时监控 Pod 数量、状态、节点分布及资源消耗等。
### 资源
- **存储**
查看持久化卷声明（PVC）、PV、StorageClass 占用与容量趋势。
- **网络**
审计网络策略（NetworkPolicy）与命名空间间连通性，定位流量瓶颈。
- **任务**
管理批处理/定时任务的执行状态与日志。
- **CRDs**
浏览并管理自定义资源（CRD）及其实例
### 中间件
快速查看集成的数据库与缓存组件（如 **Postgres**、**MongoDB**、**Redis**）实例列表、连接信息、运行指标。
### 终端
一键进入 Olares 宿主机终端，执行调试、日志查看与配置修改。适合高级运维操作。
---
### Zh Manual Olares Files Index (`docs/zh/manual/olares/files/index.md`)
---
description: 使用 Olares 文件管理器进行文件存储、同步和访问，实现高效的文件管理和团队协作。
head:
- - meta
- name: keywords
content: Olares, 文件管理器, 文件存储, 文件同步, 云存储, 外部设备, 团队协作
---
# 管理文件
Olares 内置的文件应用为用户提供了安全高效的文件存储与同步解决方案，支持从任何设备或浏览器访问各种文件类型。主要优势包括：
* **随时随地访问**：使用任意设备端的浏览器，从任何位置查看、下载或共享存储在 Olares 中的文件。
* **无缝同步**：确保数据在所有设备间保持最新。
* **集中存储**：简化信息检索与集成，无论是个人文档还是团队共享资料，均可轻松访问、管理与更新。
## 界面概览
文件管理器的界面类似于 Windows 资源管理器或 macOS 的访达，允许你整理和访问文档、图片、视频或其他文件。主要由以下几个部分组成：
* **存储**：用于存储个人文件，适合那些不需要频繁同步或修改的内容。每个用户都有一个首页目录，默认包含文档、图片、影视、下载等文件夹。外部存储（如 USB 驱动器或 SMB 共享）会显示在**外部设备**下。
* **同步**：基于资料库（Library）的高效存储区，提供文件同步服务。你可以创建多个独立的资料库，每个库均作为一个单独的文件入口（类似于独立的网盘空间）。适合存放需要频繁修改、跨设备实时同步或团队协作的文件和数据。
* **应用**：存储与应用相关的数据以及系统级共享资源。其中包括为各个应用隔离的数据目录（主要用于开发和调试），以及一个公共目录，用于存储可被多个应用和用户共享访问的 AI 模型。
* **云存储**：通过[集成](mount-cloud-storage.md)功能连接的外部云存储服务，包括 Google Drive、AWS S3 和 腾讯云 COS。可直接在 Olares 中挂载、访问和管理远程文件。
* **分享**：用于集中管理所有已开启共享的项目，包括内部分享、SMB 分享和公开分享，方便统一查看分享状态、调整用户权限或取消共享。
---
---
### Zh Developer Contribute Olares Id Verifiable Credential Overview (`docs/zh/developer/contribute/olares-id/verifiable-credential/overview.md`)
---
description: 本文档旨在帮助你了解如何使用以下工具，为你自己的场景配置各种 schema 并创建发行方 (Issuers) 和验证方 (Verifiers)
head:
- - meta
- name: keywords
content: Olares, VC, 可验证凭证, Issuer, Verifier, SSI Service, Presentation Exchange, DID
---
# VC 服务
本文档旨在帮助你了解如何使用以下工具，为你自己的场景配置各种 schema 并创建发行方 (Issuers) 和验证方 (Verifiers)：
- Olares 的 [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) 和 [did-gate](https://github.com/Above-Os/did-gate)
- tbd 团队的 [SSI Service](https://github.com/TBD54566975/ssi-service)
::: tip
如果你想进行更底层的开发，请结合 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 中的源代码阅读[协议标准](#reference)。
:::
## 简介
我们已经了解了 [VC](/zh/developer/concepts/vc.md) 的概念以及申请 VC 的基本流程。
在深入实现细节之前，我们可以先熟悉一下在钱包 (Wallet)、验证方 (Verifier) 和发行方 (Issuer) 的实际通信过程中会遇到的术语。
| 术语 | 定义 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **持有方 (Holder)** | 持有一个或多个可验证凭证的实体。持有方也是向验证方提交证明以满足其在“呈现定义 (Presentation Definition)”中描述的需求的实体。 |
| **发行方 (Issuer)** | 一个实体可以扮演的角色，通过对一个或多个主体断言声明，从这些声明中创建可验证凭证，并将其传输给持有方。 |
| **验证方 (Verifier)** | 定义了需要从持有方那里获取何种证明（通过“呈现定义”）以进行交互的实体。 |
| **可验证凭证 (VC)** | 一种防篡改的凭证，其所有权可以被加密验证。可验证凭证可用于构建可验证表述 (Verifiable Presentations)，该表述也可被加密验证。凭证中的声明可以关于不同的主体。PEX 接受三种形式的可验证凭证：1. JSON_LD，在我们的系统中称为 IVerifiableCredential；2. JWT 包装的 VC，在我们的系统中称为 JwtWrappedVerifiableCredential；或 3. 字符串，即一个有效的可验证凭证 jwt。 |
| **可验证表述 (VP)** | 一种防篡改的表述，其编码方式使得数据的所有权在经过加密验证后可以被信任。 |
| **清单 (Manifest)** | 凭证清单 (Credential Manifests) 用于描述哪些凭证可供发行。 |
| **申请 (Application)** | 持有方提供给发行方的格式。 |
| **呈现定义 (Presentation Definition)** | 阐明验证方需要何种证明的对象。 |
| **呈现 (Presentation)** | 源自一个或多个发行方所发行的一个或多个可验证凭证的数据。 |
| **提交 (Submission)** | TBC (待补充) |
| **定义 (Definition)** | TBC (待补充) |
| **Schema** | 所有不同的清单、申请、凭证、呈现、定义都需要使用 JSON 来定义 Schema。服务将验证所提交数据的正确性，然后进入业务流程。 |
## 参考资料
以下参考资料来自 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 项目。
### 规范
以下是本库目前支持的一系列规范参考。这是一个动态集合，会随着库的演进而变化。
- [去中心化标识符 (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C 建议提案 2021年8月3日
- [可验证凭证数据模型 v1.1](https://www.w3.org/TR/vc-data-model/) W3C 推荐标准 2021年11月9日
- 支持 [链接数据证明 (Linked Data Proof)](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) 格式。
- 支持 [VC-JWT 和 VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) 格式。
- [可验证凭证 JSON Schema 规范](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) 社区组报告草案 2021年9月21日
- [呈现交换 (Presentation Exchange) 2.0.0](https://identity.foundation/presentation-exchange/) 工作组草案 2022年3月
- [钱包渲染草案 (Wallet Rendering Strawman)](https://identity.foundation/wallet-rendering/) 2022年6月
- [凭证清单 (Credential Manifest)](https://identity.foundation/credential-manifest/) 草案 2022年6月
- [状态列表 (Status List) 2021](https://w3c-ccg.github.io/vc-status-list-2021/) 社区组报告草案 2022年4月4日
### 签名方法
> - [数据完整性 (Data Integrity) 1.0](https://w3c.github.io/vc-data-integrity/) 社区组报告草案
> - [链接数据加密套件注册表 (Linked Data Cryptographic Suite Registry)](https://w3c-ccg.github.io/ld-cryptosuite-registry/) 社区组报告草案 2020年12月29日
> - [JSON Web 签名 (JSON Web Signature) 2020](https://w3c-ccg.github.io/lds-jws2020/) 社区组报告草案 2022年2月9日
> - [VC 证明格式测试套件，使用 JSON Web 签名的 VC 数据模型](https://identity.foundation/JWS-Test-Suite/) 非官方草案 2022年3月9日 本实现对 JWS 测试套件的合规性可以在此处找到。
> - 支持 JWT 和链接数据证明两种格式，并符合 [JOSE 规范](https://jose.readthedocs.io/en/latest/)。
---
### Daemon Docs Wifi And Portal (`daemon/docs/wifi-and-portal.md`)
# Wi-Fi authentication and captive portal integration
## HTTP and BLE contract
The existing connect-wifi HTTP endpoint and BLE connection characteristic accept
the same JSON object. Existing `ssid` and `password` requests remain valid for
unambiguous personal networks. The server resolves authentication from the AP
scan; hidden networks absent from the scan are not supported by this version.
`POST /command/connect-wifi` does not require `X-Signature` or an access token.
Server readiness, operation-state checks, and request validation still apply.
Fields:
- `ssid`: required, 1–32 bytes.
- `password`: personal-network key or 802.1X account password.
- `username`: 802.1X account identity.
- `security`: optional `open`, `owe`, `wep`, `wpa-psk`, `sae`, or `wpa-eap`.
`wpa-psk` covers WPA/WPA2 Personal. `sae` selects WPA3 Personal.
- `bssid`, `interface`: optional AP and device selectors. Use these when the same
SSID is advertised with different authentication. An explicit BSSID also pins
the resulting profile to that AP.
- `wepKeyType`: `key` (default) or `passphrase`; `wepKeyIndex`: 0–3, default 0.
- `enterprise`: optional object described below.
802.1X example using the system trust store:
```json
{
"ssid": "Office",
"security": "wpa-eap",
"username": "alice",
"password": "account-password",
"enterprise": { "domainSuffixMatch": "radius.example.com" }
}
```
The default EAP method is PEAP with MSCHAPv2. `enterprise.eap` can be `peap` or
`ttls`. `enterprise.phase2Auth` defaults to `mschapv2`; TTLS also accepts `pap`,
`chap`, and `mschap`. `anonymousIdentity` is optional. EAP-TLS and Suite-B-only
networks are unsupported.
Server certificate validation is enabled by default. Supply `domainSuffixMatch`
and optionally `caCertPath`, an absolute path to an existing CA certificate on
the device. With no CA path the system trust store is used. This API does not
upload certificates. Only explicit `enterprise.insecureSkipVerify: true` disables
server certificate validation; username and password alone do not imply that
validation is disabled.
The scan response includes `ss`, `st`, and `se` (security types array),
`bs` (BSSID), and `if` (interface). Unknown authentication is reported as `unsupported`,
never as an open network. APs are grouped by interface, SSID, and authentication
capabilities; the strongest AP represents a group. HTTP additionally includes
`connected` (always a boolean) and receives the full list. BLE omits connection
status entirely (neither `connected` nor `co`). Its AP list contains only
`ss` (SSID), `st` (signal strength), and `se` (authentication types); `bs` and
`if` are omitted. Equivalent SSID/authentication entries across radios are merged,
keeping the strongest signal. Entries retain
the internal connection/signal priority order; an entry that does not fit is
skipped so a shorter later entry can use the remaining 512-byte capacity. Connection payloads exceeding 512 bytes are
rejected by the BLE parser; no application-level fragmentation is implemented.
Bluetooth stacks may themselves reject an oversized write before it reaches the
server. Use HTTP for larger enterprise requests.
When authentication is omitted, same-name networks with different capabilities
require an explicit selection. On mixed WPA2/WPA3 APs, daemon queries the selected
interface's wpa_supplicant `Capabilities.KeyMgmt` and prefers SAE when supported.
If this capability cannot be queried (including a different Wi-Fi backend),
specify `security` explicitly. Authentication failure never triggers automatic
fallback to weaker security.
Connections have a 90-second deadline, including discovery and activation.
Matching saved profiles retain unrelated settings and their UUID. Credentials are
updated through D-Bus, and profiles are saved after activation succeeds. Failure
restores the previous profile including stored secrets, or deletes a newly
created profile. Errors are English and do not include remote error text or
passwords. A successful response means Wi-Fi activation succeeded, not that
captive portal login has completed.
## Desktop PortalHelper contract
The daemon watches NetworkManager's global `Connectivity` property and
`PrimaryConnection` on the system bus. On PORTAL (2), it opens the primary
connection's login window using `ConnectivityCheckUri`; the desktop browser
handles redirects. It also handles initial PORTAL state, service restarts,
connection switches, and leaving PORTAL. This applies to Ethernet as well as
Wi-Fi. It does not detect a portal on a secondary link while another connection
keeps global connectivity FULL.
Default D-Bus service and interface: `com.olares.desktop.PortalHelper`.
Object: `/com/olares/desktop/PortalHelper`.
See [the interface XML](com.olares.desktop.PortalHelper.xml).
- `OpenPortal(s connectionUuid, s interfaceName, s url)` must enqueue presentation
and return immediately. Repeated calls for the same connection must not create
duplicate windows. Accept only HTTP/HTTPS URLs and route the request to the
local desktop session.
- `ClosePortal(s connectionUuid)` must be idempotent, including when no window is
open. It must also cancel any queued presentation for that UUID. The service
should serialize requests for a UUID so an earlier open cannot overtake close.
The daemon uses a five-second call timeout and 1, 2, 4, 8, 16, then 30-second retry
delays. State changes cancel stale calls/retries. A timed-out open is treated as
possibly accepted and closed when the desired connection changes. Successful
opens are deduplicated until the state or service owner changes. Helper failures
do not fail the Wi-Fi connection command. Shutdown closes the tracked window on
a best-effort basis.
`--portal-helper-service=NAME` overrides the bus destination only; the object path
and interface remain fixed. The helper itself is delivered by the desktop, not by
this daemon change.
## Deployment
NetworkManager connectivity checking must already be configured and enabled with
a usable HTTP/HTTPS `ConnectivityCheckUri`. Daemon does not change this setting or
choose a third-party probe endpoint. Invalid/missing URLs are retried and logged
without opening a browser.
The desktop must register the helper on the **system bus** and install its own
service/activation definition and D-Bus policy. For example, with a dedicated
service account `olares-portal` and root olaresd, the policy can grant that account
ownership and root permission to call the two methods:
```xml
```
Adapt the service account to the actual desktop deployment; do not install this
example verbatim without that account. Keep ownership restricted to the helper,
and validate sender credentials in the helper. The desktop owns session routing
and the sandboxed authentication UI. Service-name overrides require matching
policy changes. Portal window dismissal/login may trigger NetworkManager's
`CheckConnectivity` from the desktop to accelerate completion detection.
## Validation
```sh
go test -race ./internel/wifi ./internel/portal
go test ./internel/ble ./internel/apiserver/handlers -run 'TestWifi|TestConnectWifi'
go build -o /tmp/olaresd ./cmd/terminusd
```
The Portal test uses an isolated real D-Bus daemon if `dbus-daemon` is installed;
it skips that test otherwise. Other tests mock NetworkManager operations and
exercise authentication mappings, profile rollback, timeouts, retries, and
payload limits. The pre-existing BLE `TestScan` requires physical hardware and is
not part of these commands.
Hardware acceptance: connect to open/OWE, WPA2/WPA3, PEAP/MSCHAPv2, and TTLS APs;
verify invalid credentials fail without erasing saved settings; exercise a real
portal redirect and login; switch primary networks during login and restart NM
and the helper. Confirm only one current login window remains and credentials do
not appear in logs. These checks require a Linux device with Wi-Fi and the desktop
helper implementation.
References: [NM D-Bus types](https://networkmanager.dev/docs/api/latest/nm-dbus-types.html),
[NM properties](https://networkmanager.dev/docs/api/latest/gdbus-org.freedesktop.NetworkManager.html),
[802.1X settings](https://networkmanager.dev/docs/api/latest/settings-802-1x.html),
[wpa_supplicant D-Bus](https://w1.fi/wpa_supplicant/devel/dbus.html).
## Standalone AP list endpoint
`GET /system/list-aps` uses the same `RequireLocal` middleware as `/system/ifs`.
That middleware currently passes requests through without enforcing access control.
It scans NetworkManager directly, independently of Bluetooth initialization or
its cached AP list. Like BLE scanning, it enables a disabled Wi-Fi radio before
scanning. The scan has a 30-second deadline and returns the full list, ordered by
connected status and signal strength. Existing grouping by interface, SSID and
security capabilities applies.
```json
{
"code": 200,
"message": "",
"data": [
{ "ss": "Office", "st": 85, "connected": true,
"se": ["wpa-eap"], "bs": "00:11:22:33:44:55", "if": "wlan0" }
]
}
```
No Wi-Fi devices or no visible APs returns `data: []`. NetworkManager failures
or scan timeouts return HTTP 503 with an English error message. This endpoint
does not apply the BLE 512-byte limit and does not return credentials.
---
### Developer Cli Agent Skills (`docs/developer/cli-agent-skills.md`)
---
outline: [2, 3]
description: Learn how Olares CLI Agent Skills help AI agents manage Olares, which skills are available, and how they are installed and updated.
head:
- - meta
- name: keywords
content: Olares, Olares CLI, Agent Skills, olares-shared, skill catalog, AI agent integration
---
# Olares CLI Agent Skills
Olares CLI includes Agent Skills that teach AI agents how to manage Olares through the `olares-cli` command. This page lists the available skills and explains how to install, update, and inspect them.
If you are setting up Olares CLI for the first time, follow [Use Olares CLI with AI agents](./cli-install.md). That guide covers installation, login, and your first AI agent task in one flow.
## Available Agent Skills
| Skill | Description |
|-------|-------------|
| `olares-shared` | Routes Olares requests, explains profiles and authentication, and provides login recovery. |
| `olares-chart` | Turns a repository, Docker Compose project, or Helm chart into an Olares app and deploys it. |
| `olares-files` | Manages Olares files, including upload, download, compression, sharing, and SMB or NFS mounts. |
| `olares-market` | Browses Olares Market and installs, upgrades, uninstalls, clones, stops, resumes, or restarts apps. |
| `olares-settings` | Manages Olares settings such as users, apps, VPN, network, backups, integrations, GPU, and search. |
| `olares-dashboard` | Reads CPU, memory, disk, network, pod, GPU, fan, and application resource usage. |
| `olares-cluster` | Inspects Kubernetes runtime state, logs, containers, workloads, jobs, nodes, and middleware. |
| `olares-doctor` | Diagnoses failed installs, crashes, image pull errors, unreachable apps, and performance problems. |
| `olares-router` | Configures cloud or local AI models, defaults, keys, quotas, usage, and model calls. |
| `olares-knowledge` | Manages URL, yt-dlp, aria2, torrent, Hugging Face, and Wise download tasks. |
| `olares-search` | Searches Drive files, Sync libraries, and installed apps. |
| `olares-publish` | Publishes a locally running app to the public Olares Market, including listing metadata and assets. |
## Install or export the skills
Write the bundled skills to the standard locations:
```bash
olares-cli skills install
```
One copy is written to `~/.agents/skills`. Olares CLI then links it into every compatible agent skills directory that already exists, including directories used by Cursor, Claude Code, Codex, and OpenClaw. It does not create directories for agents that are not installed. On systems where symbolic links are unavailable, Olares CLI copies the files instead.
To write the suite to another location, such as a project directory or container image, export it:
```bash
olares-cli skills export ./skills
```
## Keep the skills matched to Olares CLI
For an npm-installed copy, update Olares CLI and its installed skills together:
```bash
olares-cli update
```
If you update the CLI manually or install another build, run:
```bash
olares-cli skills install
```
When the installed skills were written by a different CLI build, Olares CLI prints a notice on standard error. Set `OLARES_CLI_NO_SKILL_NOTICE=1` only when an automation cannot tolerate the extra output.
Install skills from the Olares CLI binary rather than a registry or a Git branch. Registry and repository copies can drift away from the commands supported by the installed binary. The ClawHub copy predates the embedded bundles and is no longer updated.
## How Agent Skills work
Each skill is a `SKILL.md` bundle that an AI runtime loads when a request matches its description. The skill maps a natural-language task to the appropriate Olares CLI commands and explains important flags, authentication behavior, and common error recovery.
The source bundles are in [`cli/skills/`](https://github.com/beclab/Olares/tree/main/cli/skills). Each bundle contains a `SKILL.md` file and, when needed, a `references/` directory with detailed instructions for individual commands.
The released bundles are compiled into the Olares CLI binary. Commands such as `skills install`, `skills export`, and `skills read` therefore use the same skill content as the CLI version that runs them.
## Inspect the bundled skills
List the skills carried by the current Olares CLI binary:
```bash
olares-cli skills list
olares-cli skills list -o json
```
Read a skill or one of its reference files without installing it:
```bash
olares-cli skills read olares-shared
olares-cli skills list olares-router/references
olares-cli skills read olares-router references/olares-router-calling.md
```
These commands read the skills bundled with your installed CLI. They do not connect to Olares or check which skills your agent can access. To check skill availability in the agent, follow [Run your first task with an AI agent](./cli-install.md#run-your-first-task-with-an-ai-agent).
---
### Developer Cli Install (`docs/developer/cli-install.md`)
---
outline: [2, 3]
description: Install and sign in to Olares CLI, then use its Agent Skills to manage Olares with an AI agent.
head:
- - meta
- name: keywords
content: Olares, Olares CLI, AI agents, Agent Skills, install Olares CLI, Claude Code, Codex, Cursor
---
# Use Olares CLI with AI agents
This guide shows you how to install Olares CLI and its matching Agent Skills on your computer, sign in to Olares, and complete your first task through an AI agent.
:::info Using an AI agent app on Olares?
[Lares](../use-cases/lares.md), [Hermes Agent](../use-cases/hermes.md), and [OpenClaw](../use-cases/openclaw.md) on Olares already include Olares CLI and its Agent Skills. You do not need to install them again inside the app. Follow your app's guide to get started.
:::
:::warning Olares hosts already include Olares CLI
If you are working directly on a Linux host that runs Olares OS, do not overwrite `/usr/local/bin/olares-cli`. See [Using Olares CLI on an Olares host](#using-olares-cli-on-an-olares-host).
:::
## Before you begin
Make sure you have:
- A computer running macOS, Windows, or Linux with Node.js 18 or later.
- An activated Olares and your Olares ID.
- An AI agent that supports Agent Skills, such as Codex, Claude Code, Cursor, or OpenClaw.
## Install Olares CLI and Agent Skills
Open a terminal and run:
```bash
npx @olares/cli@latest install
```
The setup wizard installs the same release of Olares CLI and its Agent Skills. The skills are written to `~/.agents/skills` and linked to the skill directories of compatible AI agents already installed on your computer.
Example output:
```text
┌ Setting up Olares CLI...
│
◇ Installed globally
│
◇ Skills installed
│
└ You are all set!
```
Check the installed CLI version:
```bash
olares-cli version
```
:::info
The setup wizard installs Olares CLI on your computer. It does not install Olares OS and does not sign in to your Olares account.
:::
## Log in to Olares
1. Start an interactive login with your Olares ID. For example:
```bash
olares-cli profile login --olares-id laresprime@olares.com
```
Replace `laresprime@olares.com` with your Olares ID.
2. Enter your Olares password when prompted. The password is not displayed in the terminal.
3. If two-step verification is enabled, enter the six-digit code from LarePass.
4. Check the active profile:
```bash
olares-cli profile whoami
```
The profile tells Olares CLI which Olares to connect to and which user it should act as. Olares CLI refreshes the login token automatically.
## Run your first task with an AI agent
Open your AI agent using the same operating system account you used to install Olares CLI.
In the agent's chat window, check that it can find the Olares skills:
- If the agent lists skills as slash commands, type `/` and look for entries starting with `olares-`.
- Or ask the agent:
```plain
List the available skills related to Olares.
```
Look for skills such as `olares-files` and `olares-market`. If they are missing, run `olares-cli skills install` again, check the reported installation locations, and start a new agent conversation.
Then ask the agent to complete your first task:
```plain
List the files in the Home folder on my Olares device.
```
The agent selects the relevant skill and runs the Olares CLI command. Check that it returns the contents of your Olares Home folder. This confirms that the agent can use the CLI to access your Olares.
Try a few more tasks:
```plain
Install Firefox from Olares Market and tell me when it is ready.
Show me which apps on my Olares are using more than 1 GB of memory.
Find the document named quarterly-report in my Olares files.
```
Your AI agent may ask for approval before running a command or changing Olares. Review the proposed action before approving it.
## Manage profiles
One Olares CLI installation can keep profiles for multiple Olares devices or identities.
| Task | Command |
|------|---------|
| List all profiles | `olares-cli profile list` |
| Show the current identity | `olares-cli profile whoami` |
| Switch to another profile | `olares-cli profile use ` |
| Switch back to the previous profile | `olares-cli profile use -` |
| Remove a profile and its stored token | `olares-cli profile remove ` |
Olares CLI stores tokens securely for the current operating system. Use `profile remove` to clear a profile and its token instead of editing credential files by hand.
## Update Olares CLI and Agent Skills
Check for an update without changing anything:
```bash
olares-cli update --check
```
Update Olares CLI and install the matching Agent Skills in one step:
```bash
olares-cli update
```
To receive every published release, including versions not yet tagged as `latest`, use the `next` channel:
```bash
olares-cli update --channel next
```
Check the installed copy and version after the update:
```bash
olares-cli version
```
## Other installation options
### Install Olares CLI first
To install the CLI without running the setup wizard:
```bash
npm install @olares/cli
```
Then install the Agent Skills carried by that binary:
```bash
olares-cli skills install
```
### Run one command without installing
Use `npx` to run a single command without adding Olares CLI to your `PATH`:
```bash
npx @olares/cli@latest files ls /drive/Home
```
Your profile and login state remain available for later commands.
## Using Olares CLI on an Olares host
Olares OS includes a system-managed CLI at `/usr/local/bin/olares-cli`. The system copy maintains Olares OS and is updated through Olares OS releases. Do not replace it with the npm package.
On an Olares host, the setup wizard detects the existing release-grade binary and leaves it in place. If you need the standalone npm version as well, install it under a separate prefix:
```bash
npm install @olares/cli@latest --prefix ~/.olares-cli-npm
export PATH="$HOME/.olares-cli-npm/bin:$PATH"
olares-cli skills install
```
In this terminal, `olares-cli` now runs the npm copy. For Olares OS maintenance, use the full path `/usr/local/bin/olares-cli` to run the system copy.
:::warning Do not overwrite the system CLI
Do not run `npm install @olares/cli --force` on an Olares host. It can overwrite the OS-managed binary and break its version relationship with `olaresd` and the cluster.
:::
## Learn more
- [Olares CLI Agent Skills](./cli-agent-skills.md): Browse the complete skill catalog and learn how skills are installed, discovered, and kept in sync with the CLI.
- [Manage Olares and run research tasks with Lares](../use-cases/lares.md): Use the official Olares AI assistant with Olares CLI and Agent Skills built in.
- [Olares, Olares CLI, and AI Agents: The Relationship Explained](https://www.olares.com/blog/olares-cli-ai-agents-explained/): Learn where agents can run and how profiles connect them to Olares.
---
### Manual Access Olares Terminal (`docs/manual/access-olares-terminal.md`)
---
outline: [2, 3]
description: Access the Olares host terminal via Control Hub or SSH.
---
# Access the Olares terminal
Some development and operational tasks require running commands on the Olares host, such as inspecting disks, verifying host state, or updating host-level configuration. Since Olares hosts are commonly deployed without a monitor or keyboard, terminal access is provided remotely.
You can connect to the host terminal using one of the following methods:
- **Control Hub Terminal**: A web-based interface for direct `root` access. It is recommended for quick or occasional tasks.
- **Secure Shell (SSH)**: The standard protocol for remote management. It is recommended for advanced or automated operations.
:::tip For Olares One users
If you are using Olares One, refer to [SSH into Olares One](/one/access-terminal-ssh.md).
:::
## Access via Control Hub
For quick access without configuring an SSH client, use the web-based terminal built into Control Hub.
1. Open Control Hub.
2. In the left sidebar, under the **Terminal** section, click **Olares**.
:::tip Run as `root`
The Control Hub terminal runs as `root` by default. You do not need to prefix commands with `sudo`.
:::
## Access via SSH
SSH establishes an encrypted session over the network, allowing you to run command-line operations on the Olares host from your computer.
### Connect over a local network
Before connecting, make sure you have:
- The local IP address of the Olares host.
- The username and password for the Olares host.
1. Open a terminal on your computer.
2. Run the SSH command using the following format:
```bash
ssh @
```
For example:
```bash
ssh olares@192.168.31.155
```
3. Enter the host password when prompted.
### Connect from a different network
If your computer is not on the same local network as the Olares host, enable LarePass VPN to establish a secure tunnel to your host.
Before connecting, make sure you have:
- LarePass installed and signed in on the computer you will use for the VPN connection.
- The username and password for the Olares host.
1. On Olares, go to **Settings** > **VPN**, and enable **Allow SSH via VPN**.
{width=90%}
2. Open the LarePass desktop client, click your avatar in the top-left corner, and turn on **VPN connection**.
3. On Olares, go to **Settings** > **VPN** > **View VPN connection status**, locate the host entry, and note the IP address that starts with `100.64`.
{width=90%}
4. Open a terminal on your computer.
5. Run the SSH command using the following format:
```bash
ssh @
```
For example:
```bash
ssh olares@100.64.0.1
```
6. Enter the host password when prompted.
---
### Manual Collect Diagnostic Information (`docs/manual/collect-diagnostic-information.md`)
---
outline: [2, 3]
description: Collect Olares system logs with the CLI, download the archive from the host, and share it safely.
head:
- - meta
- name: keywords
content: Olares, technical support, collect logs, export logs, system logs, pod logs
---
# Collect diagnostic information
When a troubleshooting guide does not resolve an issue, collect the relevant context and logs for further investigation. If Settings is available and you only need a system log archive, you can [export system logs in Settings](help/request-technical-support.md) instead.
## Record the problem context
Before collecting logs, write down:
- The exact time the issue occurred and your time zone.
- Your Olares version and the affected app version.
- What you were doing, the expected result, and what happened instead.
- The shortest steps that reproduce the issue.
- The complete error message and a screenshot, if available.
- Any recent change, such as an Olares update, app update, network change, or restart.
This context helps match a log entry to the visible problem.
## Connect to the Olares host
Connect to the device with SSH. On Olares One, the SSH user is `olares`:
```bash
ssh olares@{local_ip_address}
```
For a self-installed Olares device, use the Linux account that has `sudo` access.
## Collect and save the logs
Run the following commands on the Olares host:
```bash
mkdir -p "$HOME/olares-logs"
sudo olares-cli logs --max-lines 0 --output-dir "$HOME/olares-logs"
```
The command collects recent Olares system, Kubernetes, container, kernel, and network diagnostics. `--max-lines 0` removes the per-source line limit for system service logs and previous-boot kernel logs. The default seven-day time range still applies. When the command finishes, the last line prints the full archive path, for example:
```plain
logs have been collected and archived in: /home/olares/olares-logs/olares-logs-20260827-050839.tar.gz
```
If the issue occurred recently, you can reduce the archive size by specifying a time range, for example `--since 3h`.
## Download the archive
On your own computer, copy the exact file printed in the previous step. Replace `{local_ip_address}` and `{timestamp}` with your values:
```bash
scp olares@{local_ip_address}:~/olares-logs/olares-logs-{timestamp}.tar.gz .
```
The final dot saves the archive to the current directory on your computer. If you use a different SSH account, replace `olares` with that account name.
## Share logs safely
:::warning Logs can contain private system information
System logs can include Olares identifiers, hostnames, IP addresses, network configuration, file paths, and application metadata. Do not attach the complete archive to a public GitHub Issue or Discussion.
:::
1. For a general question that does not require logs, open a [GitHub Discussion](https://github.com/beclab/Olares/discussions/new?category=q-a).
2. For a reproducible software bug, open a [GitHub Issue](https://github.com/beclab/Olares/issues/new) with the problem context, but leave out the full log archive and secrets.
3. When the Olares team requests logs, send them through the private channel provided to you or email [hi@olares.com](mailto:hi@olares.com). Include the related GitHub issue number, if there is one.
Before sending, remove passwords, recovery phrases, API keys, access tokens, and other secrets from your description and screenshots. The Olares team will never need your password or recovery phrase to diagnose a problem.
---
### Manual Free Up Disk Space (`docs/manual/free-up-disk-space.md`)
---
outline: [2, 3]
description: Free Olares disk space by removing unused AI models and carefully deleting unreferenced container images on Olares 1.12.6.
head:
- - meta
- name: keywords
content: Olares, disk space, storage full, image cleanup, model cleanup, crictl, Hugging Face, Ollama
---
# Free up disk space
Use this guide to reclaim storage used by AI models you no longer need and container images that Olares no longer references. It also applies when disk usage is high, an app cannot install, or sign-in reports **Authentication failed, disk space is full**.
Start with model files that you can identify. Remove container images only after reviewing the unused-image list. Stopping an app does not automatically remove its models or images because Olares may need them when the app resumes.
## Prerequisites
- Administrator access to Olares.
- Terminal access to the Olares host for removing unused images. See [Connect to Olares via SSH](/manual/access-olares-terminal).
## Check disk usage
1. Open **Dashboard** and select the **Disk** card.
2. Check the used and available space.
3. Select **Occupancy analysis** to see which file system is full.
For details, see [Monitor resource usage](olares/resources-usage.md#disk-panel).
## Remove unused AI models
:::warning Model deletion cannot be undone
Delete only models that you recognize and no longer need. Apps that use a deleted model stop working until the model is downloaded again.
:::
1. Open **Files**.
2. Check the model locations that exist on your system:
- On Olares 1.12.6, select **Application** > **Common**, then open `huggingface` or `ollama`.
- For models stored in the earlier per-user layout, select **Home**, then look for app-named folders such as `Huggingface` and `Ollama`.
3. Identify models that are no longer used by any app.
4. Right-click the model folder or file and select **Delete**.
Keep the required directory structure when deleting individual models. For details, see [Manage shared AI models](olares/files/files-common.md#manage-model-files).
## List unused container images
Olares 1.12.6 includes a command that lists local container images with no standard workload references. Run it before deleting anything:
```bash
olares-cli doctor images --unused
```
Review every row. The command sorts unused candidates from largest to smallest and shows the estimated reclaimable size.
On a multi-node Olares cluster, the list covers images stored on the control node where the command runs. It does not inventory images stored only on worker nodes.
:::warning Check custom workloads before continuing
The unused-image check covers standard Deployment, StatefulSet, DaemonSet, Job, and CronJob specifications. It may not detect images used only by a bare Pod, static Pod, custom controller, or a running container still pinned to an older digest. If you created custom workloads, do not run the deletion pipeline without checking them first.
:::
## Delete reviewed container images
After you confirm that the list contains only images you can re-download, run:
```bash
olares-cli doctor images --unused --no-headers \
| awk '$1 ~ /^[0-9a-f]+$/ && length($1) == 12 {print $1}' \
| xargs -r sudo crictl rmi
```
The filter passes only 12-character hexadecimal image IDs to `crictl`; it does not treat the `no unused images` message as an image ID.
Deleted images do not remove personal files or app data. However, resuming or reinstalling an affected app may be slower because Olares must download its image again.
## Verify available space
1. Run `olares-cli doctor images --unused` again.
2. Return to **Dashboard** > **Disk** and refresh the usage data.
3. Resume the apps you need and confirm that they start normally.
If disk usage is still high after cleanup, see [Expand Olares system storage](best-practices/expand-storage-in-olares.md).
## Avoid blanket image pruning
:::danger Not recommended
Do not use `sudo crictl rmi --prune` as routine cleanup. It removes images for all stopped apps, not just the candidates reviewed with `olares-cli doctor images --unused`. Apps can take longer to resume, and the Olares UI can temporarily show inconsistent image information.
:::
Use blanket pruning only when Olares support specifically asks you to and you understand that stopped apps may need to download their images again.
---
### Manual Glossary (`docs/manual/glossary.md`)
---
description: Find clear definitions of common Olares and personal cloud terms in this alphabetized technical glossary.
head:
- - meta
- name: keywords
content: Olares, glossary, personal cloud terms, DID, TOTP, FRP, VC
---
# Glossary
## C
### CNAME Record
A CNAME (Canonical Name) record is a type of DNS (Domain Name System) record that maps your custom domain name to an Olares-provided address, enabling domain-to-application mapping.
## D
### DID
A Decentralized Identifier (DID) is a unique digital identification method that enables any person or entity to have a persistent, unique identity on the network. This identifier is fully independent and doesn't require verification or registration through a central authority. A DID is a unique string that starts with "did" and follows specific formatting and naming conventions.
## F
### FRP
Fast Reverse Proxy (FRP) is a high-performance reverse proxy application designed for internal network penetration scenarios. It enables servers behind NAT or firewalls to provide services externally, even without public IP addresses. FRP helps users easily expose internal services to the public network.
## T
### TOTP
Time-Based One-Time Password (TOTP) is a time-based algorithm for generating one-time passwords, widely used in two-factor authentication (2FA). It generates single-use passwords using a shared key and current time to enhance account security. Each password is valid for a brief period (typically 30 or 60 seconds) before a new one is generated.
## V
### VC
Verifiable Credential (VC) is a digital format proof that verifies certain attributes or qualifications of its holder without revealing additional personal information. It involves three primary roles:
* Holder: The individual who possesses and uses the credential to prove certain information
* Issuer: The authority or entity that creates and issues verifiable credentials
* Verifier: The individual or organization that needs to verify the authenticity of the holder's information by validating the credential
---
### Manual Install Larepass Browser Extension (`docs/manual/install-larepass-browser-extension.md`)
---
outline: [2, 3]
description: Download and install the LarePass browser extension manually in Google Chrome.
head:
- - meta
- name: keywords
content: Olares, LarePass, Chrome extension, developer mode, install extension, load unpacked
---
# Install the LarePass browser extension
Install the LarePass browser extension to use Olares features while browsing, including webpage translation, password autofill, and saving online content.
## Prerequisites
- Install Google Chrome on your computer.
- Make sure you have an existing Olares ID. If you do not have one, [create an Olares ID](./get-started/create-olares-id.md) first.
## Download the extension
1. Open the [LarePass website](https://www.olares.com/larepass).
2. Find **LarePass for Chrome Extension**, then click **Download**.
3. Move the downloaded ZIP package to a folder where you plan to keep it, then continue with the installation.
:::warning Keep the installation files in place
Chrome continues to use the files from their location during installation. After installing LarePass, do not move, rename, or delete the ZIP package. If you use **Load unpacked**, do not move, rename, or delete the unzipped folder either.
:::
## Install and enable the extension
You can drag the ZIP package into Chrome for the quickest installation. If drag-and-drop does not work, unzip the package and load the folder instead.
### Drag and drop the ZIP package
1. In the Chrome address bar, enter `chrome://extensions/`.
2. Turn on **Developer mode** in the upper-right corner.
3. Drag the downloaded ZIP package onto the extensions page.
4. Confirm that LarePass appears on the extensions page and is enabled. Keep the ZIP package in its current location.
### Load the unpacked extension
Use this method if you cannot install the ZIP package by dragging it into Chrome.
1. Unzip the downloaded package without moving the ZIP package. Keep the unzipped folder in a permanent location as well.
2. On the `chrome://extensions/` page, turn on **Developer mode**.
3. Click **Load unpacked**.
4. Select the unzipped folder that contains the extension files.
5. Confirm that LarePass appears on the extensions page and is enabled.
## Pin the extension
1. Click the extensions icon in the Chrome toolbar.
2. Find LarePass, then click the pin icon.
3. Click the LarePass icon in the toolbar and confirm that the extension opens.
## Next steps
- [Import an existing Olares account](./larepass/manage-accounts.md#chrome-extension).
- After signing in, you can use LarePass features such as webpage translation, password autofill, and saving online content.
---
### Manual Login And Activation Errors (`docs/manual/login-and-activation-errors.md`)
---
outline: [2, 3]
description: Look up Olares login and activation error messages, understand what they indicate, and choose the next action.
head:
- - meta
- name: keywords
content: Olares, login error, activation error, authentication failed, MFA binding error, DID binding error, invalid jws
---
# Login and activation error messages
Use this reference when Olares or LarePass displays a specific error during activation or sign-in. Match the complete message whenever possible. If the message differs, record it exactly instead of assuming it has the same cause.
## Activation errors
### `MFA binding error`
The request to bind multi-factor authentication (MFA) timed out. Check that both the device running LarePass and the Olares device have stable internet access, then retry the activation step.
### `DID binding error`
The request to the identity binding service timed out during activation. Check the network connection on both devices, then retry.
### `Invalid jws, timestamp is out of range`
The time on the device running LarePass differs from the Olares host by more than the accepted range. Enable automatic date and time on both devices, confirm that the time zone and clock are correct, then retry.
### `Resolve name error`
The Olares host could not resolve or reach the Olares identity service. Check its internet connection and DNS configuration, then retry. If the error persists, record the time and the DNS servers in use before collecting diagnostics.
## Login errors
### `Authentication failed, incorrect password`
The password does not match the account. Check capitalization and typing. If you no longer know the password, follow [Forgotten desktop login password](help/ts-forget-login-password.md).
### `Authentication failed, user not found`
Olares cannot find the username you entered. Check the local name and domain of the Olares ID. For a team member, ask an administrator to confirm that the account exists under **Settings** > **Users**.
### `Authentication failed, failed to query user from lldap service`
Olares could not retrieve the user record from its internal identity service. Retry once. If the error persists, ask an administrator to confirm that the user exists, record the time of the attempt, and [collect diagnostic information](collect-diagnostic-information.md).
### `too many failed login attempts, retry again later after 5 minutes`
Olares temporarily blocked sign-in after repeated failures. Stop retrying, wait at least five minutes, then enter the confirmed password once.
### `Authentication failed, disk space is full`
The system disk has no usable free space, so the authentication service cannot complete sign-in. Follow [Free up disk space](free-up-disk-space.md), then try again.
### `Authentication failed, lldap service is unavailable`
The internal identity service is unavailable. Ask an administrator to check whether LarePass also shows **System error**, then follow ["System error" in LarePass](help/ts-system-error.md).
### `Authentication failed, citus service is unavailable`
The internal database service is unavailable. Ask an administrator to check the system state, then follow ["System error" in LarePass](help/ts-system-error.md).
## If the error is not listed
Record the complete message, the time and time zone, the installed Olares version, and whether the error occurred during activation or login. Then follow [Collect diagnostic information](collect-diagnostic-information.md). Do not post full logs, Olares IDs, IP addresses, domains, or account details in a public issue.
---
### Manual Manage System Env (`docs/manual/manage-system-env.md`)
---
description: Configure system-level environment variables in Olares to apply common settings globally for all applications, such as third-party API keys.
head:
- - meta
- name: keywords
content: Olares, system environment variables, OLARES_USER, API keys, global settings
---
# Set system environment variables
Starting from Olares version 1.12.2, you can configure system-level environment variables for applications. This allows you to apply common settings globally without having to configure them for each application individually.
The variables are divided into two main categories:
| Category | Description | Permissions |
|:-------- |:----------- |:----------- |
| System config | Predefined variables required for core system operations.
Example: `OLARES_SYSTEM_CDN_SERVICE` | You cannot delete them. The system locks and grays out some variables to ensure stability, but you can edit the values of others. |
| User information | Custom or predefined user-level variables, such as third-party API keys.
Example: `OLARES_USER_CUSTOM_OPENAI_APIKEY`| You can add, edit, and delete them. The system automatically applies the `OLARES_USER_` prefix to any custom keys you create. |
To manage environment variables:
1. Go to **Settings** > **Advanced** > **System environment variables**.
{width=65%}
2. To add a new custom variable:
a. Click **Add environment variables**.
b. In the **Key** field, enter your custom key name which is appended to the `OLARES_USER_` prefix.
c. In the **Value** field, fill in the value.
d. From the **Type** list, select the data type.
e. Provide an optional description.
f. Click **Save**.
g. Click **Apply** at the bottom of **System environment variables**.
3. To modify a variable:
a. Find the target variable from the list, and then click edit_square. Variables without this icon are locked and cannot be changed.
b. In the **Edit environment variable** window, update the variable's value.
c. Click **Confirm** to save your changes.
d. Click **Apply** at the bottom of **System environment variables**.
4. To delete a variable:
a. Locate a user-level variable and click delete.
b. Click **Confirm**.
c. Click **Apply** at the bottom of **System environment variables**.
---
### Manual Migrate Shared Apps (`docs/manual/migrate-shared-apps.md`)
---
outline: [2, 3]
description: Choose and complete the correct migration path for a legacy v2 shared application installed before Olares 1.12.6.
head:
- - meta
- name: keywords
content: Olares, migrate shared applications, v2 shared app, ComfyUI, Dify, OnlyOffice, SearXNG, Xinference, Ollama
---
# Migrate legacy shared applications
Use this guide if a shared application was installed before Olares 1.12.6 and you want to move to its current shared-app architecture. Legacy v2 apps continue to run after the Olares update, but they cannot be upgraded in place.
For an explanation of the current architecture, see [About shared applications](olares/market/shared-apps.md).
:::warning Check app data before uninstalling
Uninstalling a legacy shared app can remove data that the new app cannot restore directly. Identify the app and complete the applicable export or backup steps before uninstalling it.
:::
## Identify a legacy v2 app
Open the app details page in Market and check **Compatibility** in the **Information** panel:
- A legacy v2 shared app typically shows `Olares >=1.12.3-0, <1.12.6`.
- A current shared app shows `Olares >=1.12.6-0`.
If the app does not match these ranges, do not use this guide. Record the app and chart versions before choosing a migration path.
## Choose a migration path
| App or data state | Migration path |
|---|---|
| ComfyUI | Use the app's automatic migration workflow |
| Falco, MTranServer, or another app with no user-created data | Confirm that no data must be preserved, then reinstall |
| Dify, OnlyOffice, SearXNG, or Xinference | Export or back up app-specific data, then restore it into the new app |
| Standalone Ollama shared app | Re-create the required model on an Engine Base app, then reconnect clients |
## Migrate ComfyUI
Follow [ComfyUI migration notes](/use-cases/comfyui-common-issues.md) to run the supported migration and confirm the new data locations before removing the old app.
## Reinstall an app with no data to preserve
Use this path only after confirming that the app contains no user-created data, settings, or workflows that you need.
1. Record the legacy app name and version.
2. Uninstall the legacy v2 app.
3. Find the current shared app in Market and confirm that its compatibility range starts with `Olares >=1.12.6-0`.
4. Install the current shared app and open it from the Launchpad.
## Migrate app data manually
The data that can be preserved differs by app. Complete the app-specific guide before uninstalling the legacy app:
- [Migrate Dify](/use-cases/dify-upgrade.md)
- [Migrate OnlyOffice](/use-cases/onlyoffice-migration.md)
- [Migrate SearXNG](/use-cases/searxng.md)
- [Migrate Xinference](/use-cases/xinference.md)
Do not restore an old app data directory into a new version unless its migration guide explicitly requires it.
## Move from Ollama to Engine Base
1. Note the models and client applications that use the standalone Ollama shared app.
2. Deploy each required model with an [Engine Base app](/use-cases/llm-base-apps.md).
3. Open the model console and copy the new **Base URL**.
4. Replace the Ollama endpoint in each client application with the new Base URL.
5. Send a test request from each client. Remove the old Ollama app only after the clients use the new model successfully.
---
### Manual Mount Local Disk (`docs/manual/mount-local-disk.md`)
---
description: Manually mount an HDD or SSD under /olares/share on the Olares host to use it as independent external storage for large files and AI models.
head:
- - meta
- name: keywords
content: Olares, mount HDD, mount SSD, /olares/share, fstab, external disk, Linux mount
---
# Mount a local disk
You can manually mount an HDD or SSD to Olares from your **Linux** hosting system.
This approach is recommended for **large data storage** (e.g., AI models) or **long-term storage expansion**.
## Prerequisites
Please ensure the following:
- You have **administrator (sudo) privileges** on your Linux system.
- **Olares** is properly installed and running.
- The target drive is **already formatted** (recommended file systems: `ext4` or `XFS`).
:::tip Mount path restriction
Currently, only mounts under the `/olares/share` directory are supported.
Mounting flexibility will be improved in future versions.
:::
## Identify the drive
1. Insert the hard drive into the host machine.
2. Run the following command to view detected drives:
```bash
fdisk -l
```
3. Identify the target drive type and device name from the output:
- **NVMe SSD**: typically appear as `/dev/nvme0n1`, `/dev/nvme1n1`, etc.
- **SATA** or **HDD**: typically appear as `/dev/sda`, `/dev/sdb`, etc.
Each drive lists its partitions under the Device column, such as `/dev/nvme1n1p1`, `/dev/nvme1n1p2`, or `/dev/sdb1`.
4. Confirm the target partition to mount (e.g., `/dev/nvme1n1p1`).
## Temporarily mount a partition
Temporary mounting is suitable for **one-time** or **short-term** use (e.g., file transfer).
The mount configuration will be lost after a Linux or Olares reboot.
1. Create a mount directory:
```bash
sudo mkdir -p /olares/share/
```
Replace `` with a custom name.
2. Mount the partition:
```bash
sudo mount /dev/ /olares/share/
```
**Example**:
```
sudo mount /dev/nvme1n1p1 /olares/share/hdd0
```
3. Verify the mount result:
After successful mounting, you can access the partition from **Files** > **External**.
## Permanently mount a partition
If you want the mount configuration to remain after reboot, configure **automatic mounting** in `/etc/fstab`.
1. Run the following command to list all drives and find the target partition:
```bash
lsblk -f
```
Record the following information:
- **FSTYPE**: File system type (e.g., `ext4`, `xfs`).
- **UUID**: Unique identifier of the partition.
2. Create a mount directory:
```bash
sudo mkdir -p /olares/share/
```
Replace `` with a custom name.
3. Edit the mount configuration file:
```bash
sudo vi /etc/fstab
```
4. Add a mount entry using **UUID** (recommended to prevent issues if device names change):
```
UUID= /olares/share/ defaults,nofail 0 0
```
**Example**:
```
UUID=1234-ABCD /olares/share/my_disk ext4 defaults,nofail 0 0
```
5. Save and exit the editor.
6. Verify the configuration (recommended):
```bash
mount -a
```
If no errors appear, the setup is successful.
7. After reboot, confirm the drive is automatically mounted via **Files** > **External**.
:::warning
An incorrect /etc/fstab configuration may prevent your system from booting.
It is strongly recommended to run `mount -a` first to validate the configuration before rebooting.
:::
## Unmount a partition
You can unmount partitions mounted using either temporary or permanent methods.
1. Unmount the partition:
```bash
sudo umount /olares/share/
```
:::tip NOTE
Make sure no programs or terminals are accessing the directory before unmounting.
:::
2. Remove the empty directory (optional):
```bash
rm -rf /olares/share/
```
:::warning
Ensure the directory is empty and fully unmounted before deleting.
:::
You can also view and remove this directory from **Files** in Olares.
---
### Manual Olares Vs Nas (`docs/manual/olares-vs-nas.md`)
---
noindex: true
outline: [2, 3]
description: Compare Olares with traditional NAS platforms across storage, apps, virtual machines, networking, and local AI capabilities.
---
# Compare Olares and NAS
Olares is dedicated to creating a one-stop personal cloud experience. Its core functionalities and user positioning are significantly different from traditional Network Attached System (NAS).
This document provides a detailed comparison between Olares and general NAS systems. We will highlight key differences in storage solutions, application ecosystem, virtual machine support, network configuration, and AI capabilities, using Unraid and Synology DSM as reference points.
## Overview
| Attribute | Olares | NAS |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Introduction | Olares is an open-source personal cloud operating system. | NAS systems are primarily used for network storage, allowing flexible hardware configurations to manage data and applications. |
| Positioning | Focuses on helping users deploy and manage digital assets locally as an alternative to public cloud services. It supports running powerful open-source applications locally, providing users with robust cloud computing capabilities while ensuring complete data control and privacy. | Focuses on individuals and small businesses, solving low-cost data storage reliability issues, but has limitations in application hosting and network security. |
| Target users | Regular users without a technical background | Geek users and small and medium business users |
| Transparency | Open-source or source available | Usually closed-source |
| Openness | No vendor lock-in | Closed ecosystem |
| Application security | Supports application sandboxing, isolating network, storage, and computing resources. Permissions must be declared and user authorization obtained during installation. | No application sandboxing. Most third-party applications run with root privileges, and users bear the security risks themselves. |
| Network security | Provides public and private access, using reverse proxy and VPN to achieve service security. | Only supports external access for limited system applications by default. Custom solutions by users may pose security risks. |
| Developer friendliness | Provides development tools with familiar technology stacks to deploy services and develop applications. | Does not support developer tools or application development. |
| AI | 1. Advanced GPU management (v1.12) 2. One-click installation support for over 30 AI applications and models 3. Supports inter-application and model calls 4. Supports MCP (v1.12) | ❌ |
## Project information
| Attribute | Olares | Unraid | Synology DSM |
| ---- | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Year | 2022 | 2005 | 2000 |
| Open Source | ✅ | ❌ | ❌ |
| Price | Free | 30-day trial, then requires a one-time paid license | OS sold bundled with hardware |
| Positioning | Open-source personal cloud OS that focuses on helping users deploy and manage digital assets locally as an alternative to public cloud services. | Network storage OS, allows flexible hardware configurations, simple and convenient management of data, VMs, and Docker applications | Provides secure and efficient data management systems for businesses of different scales, helping enterprises control growing data streams |
## Storage features
| Feature | Olares | Unraid | Synology DSM |
| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
| Disk types | System space, user space, application space, and application cache are on SSD | System runs on SSD, data stores on HDD |System runs on SSD, data stores on HDD |
| Storage pool | ❌ | Supports Parity-protected array similar to JBOD | Supports SHR, Basic, JBOD, RAID 0, RAID 1, RAID 5, RAID 6, RAID 10, and RAID F1 |
| LAN file sharing | SMB | SMB, NFS | SMB, NFS, AFP, FTP |
| Public file sharing | via Files application | ❌ | via File Station application |
| Distributed file system | ✅ | ❌ | ❌ |
| Mount external cloud drives | Supports mounting Google Drive, Dropbox, S3, etc. | ❌ | Supports mounting Google Drive, Dropbox, S3, etc. |
| Sync drive | ✅ (Seafile integrated) | ❌ | Synology Drive |
| Mount SMB directory | ✅ | ❌ | ❌ |
| Mount mobile storage devices | Auto-mount | Manual mount | Auto-mount |
| Structured data support | Supports mainstream databases and data warehouses (e.g., Redis, PostgreSQL),suitable for production environments | Can be manually installed, but not recommended for production environments | Can be manually installed, but not recommended for production environments |
| Local data security | No protection in single-node; disk data protection via Minio or Ceph in cluster mode | Allows 1-2 disk failures depending on configuration, but Parity disk must not fail | Allows 1-2 disk failures depending on RAID configuration |
| Remote backup | Supports periodic incremental encrypted backups via Restic | Flash drive can be manually backed up, but there is no official backup solution for data drives | Supports multiple official backup solutions |
## Application management
| Feature | Olares | Unraid | Synology DSM |
| ---------------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------ |
| Installation format | Olares package format based on improved Helm | Dockerfile or Docker Compose | Dockerfile or Docker Compose |
| App store | Rich community app ecosystem with application sandboxing | Rich apps with no sandboxing restrictions. | Fewer apps, extendable via third-party stores |
| Application sandbox | ✅ | ❌ | ❌ |
| Developer tools | OAC packaging and CLI tools | ❌ | ❌ |
| Middleware sharing | Supports mainstream middleware like PostgreSQL, MongoDB, and Redis | ❌ | ❌ |
| Cluster application support | ✅ | ❌ | ❌ |
| LDAP integration | ✅ (Requires third-party adaptation) | ❌ | ❌ |
| Unified SSO login | ✅ | ❌ | ❌ |
| Secret management | ✅ | ❌ | ❌ |
## Virtual machine management
| Feature | Olares | Unraid | Synology DSM |
| ------------- | --------------------------------------------------------------------- | ------------------------------ | ------------- |
| Install via ISO | Not yet supported, will be supported via Kubevirt | ✅ | ✅ |
| Windows | One-click install from app store, auto-integrates Tailscale, for secure external RDP access | Install via ISO | Install via ISO |
| Steam | Supported in app store, auto-configures GPU mounting, streaming, and external access | Requires manual configuration for GPU passthrough, etc. | ❌ |
| Linux | Supported through containerized workloads | Install via ISO | Install via ISO |
| Android | Supported via redroid | ❌ | ❌ |
| Mac | Coming soon | ❌ | ❌ |
| Openwrt | Coming soon | ❌ | ❌ |
## Network access
| Feature | Olares | Unraid | Synology DSM |
| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Reverse proxy | Integrated Cloudflare Tunnel and FRP, supports independent domain access for all apps | Only supports access to limited system services | Only supports access to limited system services |
| DDNS | No configuration needed | Manual configuration required. Supports domain+port access for non-system apps, but practically cannot provide external services. | Manual configuration required. Supports domain+port access for non-system apps, but practically cannot provide external services. |
| Custom domain support | ✅ | ❌ | ❌ |
| Firewall | Integrated Cloudflare firewall | ❌ | ❌ |
| Free HTTPS certificate | ✅ | ✅ | ✅ |
| Two-Factor Authentication Login | ✅ | ✅ | ❌ |
| Different security policies for different directories | ✅ | ✅ | ❌ |
| Private Access Endpoint | ✅ | ✅ | ❌ |
| VPN connection | No configuration needed, Tailscale integrated | Manual configuration required | Manual configuration required |
| VPN-only access mode | ✅ | ❌ | ❌ |
## AI capabilities
| Feature | Olares | Unraid | Synology DSM |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ |
| GPU management | 1. Supports heterogeneous GPU clusters across multiple nodes (v1.12) 2. Nvidia GPUs support memory slicing and time-slicing sharing modes (v1.12) | Supports GPU passthrough on a single node via manual configuration | ❌ |
| Models | 1. Supports mainstream language, image, video, and voice models, such as Ollama, VLLM, ComfyUI, SD, Whisper, and ACE-STEP. 2. Supports mainstream open-source AI tools, such as Dify, Ragflow, MaxKB, and LobeChat. | ❌ | ❌ |
| Interoperability | 1. Supports mutual calls between applications and models 2. System-level support for MCP calls (v1.12) | ❌ | ❌ |
---
### Manual Password And Devices (`docs/manual/password-and-devices.md`)
---
description: Change your Olares login password, set the network access policy, manage signed-in devices, and log out from the My Olares page.
head:
- - meta
- name: keywords
content: Olares, Settings, My Olares, change password, two-factor, network access policy, signed-in devices, log out
---
# Change your password and manage signed-in devices
On the **My Olares** page in **Settings**, you can manage account security for your Olares. To access it, open **Settings** and click your avatar in the top-left corner.
## Change password
To update your Olares login password, click **Change password** on the **My Olares** page.
## Set network access policy
Define system-level access and authentication policies to control how users connect to your Olares.
* **Two-factor** (Recommended): Requires both your login password and a two-factor authentication code for enhanced security.
* **One-factor**: Only requires your login password.
## Manage signed-in devices
View devices that are authorized to access your Olares. Each device entry shows the device name and client type. Select a device to view more details or manage its access.
## Log out
Click **Log out** to sign out of the current Olares session. You need to log in again before accessing Olares from this device.
---
### Manual Release Notes (`docs/manual/release-notes.md`)
---
description: Track the latest Olares documentation changes, including new guides, updates, deprecations, and moved pages.
head:
- - meta
- name: keywords
content: Olares, documentation updates, what's new, new guides, deprecations, release notes
---
# What's new in docs
This page highlights documentation changes after each Olares release that affect how you use Olares. It focuses on new guides, major updates, and deprecations. Minor corrections and clarifications are not listed here.
The docs are built and published from the `main` branch of the [Olares GitHub repository](https://github.com/beclab/Olares/tree/main/docs), so they always reflect the latest documentation changes.
For Olares OS software release notes, see the GitHub releases page.
- [Olares 1.12.7](https://github.com/beclab/Olares/releases/tag/1.12.7)
- [Olares 1.12.6](https://github.com/beclab/Olares/releases/tag/1.12.6)
- [Olares 1.12.5](https://github.com/beclab/Olares/releases/tag/1.12.5)
To stay informed of Olares news, including documentation updates, follow Olares on X or join the [Discord community](https://discord.com/invite/BzfqrgQPDK).
## Olares 1.12.7
Released: September 28, 2026
For the software changes, see the [Olares 1.12.7 release notes](https://github.com/beclab/Olares/releases/tag/1.12.7).
For release highlights and walkthroughs, see the [Olares 1.12.7 blog post](https://www.olares.com/blog/olares-1-12-7/).
### New docs
- Added [What to do after updating to Olares 1.12.7](/manual/update-guides/1.12.7), covering the upgrade path, Router and Lares setup, and agent app updates.
- Added [Use Olares Router as your AI gateway](/use-cases/olares-router), introducing model and tool capabilities, caller authentication, model naming, and connection details.
- Added [Manage Olares and run research tasks with Lares](/use-cases/lares), covering first tasks, permissions, and web research tools configured through Router.
- Added [Install the LarePass browser extension](/manual/install-larepass-browser-extension) and [Translate webpages privately with LarePass](/manual/tutorial/translate-webpages-with-larepass), for translating pages with a local model through Router.
- Added [Save resources to Olares](/manual/larepass/save-resources-to-olares), covering Fetch in LarePass Desktop for web links, torrents, Hugging Face repositories, and supported media.
- Added [Create and manage support tickets in Olares Space](/manual/space/tickets) and expanded [Get support](/manual/help/request-technical-support) with the Ticket app, log collection, and follow-up replies.
- Added [Recover access to LarePass, Olares Desktop, or your Olares device](/manual/help/ts-access-without-mnemonic), alongside updated [password reset instructions](/manual/help/ts-forget-login-password).
- Added [Create a Blender scene with Lares](/use-cases/blender) and [Create videos with Concat and Lares](/use-cases/concat), covering MCP setup, creative workflows, and saving outputs in Files.
- Added [Open Design](/use-cases/open-design), [Codex CLI](/use-cases/codex-cli), and [Manage Olares from OpenCode](/use-cases/opencode-olares-cli) tutorials for design, coding, and device management.
- Added [Minecraft](/use-cases/minecraft) and [Palworld](/use-cases/palworld) server guides with Overlay Gateway setup for local network access.
### Updated docs
- Rewrote [Connect your apps to AI capabilities](/manual/best-practices/connect-ai-apps) for Router, covering API formats, model and tool setup, default system names such as `default-chat`, and API keys for external clients.
- Updated AI client tutorials for the Router workflow, using Qwen3.8-27B (llama.cpp) as the chat example. Added an on-page version selector to affected guides so readers can choose the Olares 1.12.7 or 1.12.6 instructions.
- Reorganized the [Olares manual](/manual/overview) around user tasks and [installation guidance](/manual/get-started/install-olares) around Linux, Olares One, and DGX Spark setup paths. Updated [Olares One onboarding](/one/olares-onboarding) for Lares.
- Updated [local access guidance](/manual/best-practices/local-access) with LarePass host mappings on Windows and macOS, alongside VPN and `.local` access options.
- Updated [Market](/manual/olares/market/market) with app and model discovery and source selection, and [language settings](/manual/olares/settings/language-appearance) with the additional language options.
- Reworked [Olares Space account management](/manual/space/manage-accounts), [resource and traffic monitoring](/manual/space/manage-olares), and [billing](/manual/space/billing) instructions.
- Reworked [eGPU guidance for Olares One](/one/egpu) with separate Olares OS and Windows setup guides, compatibility information, and troubleshooting. The [Olares One FAQ](/one/faq#does-olares-one-support-out-of-band-management) now explains which out-of-band management capabilities are available.
- Updated [Jellyfin](/use-cases/jellyfin) hardware acceleration, [Steam streaming](/use-cases/steam-stream) network setup, and [Penpot](/use-cases/penpot) integration with its built-in MCP server.
### Retired docs
- Retired the standalone Ollama use-case guide, following the deprecation announced in Olares 1.12.6. Use [Ollama Engine Base](/use-cases/llm-base-apps) for new model deployments. Existing Ollama guide URLs redirect to the Engine Base guide.
### Moved and consolidated docs
- Consolidated backup and restore instructions in [Back up and restore Olares](/manual/olares/settings/backup). Previous restore and Olares Space backup links redirect to this guide.
- Split the former My Olares topic into [password and device management](/manual/password-and-devices) and [Olares One hardware settings](/one/hardware-settings).
- Consolidated Olares ID creation in [Create an Olares ID](/manual/get-started/create-olares-id), and moved integration instructions into task-specific guides such as [Mount cloud storage](/manual/olares/files/mount-cloud-storage). Previous links redirect to the replacement pages.
## Olares 1.12.6
Released: July 23, 2026
For the highlights and walk-through of Olares v1.12.6, see the [Olares 1.12.6 blog post](https://www.olares.com/blog/olares-1-12-6/).
### New docs
- Added [Olares CLI overview](/developer/cli-overview), an introduction to managing Olares from the command line.
- Added [Use Olares CLI with AI agents](/developer/cli-install), covering installation, login, and the first AI agent task.
- Added [Olares CLI Agent Skills](/developer/cli-agent-skills), describing the built-in skills for cluster management, apps, settings, and more.
- Added [Install and activate Olares from the command line](/manual/best-practices/activate-olares-using-cli), for setting up a device with Olares CLI.
- Added [Manage shared AI models with the Common directory](/manual/olares/files/files-common), explaining how to use the Common directory for models shared across apps.
- Added [Compress and extract files](/manual/olares/files/compress-extract-files), covering ZIP, 7z, TAR, and password-protected archives in Olares Files.
- Added [Mount NFS shares](/manual/olares/files/mount-nfs), for accessing NFS shared directories from Olares.
- Added [About shared applications](/manual/olares/market/shared-apps), explaining the new shared app architecture, and [Migrate legacy shared applications](/manual/migrate-shared-apps), covering migration options for v2 apps.
- Ollama
- [ComfyUI](/use-cases/comfyui-common-issues)
- [Dify](/use-cases/dify-upgrade)
- [OnlyOffice](/use-cases/onlyoffice-migration)
- [SearXNG](/use-cases/searxng)
- [Xinference](/use-cases/xinference)
- Added [Configure Overlay Gateway](/manual/olares/settings/overlay-gateway), for managing Overlay Gateway settings.
- Added [Olares One onboarding](/one/olares-onboarding), a guided walkthrough for managing Olares One through natural language.
- Added [Desktop widgets](/manual/olares/desktop#widgets), documenting the new widgets on the Olares desktop.
- Added [Run local AI models with Engine Base apps](/use-cases/llm-base-apps), for deploying and running local AI models on Olares.
- Added [Home Assistant with Overlay Gateway](/use-cases/home-assistant#enable-the-overlay-gateway), for accessing Home Assistant over the local network.
- Added [Jellyfin with Overlay Gateway](/use-cases/jellyfin#enable-overlay-gateway-for-jellyfin), for accessing Jellyfin over the Overlay Gateway.
- Added [Update notes for *Arr apps](/use-cases/arrs-upgrade), covering the configuration changes required after the Olares v1.12.6 internal entrance update.
### Updated docs
- Rewrote [Connect AI apps](/manual/best-practices/connect-ai-apps) to align with the v1.12.6+ architecture.
- Consolidated Olares One software documentation into the main manual and versioned the ISO download links.
- Updated [My Olares](/one/hardware-settings), adding the **Limit CPU frequency** and **Automatic startup** toggles under **My Hardware**.
- Updated [Basic file operations](/manual/olares/files/add-edit-download) with new sorting options, Markdown editing, preview, and additional supported formats.
- Updated [Managing accelerator resources](/manual/olares/settings/gpu-resource) to cover GPU and other accelerator resources.
- Updated [Manage BIOS and EC](/one/update-firmware) with EC 1.03 and BIOS 1.05 changelogs, including the note that **Automatic startup** requires Olares OS 1.12.6 or later.
- Updated [ComfyUI](/use-cases/comfyui) with migration steps and the new v1.12.6 directory structure.
- Updated [App submission guide](/developer/develop/submit-apps) to reflect the new packaging and submission workflow.
- Updated [OlaresManifest Specification](/developer/develop/package/manifest) to document the `0.12.0` schema, including new fields such as `apiVersion`, `accelerator`, `workloadReplicas`, `overlayGateway`, `LLMGatewaySupported`, `appCommon`, and `externalData`, plus deprecated fields.
- Standardized the local model and service connection workflow across AI use-case guides. AI use-case guides now connect to models through the Model Console instead of relying on the standalone Ollama app or individual model apps.
### Deprecated docs
- Added a deprecation notice to the Ollama use-case guide because the standalone Ollama app was removed from Market in Olares 1.12.6.
- Retired the Olares CLI reference pages. The deprecated pages have been superseded by the [Olares CLI overview](/developer/cli-overview), [Use Olares CLI with AI agents](/developer/cli-install), and [Olares CLI Agent Skills](/developer/cli-agent-skills).
- Retired all Studio documentation. Studio is no longer available in Market. Use [Olares CLI Agent Skills](/developer/cli-agent-skills) and the [App submission guide](/developer/develop/submit-apps) for the new packaging and porting workflow.
- The **Allow subnet routing** feature is temporarily disabled in Olares 1.12.6, and the related documentation has been removed from [Configure VPN access to Olares](/manual/olares/settings/remote-access#allow-subnet-routing). The feature will return in a future release.
- Retired the DeerFlow use-case guide. The DeerFlow app was replaced by [DeerFlow 2.0](/use-cases/deerflow2).
### Upcoming deprecations
- The Ollama use-case guide will be removed in a future release. The standalone Ollama app was already removed from Market in Olares 1.12.6, and AI use-case guides now connect to models through the Model Console.
---
### Manual Update App Image (`docs/manual/update-app-image.md`)
---
outline: [2, 3]
description: Manually update an application's Docker image in Control Hub when the version you need is not yet available in the Market, and roll back if issues occur.
head:
- - meta
- name: keywords
content: Olares, update app image, Control Hub, container image, rollback, Docker image
---
# Manually update an app image
We recommend always updating applications through the Olares Market to ensure stability and compatibility. In some cases, an application might show an internal prompt for a new update before it is officially available in the Market. If you urgently need the latest features, you can manually update the application's Docker image in Control Hub.
Before proceeding, review the following notes:
- **Temporary changes**: Manual edits to configurations in Control Hub are not persistent. When you apply an update through the Market later on, the Market version will overwrite all your manual configurations, including the image version.
- **Unexpected behavior**: After the manual update, the application might fail to start or run correctly due to compatibility issues.
:::warning Compatibility & privileges
- The official image might not be fully adapted for Olares because configuration paths or environment variables can vary.
- If the application requires root or other special privileges, using images from other organizations might prevent the application from starting due to permission restrictions.
:::
The following steps demonstrate how to manually update using Ollama as an example.
1. Find the official Docker image name and the latest release tag.
2. Note down the image name and tag. For example, `ollama/ollama` and `0.23.1`.
3. Open Control Hub, go to **Browse** > **System** > **ollamaserver-shared** > **Deployments** > **ollama**, and then click edit_square.
4. In the YAML editor, find the `containers` section, and then note down the current image and tag in case you need to roll back later. For example, `docker.io/beclab/ollama-ollama:0.20.5`.
5. Update the field to the new official image name and tag. For example, change `docker.io/beclab/ollama-ollama:0.20.5` to `docker.io/ollama/ollama:0.23.1`.
6. Click **Confirm**. The system will automatically pull the new image and restart the pod. Large images might take several minutes to download. Once complete, the pod status returns to **Running**.
7. Open the container's Terminal in Control Hub and run the version command `ollama -v` to confirm the update.
:::warning Potential conflicts
`beclab` images are provided by Olares for easier access. However, because some updates include environment adaptations, manually pulling a new version might cause configuration mismatches with your current setup. As a result, the application might fail to start or function correctly.
:::
For some frequently updated AI applications, Olares might have already mirrored the latest image to the official registry but hasn't manually pushed the chart update to the Market yet.
The following steps demonstrate how to manually update using OpenClaw as an example.
1. Go to the official [Olares Docker registry](https://hub.docker.com/u/beclab).
2. Search for `OpenClaw`, go to its details page, check the **Tags** tab, and then note down the latest version tag. For example, `2026.5.7`.
3. Open Control Hub, go to **Browse** > **{Username}** > **clawdbot-{Username}** > **Deployments** > **clawdbot**, and then click edit_square.
4. In the YAML editor, find the `containers` section, and then note down the current image and tag, in case you need to roll back later. For example, `beclab/openclaw-openclaw:2026.3.12`.
5. Update only the version tag of the existing `beclab` image. For example, change `beclab/openclaw-openclaw:2026.3.12` to `beclab/openclaw-openclaw:2026.5.7`.
6. Click **Confirm**. The system will automatically pull the new image and restart the pod. Large images might take several minutes to download. Once complete, the pod status returns to **Running**.
7. Open the container's Terminal in Control Hub and run the version command `openclaw -v` to confirm the update.
:::tip Rollback
If the application fails to start or experiences compatibility issues after the manual update, you can revert it by editing the YAML again to restore the old image tag using the one you noted down earlier. For example, change `docker.io/ollama/ollama:0.23.1` back to `docker.io/beclab/ollama-ollama:0.20.5`.
:::
---
### Manual Use Usb Drive (`docs/manual/use-usb-drive.md`)
---
description: Use USB drives with Olares. Olares automatically mounts inserted USB storage devices, and you can access or eject them from Files.
head:
- - meta
- name: keywords
content: Olares, USB drive, external storage, auto-mount, eject USB
---
# Use a USB drive
Olares automatically detects and mounts inserted USB storage devices.
- Once you insert a USB device, it will be mounted automatically. No command-line operations are required.
- You can access it in **Files** > **External** from both Olares and LarePass.
- The system automatically unmounts the device when you unplug it.
- You can manually eject the device via the Olares web interface. Right-click the USB drive in Files and select **Unmount**.
---
### Manual What Is Olares (`docs/manual/what-is-olares.md`)
---
noindex: true
description: "Learn what Olares is: an open-source personal cloud OS that brings public-cloud power to your own hardware, so your data, apps, and local AI stay fully yours."
---
# What is Olares
Olares is the sovereign cloud that puts you in control. It's an open-source, self-hosted alternative to public clouds like AWS, built to reclaim your data ownership and privacy. By combining the power of Kubernetes with a streamlined interface, Olares enables you to take full control of your data and computing resources. Whether you're managing a homelab, hosting applications, or safeguarding your privacy, Olares delivers the flexibility and capabilities of public clouds, without compromising privacy or security.
## What can you do with Olares
Typical use cases of Olares include:
- 🖥️ **Homelab server**: Turn your personal devices into a versatile homelab for experimenting with containerized applications, running local AI models, managing self-hosted services, or testing cloud technologies—all within your own private infrastructure.
- 🤖 **Local AI**: Host and run cutting-edge open-source AI models—including large language models, image generation, and speech recognition—directly on your devices. Build custom AI assistants that integrate with your data and applications while keeping everything private and secure.
- 💻 **Personal data repository**: Securely store, sync, and manage your photos, documents, and important files in a unified, private storage system accessible from anywhere.
- 🛠️ **Self-hosted workspace**: Create a free, collaborative workspace for your team or family with open-source alternatives to commercial productivity tools.
- 🎥 **Private media server**: Turn your personal media collection into your own streaming service, hosted entirely on your devices.
- 🏡 **Smart home**: Use Olares as the central control point for managing IoT devices and home automation.
- 🤝 **Decentralized social media**: Host decentralized social media platforms like Mastodon, Ghost, or WordPress to build your personal brand without the risks of bans or platform fees.
---
### One Access Olares Via Local Domain (`docs/one/access-olares-via-local-domain.md`)
---
outline: [2, 3]
description: Learn how to access Olares One directly from a computer on the same local network.
head:
- - meta
- name: keywords
content: Olares One, local access, host mappings, .local domain, LAN
---
# Access Olares One on your local network
When your computer is on the same local network as Olares One, you can keep traffic on the LAN instead of routing it through the public reverse proxy. This provides faster access and lets you reach your apps when the internet is unavailable.
## Before you begin
- Make sure Olares One and your computer are on the same local network.
- To use LarePass host mappings, install LarePass Desktop on Windows or macOS and import your Olares ID.
## Find the right method
| If this applies to you | What to do |
| --- | --- |
| You want to keep using standard `olares.com` URLs on this computer | [Configure local access with LarePass](#configure-local-access-with-larepass). |
| You use macOS or iOS and do not want to use LarePass | [Use a `.local` URL](#use-a-local-url-without-larepass). |
| You regularly move between local and remote networks | [Use LarePass VPN](./access-olares-via-vpn.md). |
## Configure local access with LarePass
## Use a .local URL without LarePass
On macOS or iOS, local service discovery can resolve multi-level `.local` hostnames without additional configuration. Open a URL such as:
```text
http://desktop..olares.local
```
On Windows, use LarePass Desktop to configure the multi-level `.local` hostname.
## Troubleshooting
## Learn more
- [Access Olares services locally](../manual/best-practices/local-access.md): Compare all local access methods and find FAQs and troubleshooting steps.
---
### One Access Olares Via Vpn (`docs/one/access-olares-via-vpn.md`)
---
outline: [2,3]
title: Access Olares One with LarePass VPN
description: Access Olares One securely with LarePass VPN and verify the connection type on local or remote networks.
head:
- - meta
- name: keywords
content: Olares, LarePass VPN, local access
---
# Access Olares One services securely using LarePass VPN
Typically, you access Olares services through a browser using a URL like `https://desktop..olares.com`. This way, you can reach your services from any device at any time.
While this address works from anywhere, it's recommended to enable the LarePass VPN to ensure your connection is always secure and efficient. The client automatically detects your network environment and selects the best connection method:
- **At home**: It establishes a direct **Intranet** connection to allow faster file transfers on your local network.
- **From remote**: It switches to a secure encrypted tunnel to ensure you remain connected safely when accessing remotely.
## Prerequisites
**Hardware**
- Your Olares One is set up and accessible.
- A client device (computer or mobile phone) with internet access.
## Step 1: Download LarePass
## Step 2: Enable LarePass VPN
Once installed, enable the VPN directly on the device.
## Step 3: Verify the connection type
## Troubleshooting
---
### One Access Physical Console (`docs/one/access-physical-console.md`)
---
outline: [2, 3]
description: Learn how to access the Olares One host terminal for command-line usage by logging in directly with a monitor and keyboard.
head:
- - meta
- name: keywords
content: Olares One, terminal, physical console, monitor, keyboard
---
# Access Olares One terminal physically
If network access or SSH is unavailable, you can log in to the Olares One device physically using a monitor and keyboard.
## Prerequisites
- Your Olares One is set up and powered on.
- A monitor and keyboard connected to Olares One.
- If Olares OS is activated, a mobile device with the LarePass app installed is required to retrieve the login password from Vault.
## Step 1: Prepare your login password
:::info Not the same as your Olares Desktop password
This password logs you in to the Olares One host system. It's different from the password you use to sign in to the Olares Desktop in your browser.
:::
The default login password is `olares`. After you activate Olares OS, you will be prompted to reset the SSH password on the LarePass app, and the new password is automatically generated and saved to your Vault.
Identify your password based on your activation status.
If you have not activated Olares OS yet, use the default password `olares`.
If you have already activated Olares OS, obtain the saved password from the LarePass mobile app.
## Step 2: Log in
:::info
For security, characters will not appear on the screen as you type.
:::
1. In the text-based login prompt displayed on your connected monitor, type the username `olares`, and then press **Enter**.
```text
olares login:
```
2. Type the password obtained in Step 1, and then press **Enter**.
---
### One Access Terminal Control Hub (`docs/one/access-terminal-control-hub.md`)
---
outline: [2, 3]
description: Learn how to access the Olares One host terminal for command-line usage via Olares CLI built into the Control Hub.
head:
- - meta
- name: keywords
content: Olares One, terminal, Olares CLI, Control Hub
---
# Access Olares One terminal via Control Hub
If you need to run quick, occasional commands, use the Olares CLI. This web-based terminal is built into the Control Hub application. It runs as `root` by default and requires no SSH client or IP address configuration.
## Prerequisites
- Your Olares One is set up and running.
- You can open the Olares desktop in a browser.
## Access via Olares CLI
1. Open a browser and access your Olares desktop:
```text
https://desktop..olares.com
```
2. Open Control Hub from the Launchpad.
3. In the left sidebar, under the **Terminal** section, click **Olares**.
{width=90%}
## Learn more
- [Olares CLI](../developer/cli-overview.md)
- [Manage Olares with Control Hub](../manual/olares/controlhub/index.md)
---
### One Access Terminal Ssh (`docs/one/access-terminal-ssh.md`)
---
outline: [2, 3]
description: Learn how to access the Olares One host terminal for command-line usage via SSH.
head:
- - meta
- name: keywords
content: Olares One, terminal, SSH
---
# Access Olares One terminal via network (SSH)
Secure Shell (SSH) establishes an encrypted session over the network, allowing you to run command-line operations on Olares One from your own computer.
You can connect over your local network, or use LarePass VPN to connect securely from a different location.
## Prerequisites
**Hardware**
- Your Olares One is set up and connected to a network.
- A client device, such as a computer, to access the terminal.
- A mobile device with the LarePass app installed.
**Experience**
- Basic familiarity with terminal commands and the command-line interface (CLI).
## Connect over your local network
Follow these steps if your device and your Olares One are on the same local network.
### Step 1: Get the local IP address of Olares One
1. Open the LarePass app on your mobile device, and then go to **Settings** > **System**.
2. Tap the Olares One device card.
3. Scroll down to the **Network** section, and then note down the **Intranet IP**.
:::tip Check via Control Hub
You can check the IP using the `ifconfig` command in the Control Hub terminal.
Look for your active interface, typically `enp3s0` (wired) or `wlo1` (wireless). The IP address appears after `inet`.
:::
### Step 2: Get the login password from Vault
:::info Not the same as your Olares Desktop password
This password logs you in to the Olares One host system over SSH. It's different from the password you use to sign in to the Olares Desktop in your browser.
:::
To change the saved password, see [Reset SSH password](./hardware-settings.md#reset-ssh-password).
### Step 3: Connect via SSH
The default username for Olares One is `olares`.
1. Open a terminal on your computer.
2. Run the following command, replacing `` with the Intranet IP you noted down:
```bash
ssh olares@
```
3. When prompted, enter the password obtained in Step 2.
## Advanced: Connect remotely from a different network
If your device is not on the same local network as your Olares One, use LarePass VPN to establish a secure tunnel to Olares One without exposing it to the internet. LarePass VPN uses [Tailscale](https://tailscale.com/), a mesh VPN that assigns each connected device a stable IP address in the `100.64.0.0/10` range (the Tailscale IP) to enable direct, encrypted communication between them.
### Step 1: Enable SSH via VPN
1. Open your Olares desktop, and then go to **Settings** > **VPN**.
2. Toggle on **Allow SSH via VPN**.
3. On your computer, open the LarePass desktop client.
4. Click your avatar in the top-left corner and toggle on **VPN connection**.
### Step 2: Find the Tailscale IP address
1. On your Olares desktop, go to **Settings** > **VPN** > **View VPN connection status**.
2. Find **olares**, and then click it to expand the connection details.
3. Locate the IP address that starts with `100.64`, and then note it down.
{width=80%}
### Step 3: Get the login password from Vault
### Step 4: Connect via SSH
The default username for Olares One is `olares`.
1. Open a terminal on your computer.
2. Run the following command, replacing `` with the Tailscale IP address you noted down:
```bash
ssh olares@
```
:::info
After you enable SSH via VPN, the first connection is slower because VPN routes are being applied. Wait a short time for the connection to complete.
:::
3. When prompted, enter the password obtained in Step 3.
---
### One Configure Gpu Mode (`docs/one/configure-gpu-mode.md`)
---
outline: [2, 3]
description: Configure the GPU mode on Olares One running Ubuntu.
head:
- - meta
- name: keywords
content: Olares One, Ubuntu, GPU mode, performance mode, quiet mode, NVIDIA, nvidia-powerd, ioport
---
# Configure the GPU mode on Ubuntu
Use this guide to configure the GPU mode on Olares One running Ubuntu.
## Prerequisites
- Your Olares One is powered on and running Ubuntu.
- You can access the Ubuntu terminal on your Olares One, either directly or through SSH, and run commands with `sudo`.
## Step 1: Install the NVIDIA driver
The NVIDIA driver allows Ubuntu to communicate with the discrete GPU. Install it before enabling NVIDIA power management or switching the GPU mode.
:::info Use the NVIDIA .run installer
The `.run` installer installs the NVIDIA driver and includes the `nvidia-powerd` service needed for power management. Drivers installed through `apt` do not include this service.
:::
1. In the Ubuntu terminal on your Olares One, download the NVIDIA driver installer:
```bash
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/595.84/NVIDIA-Linux-x86_64-595.84.run
```
:::info Driver version
This guide uses driver version `595.84`, which is tested on Olares One. Other versions are untested, and the `nvidia-powerd` service may fail to start on some of them.
:::
2. Make the installer executable:
```bash
chmod +x ./NVIDIA-Linux-x86_64-595.84.run
```
3. Run the installer:
```bash
sudo ./NVIDIA-Linux-x86_64-595.84.run
```
4. Follow the prompts shown by the installer until the installation completes.
## Step 2: Enable NVIDIA power management
The `nvidia-powerd` service manages power allocation between the CPU and GPU during demanding workloads. Enabling it allows the NVIDIA driver to apply the system's supported power-management behavior.
1. Enable and start the `nvidia-powerd` service:
```bash
sudo systemctl enable --now nvidia-powerd
```
2. Check the service status:
```bash
sudo systemctl status nvidia-powerd
```
The service status should show `active (running)`.
:::info
On Olares One, you may see `ERROR! JPAC is not created/already destroyed, ignoring request.` because the device has no battery. This message can be ignored if the service is `active (running)`.
:::
## Step 3: Set the GPU mode
With NVIDIA power management enabled, you can now set the GPU mode using `ioport`, a command-line tool for accessing hardware I/O ports. Choose performance mode (`3`) or quiet mode (`0`).
1. Install `ioport`:
```bash
sudo apt update && sudo apt install -y ioport
```
2. Run one of the following commands for the mode you want to use.
:::warning Olares One only
These commands access the Olares One Embedded Controller (EC). Use them only on Olares One, and copy the command for your chosen mode exactly as shown.
:::
To enable performance mode (`3`):
```bash
sudo outb 0x302 0x60 && sudo outb 0x303 3
```
To enable quiet mode (`0`):
```bash
sudo outb 0x302 0x60 && sudo outb 0x303 0
```
3. Check that the GPU power limit matches the selected mode:
```bash
nvidia-smi
```
In the `Pwr:Usage/Cap` column, check the value for `Cap`. It should be `150W` for performance mode (`3`) or `50W` for quiet mode (`0`).
:::info Performance mode boosts up to 175W
In performance mode, `nvidia-smi` shows a power limit of `150W` when the GPU is idle. Under full load, the limit dynamically rises to `175W`.
:::
**Example output:**
```text
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 595.84 Driver Version: 595.84 CUDA Version: 13.2 |
+-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 5090 ... Off | 00000000:02:00.0 Off | N/A |
| N/A 41C P8 7W / 150W | 9706MiB / 24463MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
```
## Resources
- [Install Ubuntu Server on Olares One](install-ubuntu-server.md)
- [Install Ubuntu Desktop on Olares One](install-ubuntu-desktop.md)
- [Manage BIOS and EC](update-firmware.md)
---
### One Connect Two Olares One (`docs/one/connect-two-olares-one.md`)
---
title: Connect two Olares One devices as a cluster
outline: [2, 3]
description: Connect two Olares One devices by enabling JuiceFS on an existing master, generating a worker join command, and checking the cluster.
head:
- - meta
- name: keywords
content: Olares One, Cluster, Kubernetes, Multi-node, Worker node, Master node
---
# Connect two Olares One devices
For advanced use cases requiring more computing resources and distributed storage, you can physically connect two Olares One units to form a single, unified cluster.
:::warning Olares 1.12.7 or later required
The master must be activated and running Olares 1.12.7 or later as a single-node system. [Back up important data](../manual/olares/settings/backup.md) before starting. Keep the master powered on during the file system migration.
:::
## Learning objectives
By the end of this guide, you will learn how to:
- Enable shared storage on the master node.
- Generate and protect the worker join command.
- Resolve hostname conflicts and join a worker node to the cluster.
- Verify that both nodes are ready.
## Before you begin
- The factory SSH username and password are both `olares`. For activated devices, use the SSH password saved in LarePass Vault. See [Access Olares One via SSH](./access-terminal-ssh.md#step-2-get-the-login-password-from-vault).
- SSH access grants powerful control over the system. Keep your credentials secure.
## Prerequisites
**Hardware**
- Two Olares One units connected to the same local area network, with internet access to download the join script and installation files.
- A computer with an SSH client.
**Experience**
- Familiarity with terminal commands and basic Kubernetes node management.
**Software**
- LarePass installed on your mobile phone.
- SSH access with `sudo` permissions on both units. The worker must be able to sign in to the master over SSH with a password.
## Step 1: Set up the master node
### Enable JuiceFS
Your existing, activated unit serves as the master node. JuiceFS provides shared storage for the cluster. The migration command installs MinIO as the storage backend by default and migrates your existing data.
1. Access the master node via SSH using its local IP address.
In LarePass, go to **Settings** > **System** > your device > **Nodes** > **Network** > **Intranet IP** to find the address. Use the SSH password saved in LarePass Vault.
```bash
ssh olares@
```
2. Stop Olares.
```bash
sudo olares-cli stop
```
3. Enable JuiceFS and migrate the existing Olares file system.
```bash
sudo olares-cli node enable-juicefs
```
Migration time depends on the amount of data. Large migrations can take a while without showing progress. Keep the terminal open and wait for completion.
Olares restarts automatically when the migration finishes. Wait for confirmation that JuiceFS is enabled and the master is ready to accept worker nodes before continuing.
Example output:
```plain
[Job] Enable JuiceFS on the master node and migrate rootfs execute successfully!!! (...)
JuiceFS is enabled on this master node (version ); it is now ready to accept worker nodes.
Run 'olares-cli node join-command' on this master to print the command for a worker node.
```
### Generate the worker join command
1. In the master terminal, run:
```bash
sudo olares-cli node join-command
```
2. Check the SSH address and username shown. Enter `y` to confirm, or follow the prompt to change the username. The default is `olares`.
3. Enter the SSH password. The command checks SSH sign-in and `sudo` access on the master. If authentication fails, it prompts for the username and password again. Press `Enter` to keep the suggested username, or enter a different one. If the connection still fails, check the address, SSH service, and firewall settings.
4. Copy the generated command. You will run it on the worker node in the next step.
Example output:
```plain
SSH login and sudo access verified for @:22.
Run the following command on the worker node:
export MASTER_AUTH_INFO='' OLARES_SYSTEM_CDN_SERVICE='' && curl -fsSL '' | bash
MASTER_AUTH_INFO is Base64-encoded, not encrypted. Anyone holding this command can recover the master's SSH credentials, so share it only with the intended worker administrator.
```
:::danger Protect the join command
The generated `MASTER_AUTH_INFO` value is Base64-encoded, not encrypted. Anyone who has the command can recover the master's SSH credentials. Share it only with the administrator of the intended worker, and never post it in a public channel or repository.
:::
## Step 2: Set up the worker node
The second unit will serve as the worker node. Open a separate terminal and check its IP address before continuing.
:::warning Clean installation required on the worker
Uninstall any existing Olares system on the worker, including the factory-installed system. [Back up important data](../manual/olares/settings/backup.md) first. Do not uninstall Olares on the master.
:::
1. Access the worker node via SSH using its local IP address.
```bash
ssh olares@
```
2. On the worker, paste and run the complete command from [Generate the worker join command](#generate-the-worker-join-command). The command follows this pattern:
```bash
export MASTER_AUTH_INFO='' \
OLARES_SYSTEM_CDN_SERVICE='' \
&& curl -fsSL '' | bash
```
Use the generated command exactly as shown. Do not copy the placeholder command above.
3. If the command reports that Olares is already installed, uninstall it:
```plain
Joining this machine to an Olares cluster as a worker node, using the Olares installer.
error: Olares is already installed on this node; run 'sudo olares-cli uninstall' before joining it to another cluster
```
```bash
sudo olares-cli uninstall
```
When the uninstall finishes, run the generated join command again.
4. If prompted, enter a unique hostname, such as `olares-worker`. Both units use `olares` by default, but Kubernetes requires each node to have a unique name. If the current hostname is valid and unique, no change is needed.
The hostname must:
- Contain only lowercase letters, numbers, hyphens (`-`), or periods (`.`).
- Start and end with a letter or number.
- Be unique in the cluster.
The join process checks the connection to the master, updates the hostname when needed, prepares the matching Olares version, and adds the worker to the cluster.
If the worker has only been prepared for installation, rather than fully installed, the process reuses a matching version. If the prepared version differs from the master's, it automatically removes the old prepare state and prepares the matching version.
Wait for a success message similar to the following:
```plain
[Job] Add Worker Node To The Cluster execute successfully!!! (...)
This node joined the Olares cluster at as "".
Verify it on the master with: sudo /usr/local/bin/kubectl get nodes
```
## Step 3: Verify the cluster
Once the join command completes, run the following command on the master to check both nodes:
```bash
sudo /usr/local/bin/kubectl get nodes
```
Confirm that both devices appear and show `Ready`. For example:
```plain
NAME STATUS ROLES AGE VERSION
olares Ready control-plane,master,worker 1h v1.33.3+k3s1
olares-worker Ready worker 1m v1.33.3+k3s1
```
## Resources
- [Set up a multi-node Olares cluster](../manual/best-practices/install-olares-multi-node.md): Follow the general setup guide for Linux devices.
- [Olares environment variables](../developer/install/environment-variables.md): Explore advanced configuration options.
---
### One Create Bootable Usb (`docs/one/create-bootable-usb.md`)
---
outline: [2, 3]
description: Create a bootable USB drive with the latest Olares One ISO to reinstall or recover Olares OS on Olares One.
head:
- - meta
- name: keywords
content: Olares One, bootable USB, Olares One ISO, reinstall Olares OS, recovery USB, Balena Etcher
---
# Create an Olares One bootable USB drive
Create a bootable USB drive with the latest Olares One ISO when you need to reinstall or recover Olares OS on Olares One.
Use this guide if the included USB drive is unavailable, contains an earlier OS image, or if you want to reinstall Olares One directly with the latest OS image.
:::warning Use the Olares One ISO only
Use only the Olares One ISO linked in this guide to create the bootable USB drive.
Do not use Olares ISO images linked from other Olares installation documentation, as they are intended for generic hardware. If you use a standard self-hosted ISO, your device may be recognized as **Generic** instead of **Olares One**, and some Olares One-specific features may be unavailable.
:::
## Prerequisites
- USB flash drive: A drive with 32 GB or larger capacity.
:::warning Data loss
The selected USB drive will be erased when you create the bootable drive. Back up any important files before continuing.
:::
- Computer: A Windows, macOS, or Linux computer to perform the setup.
- Internet connection: A stable connection for downloading the ISO file and Balena Etcher.
## Create the bootable USB drive
1. Download [the latest official Olares One ISO image](https://cdn.olares.com/one/v1.12.7-amd64.iso) to your computer.
2. Download and install [**Balena Etcher**](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open Balena Etcher and follow these steps:
a. Click **Flash from file** and select the Olares One ISO you downloaded.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait until flashing and validation are complete.
6. Safely eject the USB drive.
## Next steps
Use the bootable USB drive to reinstall Olares OS on Olares One. For detailed instructions, see [Reinstall Olares OS using bootable USB](create-drive.md).
---
### One Create Drive (`docs/one/create-drive.md`)
---
outline: [2, 3]
description: Reinstall Olares OS on Olares One using a bootable USB drive to restore the device to a clean initial state.
head:
- - meta
- name: keywords
content: Olares One, reinstall, Olares OS, bootable USB, installation USB
---
# Reinstall Olares OS using bootable USB
Reinstalling Olares OS returns your Olares One to a clean initial state.
:::warning Data loss
This will permanently delete all accounts, settings, and data on the device. This action cannot be undone.
:::
## Prerequisites
- A monitor and keyboard connected to Olares One.
- The bootable USB drive that came with Olares One.
:::info Installed OS version
The OS image on the included USB drive may be an earlier version, depending on when your device was shipped. You can still use it to reinstall the system, then update Olares OS after activation if needed.
If you need the latest OS image, create a new bootable USB drive from the [Olares One ISO](https://cdn.olares.com/one/v1.12.7-amd64.iso). For detailed steps, see [Create an Olares One bootable USB drive](create-bootable-usb.md).
## Step 1: Boot from the USB drive
1. Insert the bootable USB drive into Olares One.
2. Power on Olares One or restart it if it is already running.
3. When the Olares logo appears, immediately press the **Delete** key repeatedly to enter **BIOS setup**.
4. Navigate to the **Boot** tab, set **Boot Option #1** to the USB drive, and then press **Enter**.
5. Press **F10**, then select **Yes** to save and exit.
Olares One will restart and boot into the Olares installer interface.
## Step 2: Install Olares to disk
1. From the installer interface, select **Install Olares to Hard Disk** and press **Enter**.
2. When prompted for the installation target, the installer shows a list of available disks. Type `/dev/` followed by the disk name (e.g. `nvme0n1`) from that list and press **Enter**.
For example, to install to `nvme0n1`, enter:
```bash
/dev/nvme0n1
```
3. When you see prompts about NVIDIA GPU drivers, press **Enter** to accept the default.
4. When you see the message below, the reinstallation is complete:
```bash
Installation completed successfully!
```
5. Remove the USB drive, then press **Ctrl + Alt + Delete** to restart.
## Step 3: Verify the installation
After the reboot, the system starts in a clean factory state and shows a text-based Ubuntu login prompt.
1. Log in with the default credentials:
- **Username**: `olares`
- **Password**: `olares`
2. (Optional) Run the following command to verify the installation:
```bash
sudo olares-check
```
Example output:
## Step 4: Complete activation via LarePass
You can then activate Olares One again via LarePass. For detailed instructions, see [First boot](first-boot.md).
## Step 5: Check for system updates (optional)
The included USB drive may install an earlier OS version. After activation, you can update Olares OS in LarePass. For detailed steps, see [Update OS](update.md).
---
### One Direct Display (`docs/one/direct-display.md`)
---
outline: [2, 3]
description: Use Olares One locally with an HDMI display, keyboard, and mouse while keeping your apps and data accessible from a browser.
head:
- - meta
- name: keywords
content: Olares One, HDMI display, direct display, Olares Desktop, Node Display
---
# Use Olares One with a direct display
Connect an HDMI display, keyboard, and mouse to Olares One to access your apps and data directly, without another computer. You can use Olares Desktop on the connected display and in a browser at the same time without either session interrupting the other.
:::warning Alpha feature
This feature is currently in the **Alpha** stage and is not recommended for production environments. It is disabled by default and requires you to install the preview `olares-desktop` package. It may contain performance issues and require additional manual configurations. If you encounter any issues, please report them to the [Olares GitHub repository](https://github.com/beclab/Olares/issues).
:::
## Prerequisites
**Hardware**
- Your Olares One is set up and powered on.
- An HDMI display, keyboard, and mouse connected to Olares One.
- An audio output device connected to Olares One if you want game audio.
- If Olares OS is activated, a mobile device with the LarePass app installed is required to retrieve the login password from Vault.
**System**
- Olares OS v1.12.7 running on the Olares One.
**Software**
- Steam Headless updated to the latest version, if you plan to use Steam.
## Step 1: Access Olares One directly
1. Prepare the Olares One host login password.
- If Olares OS is not activated, use the default password `olares`.
- If Olares OS is activated, open the LarePass app on your mobile device. In Vault, find the item marked with the terminal icon, and tap it to reveal the password.
:::info Not the same as your Olares Desktop password
This password logs you in to the Olares One host system. It is different from the password you use to sign in to Olares Desktop in your browser.
:::
2. On the text-based login prompt displayed on the connected monitor, enter the username `olares`, and then press **Enter**.
```text
olares login:
```
3. Enter the host login password you prepared above, and then press **Enter**. For security, characters will not appear on the screen as you type.
:::tip
If you prefer to prepare Olares One remotely, you can use SSH or Control Hub to download and install the package before connecting the display. See [Access Olares One terminal](https://www.olares.com/docs/one/access-overview) for the available methods.
:::
## Step 2: Download and install the Olares Desktop preview package
1. Download the package:
```bash
cd /tmp && wget https://cdn.olares.com/olares-one/desktop/olares-desktop_0.1.0_20260928_amd64.deb
```
2. After the download finishes, install the package:
```bash
sudo bash -c 'apt update && DEBIAN_FRONTEND=noninteractive apt-get install -y -f ./olares-desktop_0.1.0_20260928_amd64.deb'
```
3. If prompted about the configuration file `/etc/default/apport`, press **Enter** to accept the default option `N` and keep the existing configuration.
```text
*** apport (Y/I/N/O/D/Z) [default=N] ?
```
4. Wait for the installation to finish and the terminal prompt to return.
```text
olares@olares:/tmp$
```
## Step 3: Start the local desktop
1. Run the following command:
```bash
sudo start-desktop
```
2. Wait for the Olares sign-in screen to appear, and then enter your Olares Desktop password to log in.
## Step 4: Configure Steam for local display
If you plan to use Steam, complete the following steps after the local desktop starts.
:::warning
Steam compatibility mode is temporary. Each time you start the local desktop with `sudo start-desktop`, complete Step 4 afterward. Each time you stop it with `sudo stop-desktop`, complete Step 7 afterward.
:::
1. Press and hold **Ctrl**, then press **Tab** until the local terminal (`olares@olares:~`) is highlighted. Release **Ctrl** to open it.
2. Create the Olares Desktop configuration. This enables the configuration required for Steam compatibility mode.
```bash
kubectl apply -f - <` with your Olares user name (such as `laresprime`). This sets Steam Headless to use the compatibility mode while the local desktop is running.
```bash
kubectl patch appenv steamheadless- -n steamheadless- --type='json' -p='[{"op": "add", "path": "/envs/2/value", "value": "secondary"}]'
```
When the command finishes successfully, the terminal displays:
```text
appenv.sys.bytetrade.io/steamheadless- patched
```
4. Press and hold **Ctrl**, then press **Tab** to switch back to Olares Desktop.
5. Open Olares Settings, go to **Applications** > **Steam Headless**, stop the app and then resume it.
6. Open Steam Headless from the Launchpad and sign in.
## Step 5: Switch between top-level windows
Press and hold **Ctrl**, then press **Tab** repeatedly to cycle through the available top-level windows. Release **Ctrl** to open the highlighted window.
The default windows are:
- **Olares Desktop**: The local Olares Desktop interface, which you can use just as in a browser.
- **Node Display**: A local interface for managing the Olares One device.
- **`olares@olares:~`**: The local terminal.
## Step 6: Stop the direct display interface
1. Save your work in any open app.
2. Use **Ctrl+Tab** to switch to the local terminal (`olares@olares:~`), then run:
```bash
sudo stop-desktop
```
## Step 7: Restore Steam to its default mode
If you enabled Steam compatibility mode in [Step 4](#step-4-configure-steam-for-local-display), restore the Steam settings using the commands below. Run these commands only after stopping the direct display interface in [Step 6](#step-6-stop-the-direct-display-interface).
1. Remove the Olares Desktop configuration. This disables the compatibility configuration after you stop the direct display interface.
```bash
kubectl delete cm -n os-framework olares-desktop-config
```
When the command finishes successfully, the terminal displays:
```text
configmap "olares-desktop-config" deleted
```
2. Restore the Steam Headless environment. Replace `` with your Olares user name (such as `laresprime`). This removes the temporary compatibility setting from Steam Headless.
```bash
kubectl patch appenv steamheadless- -n steamheadless- --type='json' -p='[{"op": "remove", "path": "/envs/2/value"}]'
```
When the command finishes successfully, the terminal displays:
```text
appenv.sys.bytetrade.io/steamheadless- patched
```
---
### One Dual Boot Dual Drive (`docs/one/dual-boot-dual-drive.md`)
---
outline: [2,3]
description: Learn how to install Windows on a secondary SSD to create a dual-boot system on Olares One.
head:
- - meta
- name: keywords
content: Dual-boot, Windows, NVMe SSD, BIOS, Windows installation
---
# Dual-boot Windows on a secondary SSD
For competitive gaming or Windows-exclusive software, configure a secondary NVMe SSD to create a dual-boot system.
This dual-drive setup physically isolates the operating systems. This ensures Olares OS remains stable and secure while providing full native performance for your Windows applications.
## Learning objectives
By the end of this guide, you will learn how to:
- Create a bootable Windows installation USB drive.
- Configure BIOS settings to isolate Olares OS during installation.
- Install Windows on a secondary SSD.
- Set up GRUB to detect and switch between both operating systems.
## Prerequisites
**Hardware**
- A secondary NVMe M.2 SSD physically installed in Olares One.
- A USB flash drive (8 GB or larger) for Windows installation media.
- A wired keyboard and mouse connected to Olares One.
- A monitor connected to Olares One.
- An Ethernet cable connected to Olares One.
- A Microsoft account for completing the Windows setup process.
## Step 1: Create a bootable Windows USB drive
1. Download the Windows 11 ISO from the [official Microsoft website](https://www.microsoft.com/en-us/software-download/windows11).
2. Download and install [**balenaEtcher**](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open balenaEtcher and follow these steps:
a. Click **Flash from file** and select the ISO you downloaded.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait for the flashing and validation to finish, and then safely eject the USB drive.
## Step 2: Boot into BIOS and disable Olares OS
Disable the Olares OS drive in the BIOS before you install Windows to ensure the dual-boot configuration works correctly later.
1. Insert the Windows USB boot drive into the USB port on Olares One.
2. Power on Olares One, or restart it if it is already running.
3. When the Olares logo appears, press the **Delete** key repeatedly to enter the BIOS setup.
4. Go to the **Boot** tab, select the boot option for the Olares OS disk, and then press **Enter**.
5. Select **Disabled** in the popup window, and then press **Enter**.
6. Go to the **Save and Exit** tab, under **Boot Override**, select your Windows USB disk to boot directly from it, and then press **Enter**.
7. Press **F10**, and then select **Yes** to save the changes and exit.
The system automatically boots from the USB drive into the Windows installation interface.
## Step 3: Install Windows
The Windows setup process guides you through configuring your new system.
1. On the **Ventoy** screen, select the ISO file such as **Win11_25H2_English_x64_v2.iso**, and then select **Boot in normal mode**. The **Windows 11 Setup** wizard launches.
2. Follow the on-screen prompts to finish the standard Windows setup. During this process, the system restarts several times.
:::danger Verify the selected partition
On the **Select location to install Windows 11** screen, ensure you choose the correct secondary drive or partition. Selecting the wrong partition permanently erases your Olares OS.
:::
3. After the final configuration process finishes, the Windows desktop appears, indicating a successful installation.
4. Unplug the Windows USB drive.
## Step 4: Re-enable Olares OS in BIOS
After installing Windows, re-enable the Olares OS drive in the BIOS and set it as the primary boot device. You must boot back into Olares OS so you can configure the GRUB dual-boot menu in the next step.
1. Restart Olares One.
2. When the Olares logo appears, press the **Delete** key repeatedly to enter BIOS setup.
3. Go to the **Boot** tab.
4. Set **Boot Option #1** to the SSD that contains Olares OS, and set **Boot Option #2** to the SSD that contains Windows.
5. Press **F10**, and then select **Yes** to save and exit BIOS. Olares One boots into Olares OS.
## Step 5: Detect Windows and update GRUB
To choose between operating systems at startup, configure the GRUB bootloader to detect Windows.
1. Log in using the default credentials:
* **Username**: `olares`
* **Password**: `olares`
2. Run the following command:
```bash
sudo os-prober
```
If Windows has been installed successfully, you should see an entry similar to:
```bash
/dev/nvme0n1p1@/efi/Microsoft/Boot/bootmgfw.efi:Windows Boot Manager:Windows:efi
```
3. Enable GRUB to probe other operating systems and regenerate the boot menu:
a. Create a symbolic link for GRUB configuration:
```bash
sudo ln -s /boot/efi/grub /boot/grub
```
b. Enable OS prober to detect Windows:
```bash
sudo sed -i 's|GRUB_DISABLE_OS_PROBER=true|GRUB_DISABLE_OS_PROBER=false|' /etc/default/grub
```
c. Regenerate the GRUB boot menu:
```bash
sudo update-grub
```
Example output:
```bash
Sourcing file '/etc/default/grub'
Generating grub configuration file ...
Warning: os-prober will be executed to detect other bootable partitions.
Its output will be used to detect bootable binaries on them and create new boot entries.
Found Windows Boot Manager on /dev/nvme0n1p1@/efi/Microsoft/Boot/bootmgfw.efi
Adding boot menu entry for UEFI Firmware Settings ...
done
```
1. Obtain the system password from LarePass.
:::info
Right after you activate Olares, you will be prompted to reset the SSH password on the LarePass app. The password is automatically generated and saved to your Vault.
:::
a. Tap **Vault** in the LarePass app. When prompted, enter your local password to unlock.
b. In the top-left corner, tap **Authenticator** to open the side navigation, and then tap **All vaults** to display all saved items.
c. Find the item with the terminal icon and tap it to reveal the password.
d. Note down the password.
2. Log in using the default credentials:
* **Username**: `olares`
* **Password**: The one you obtained in Step 1.
3. Run the following command:
```bash
sudo os-prober
```
If Windows has been installed successfully, you should see an entry similar to:
```bash
/dev/nvme0n1p1@/efi/Microsoft/Boot/bootmgfw.efi:Windows Boot Manager:Windows:efi
```
4. Enable GRUB to probe other operating systems and regenerate the boot menu:
a. Create a symbolic link for GRUB configuration:
```bash
sudo ln -s /boot/efi/grub /boot/grub
```
b. Enable OS prober to detect Windows:
```bash
sudo sed -i 's|GRUB_DISABLE_OS_PROBER=true|GRUB_DISABLE_OS_PROBER=false|' /etc/default/grub
```
c. Regenerate the GRUB boot menu:
```bash
sudo update-grub
```
Example output:
```bash
Sourcing file '/etc/default/grub'
Generating grub configuration file ...
Warning: os-prober will be executed to detect other bootable partitions.
Its output will be used to detect bootable binaries on them and create new boot entries.
Found Windows Boot Manager on /dev/nvme0n1p1@/efi/Microsoft/Boot/bootmgfw.efi
Adding boot menu entry for UEFI Firmware Settings ...
done
```
## Step 6: Switch between operating systems
Use the GRUB boot menu to choose your preferred operating system every time you start Olares One.
1. Shut down Olares One, wait a few seconds, and then power it on again.
The GNU GRUB dual-boot menu appears automatically.
2. Choose which operating system to boot. The system automatically executes the highlighted entry in 10 seconds.
- **Boot Olares OS**: Select **Olares GNU/Linux**.
- **Boot Windows**: Select **Windows Boot Manager**.
3. To switch to the other operating system while currently logged in:
- **From Olares OS to Windows**: Run `sudo reboot` in the terminal and enter your password when prompted. When the GNU GRUB menu appears, select **Windows Boot Manager**.
:::info
When you type your password in the terminal, the characters remain invisible for security. Ensure you have entered the correct password and press **Enter**.
:::
- **From Windows to Olares OS**: Restart Windows. When the GNU GRUB menu appears, select **Olares GNU/Linux**.
## Resources
- [Install drivers on Windows](install-nvidia-driver.md)
---
### One Dual Boot Single Drive (`docs/one/dual-boot-single-drive.md`)
---
outline: [2,3]
description: Install Windows and Olares OS on a single SSD using a dual-boot configuration.
head:
- - meta
- name: keywords
content: Dual-boot, Single SSD, Windows, Ubuntu, Olares OS, Partitioning
---
# Dual-boot Windows on a single SSD
Run both Windows and Olares OS on Olares One without adding a second drive.
This configuration installs Windows first, then sets up Ubuntu Linux alongside it, and finally deploys Olares OS.
## Prerequisites
**Hardware**
- Olares One connected to Power.
- Wired keyboard and mouse connected to Olares One.
- (Recommended) An Ethernet cable connecting Olares One to your router.
- A USB flash drive contains Windows installation media.
- A USB flash drive contains Ubuntu Server or Desktop (24.04 LTS or newer) installation media.
**Network**
- A reliable internet connection.
- Your mobile phone connected to the same network.
**Software**
- [You have downloaded the LarePass app and created an Olares ID](first-boot.md#step-1-power-on-and-install-larepass).
:::danger Backup required
Partitioning a drive carries a risk of data loss. If you have important data on your current drive, backup everything to an external source before proceeding.
:::
## Step 1: Install Windows
1. Insert the Windows USB boot drive into a USB port on Olares One.
2. Power on Olares One or restart it if it is already running.
3. When the Olares logo appears, immediately press the **Delete** key repeatedly to enter **BIOS setup**.
4. Navigate to the **Boot** tab using the arrow keys on your keyboard.
5. Set **Boot Option #1** to your Windows USB flash drive, and press **Enter**.
6. Press **F10**, then select **Yes** to save and exit BIOS. The system restarts and boots from the USB drive into the Windows installation interface.
7. Follow the on-screen prompts to begin the Windows installation.
8. When the installation finishes and the system restarts, unplug the Windows USB drive.
The system will boot into Windows automatically.
## Step 2: Create a partition for Ubuntu
1. Once Windows is running, right-click the **Start** button and select **Disk Management**.
2. Right-click your main `C:` partition and select **Shrink Volume**.
3. Enter the amount of space to free up for Olares. Minimum 150 GB is required.
:::tip
Avoid splitting the drive into two equal sizes. Using distinct sizes makes it easier to identify the correct partition later during the Ubuntu installation.
:::
4. Click **Shrink** to create a block of unallocated space.
## Step 3: Install Ubuntu
Olares OS runs on top of a Linux kernel. You will install Ubuntu to serve as the host system.
1. Insert the Ubuntu USB drive and restart Olares One.
2. When the Olares logo appears, press the **Delete** key repeatedly to enter **BIOS setup**.
3. Navigate to the **Boot** tab, set **Boot Option #1** to your Ubuntu USB flash drive, and then press **Enter**.
4. Press **F10**, then select **Yes** to save and exit BIOS. The system restarts and boots from the USB drive into the Ubuntu installer.
5. Follow the installer prompts until you reach the **Installation type** screen.
:::tip
If this option does not appear, select the manual installation option to manually assign the unallocated space to Ubuntu.
:::
6. When the installation finishes and the system restarts, unplug the Ubuntu USB drive.
The system will boot into Ubuntu automatically.
## Step 4: Install Olares OS
1. Log in to Ubuntu using your username and password.
2. Open a terminal window if using Ubuntu Desktop or use the command line directly.
3. Run the official installation script:
```bash
curl -fsSL https://olares.sh | bash
```
4. At the end of the installation process, you will be prompted to enter your domain name and Olares ID.
For example, if your full Olares ID is `alice123@olares.com`:
- **Domain name**: Press `Enter` to use the default domain name or type `olares.com`.
- **Olares ID**: Enter the prefix of your Olares ID. In this example, enter `alice123`.
Upon completion of the installation, the initial system information, including the Wizard URL and the initial login password, will appear on the screen. You will need them later in the activation stage.
## Step 5: Activate Olares OS
1. Enter the Wizard URL in the browser on Ubuntu, or use a browser on another computer connected to the same network.
2. Enter the one-time password and click **Continue**.
3. Select the system language. Olares supports English, Simplified Chinese, German, Spanish, Italian, French, and Japanese. The Wizard switches to the selected language immediately, and Olares Desktop uses the same language after activation.
4. Select a reverse proxy node that is geographically closest to your location.
5. Activate Olares using LarePass app.
a. Open LarePass app, and tap **Scan QR code** to scan the QR code on the Wizard page and complete the activation.
b. Reset the login password.
After setup is complete, the LarePass app returns to the home screen, and the browser redirects you to the Olares login page.
## Switch between operating systems
You switch between Windows and Olares using the BIOS boot priority.
### Switch to Olares OS
1. Restart Olares One.
2. Press the **Delete** key repeatedly to enter **BIOS setup**.
3. Go to the **Boot** tab.
4. Set **Boot Override** to Ubuntu.
5. Press **F10** to save and exit BIOS.
### Switch to Windows
1. Restart Olares One.
2. Press the **Delete** key repeatedly to enter **BIOS setup**.
3. Go to the **Boot** tab.
4. Set **Boot Override** to Windows.
5. Press **F10** to save and exit BIOS.
## Troubleshooting
### An error occurs during installation
If an error occurs during installation, use the following command to uninstall first:
```bash
olares-cli uninstall --all
```
After uninstalling, retry the installation by running the original installation command.
### The Ubuntu interface is lagging
When you first boot into the Ubuntu desktop, the interface might feel laggy. This is because the GPU drivers for Ubuntu are not yet installed.
Proceed with the Olares OS installation. The installation script automatically installs the necessary GPU drivers, which will resolve the lag.
## Resources
- [Install drivers on Windows](install-nvidia-driver.md)
---
### One Dual Boot Ubuntu Dual Drive (`docs/one/dual-boot-ubuntu-dual-drive.md`)
---
noindex: true
outline: [2,3]
description: Install Ubuntu on a secondary SSD and set up dual-boot with Olares OS on Olares One.
head:
- - meta
- name: keywords
content: Dual-boot, Ubuntu, NVMe SSD, GRUB, Olares One
---
# Dual-boot Ubuntu on a secondary SSD
Install Ubuntu on a secondary NVMe SSD to create a dedicated environment for development, testing, or a fallback system without affecting Olares OS.
This dual-drive setup physically isolates the systems. This ensures Olares OS remains stable and secure while providing the flexibility to boot into either operating system natively.
## Learning objectives
By the end of this guide, you will learn how to:
- Create a bootable Ubuntu USB drive.
- Install Ubuntu on a secondary SSD.
- Configure GRUB to detect both Olares OS and Ubuntu.
- Switch between the two systems at startup.
## Prerequisites
**Hardware**
- A secondary NVMe M.2 SSD physically installed in Olares One.
- A USB flash drive (8 GB or larger) for Ubuntu installation media.
- A wired keyboard and mouse.
- A monitor connected to Olares One.
## Step 1: Create a bootable Ubuntu USB drive
1. Download the Ubuntu ISO (26.04 LTS or later) from the [official Ubuntu website](https://ubuntu.com/download/server). You can choose the Server or Desktop version.
2. Download and install [balenaEtcher](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open balenaEtcher and follow these steps:
a. Click **Flash from file** and select the ISO you downloaded.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait for the flashing and validation to finish, and then safely eject the USB drive.
## Step 2: Boot from the Ubuntu USB drive
1. Insert the Ubuntu USB drive into Olares One.
2. Power on Olares One, or restart it if it is already running.
3. When the Olares logo appears, press the **Delete** key repeatedly to enter the BIOS setup.
4. Go to the **Save & Exit** tab, under **Boot Override**, select your USB drive from the list, and then press **Enter**.
The system restarts and boots from the USB drive into the Ubuntu installation interface.
## Step 3: Install Ubuntu on the secondary SSD
The following steps use Ubuntu Server 26.04 as an example. The process is similar for the Desktop version.
1. In GNU GRUB, select **Try or Install Ubuntu Server**. Wait for the initial loading sequence to finish and the language selection screen to appear.
2. Select your language, and then press **Enter**.
3. Keep the default keyboard layout English (US), and then press **Enter**.
4. On the **Choose the type of installation** screen, select **Ubundu Server**, and then press **Enter**.
5. On the **Network configuration** screen, skip network configuration for now by selecting **Continue without network** at the bottom, and then press **Enter**.
:::tip
Connecting to the network triggers automatic background downloads for patches and dependencies. This can significantly delay the installation and might cause the installer to hang due to network fluctuations. Skipping this ensures a rapid, completely local installation from the pure ISO image.
:::
6. On the **Proxy configuration** screen, leave it blank unless your environment requires one, and then press **Enter**.
7. On the **Ubuntu archive mirror configuration** screen, keep the default Ubuntu archive mirror URL, ignore the "no network" warning, and then press **Enter**.
8. On the **Guided storage configuration** screen:
a. Ensure **Use an entire disk** is selected.
b. In the dropdown list below, verify the target disk is selected. For example, the **FORESEE** disk in this scenario.
c. Navigate down to **Set up this disk as an LVM group** and clear the selection using the **Space** key.
:::tip
Disabling LVM forces the installer to automatically create stable, straightforward standard ext4 partitions. This eliminates the risk of future GRUB bootloader conflicts or errors in a multi-OS environment.
:::
d. Navigate to the bottom of the page, select **Done**, and then press **Enter**.
9. On the **Storage configuration** summary screen, verify the following details, and then press **Enter**:
- Under **FILE SYSTEM SUMMARY**, ensure the system automatically allocates a `/boot/efi` (fat32) partition and a `/` (ext4) standard partition on your target disk.
- Under **USED DEVICES**, ensure only your target disk is in the "to be formatted" status.
10. In the **Confirm destructive action** window, select **Continue**, and then press **Enter** to start the formatting.
11. On the **Profile configuration** screen, set up your account, and then press **Enter**.
12. On the **Upgrade to Ubuntu Pro** screen, select **Skip Ubuntu Pro setup for now**, and then press **Enter**.
13. On the **SSH configuration screen**, select **Install OpenSSH server** to allow remote terminal management after connecting to the network later, and then press **Enter**.
14. The system will begin deployment. Wait for the top banner to display **Installation complete**.
15. Select **Reboot Now** at the bottom, and then press **Enter**.
16. Remove the installation USB drive and press **Enter** when prompted. The system reboots automatically.
## Step 4: Modify the BIOS boot order
After the reboot, the system boots into Olares OS by default. This happens because the installer places its bootloader (GRUB) in the EFI partition of the primary disk, and the motherboard still identifies the original Olares drive as the primary boot device.
Manually update **Boot Option #1** to the new drive to force the motherboard to load the newly generated GRUB menu. This menu successfully recognizes both Ubuntu and Olares OS.
1. Restart Olares One, and press the **Delete** key repeatedly to enter the BIOS setup.
2. Go to the **Boot** tab and locate the **Boot Option Priorities** section.
3. Change **Boot Option #1** to point to the newly installed drive:
a. Navigate to **Boot Option #1**, and then press **Enter**.
b. In the popup window, select the newly installed drive, and then press **Enter**.
4. Press **F10**, then select **Yes** to save and exit BIOS. The system reboots automatically.
## Step 5: Switch between Olares OS and Ubuntu
After rebooting, the **GNU GRUB** dual-boot menu appears automatically.
1. Choose which operating system to boot. The system automatically executes the highlighted entry in 10 seconds.
- **Boot Ubuntu**: Select **Ubuntu**.
- **Boot Olares OS**: Select the entry containing Olares, such as **Ubuntu 24.04.3 LTS (24.04) (on /dev/mapper/olares-vg-root)**.
2. To switch to the other operating system while currently logged in, run `sudo reboot` in the terminal and enter your password when prompted. When the **GNU GRUB** menu appears, choose the system you want to boot.
:::info
When you type your password in the terminal, the characters remain invisible for security. Ensure you have entered the correct password and press **Enter**.
:::
## Resources
- [Dual-boot Windows on a secondary SSD](dual-boot-dual-drive.md)
- [Ubuntu Server documentation](https://ubuntu.com/server/docs)
- [GRUB manual](https://www.gnu.org/software/grub/manual/grub/html_node/)
---
### One Dual Boot Windows Troubleshooting (`docs/one/dual-boot-windows-troubleshooting.md`)
---
outline: [2, 3]
description: Common issues and solutions for dual-booting Olares OS with Windows on Olares One.
head:
- - meta
- name: keywords
content: Olares One, dual boot, Windows, troubleshooting, display flickering, HDMI, external monitor
---
# Troubleshooting
Use this page to identify and resolve common issues when dual-booting Olares OS with Windows on Olares One.
## Monitors flicker when starting Windows with two external displays
### Condition
This issue applies if you experience all of the following:
- Olares One is set up to dual-boot Olares OS and Windows.
- Windows starts with two external monitors connected.
- One monitor is connected through HDMI, and the other is connected through a USB-C hub or adapter.
- One or both monitors flicker during Windows startup or shortly after Windows reaches the desktop.
You can confirm this issue if disconnecting and reconnecting the affected monitor restores normal display output.
### Cause
When Windows starts, it first loads a basic display driver to turn on the screens. This driver is enough to start Windows, but it may not handle high-resolution HDMI output and multi-monitor detection reliably in this dual-boot setup.
After Windows reaches the desktop, the NVIDIA driver takes over display output. However, if a monitor connection has already entered an unstable state during startup, the NVIDIA driver may not recover it automatically. Reconnecting the monitor forces Windows to detect the display again.
This is usually a temporary display initialization issue, not a sign that your monitors or GPU are damaged.
### Solution
If the monitor is currently flickering:
1. Disconnect the affected monitor from Olares One or from the USB-C hub.
2. Wait a few seconds.
3. Reconnect the monitor and wait for Windows to detect it again.
To prevent the issue from happening again:
1. Before booting into Windows, disconnect the USB-C display or hub and keep only the HDMI monitor connected.
2. Start Windows and wait until the desktop is fully loaded.
3. Connect the second monitor through the USB-C hub or adapter.
---
### One Egpu Olares Os (`docs/one/egpu-olares-os.md`)
---
outline: [2, 3]
description: Connect an NVIDIA eGPU to Olares One, check it in Olares OS, and install the temporary Gen1 workaround when needed.
---
# Set up an eGPU on Olares OS
Use this guide to connect the eGPU. Install the Gen1 workaround only if startup stalls or the GPU is not detected.
:::danger Always power off before changing the connection
Olares OS does not support eGPU hot-plugging. Shut down Olares One before connecting or disconnecting the eGPU.
:::
## Connect the eGPU
1. Open **Settings** > **My hardware** > **Shutdown**.
2. Scan the QR code with LarePass, then tap **Confirm**.
3. Wait until Olares One is completely off.
4. Prepare the eGPU:
- If the GPU is already installed, connect the device's power adapter.
- If you use an eGPU dock or enclosure, install the desktop GPU and connect all required GPU power cables.
5. Turn on the eGPU.
6. Disconnect other high-bandwidth Thunderbolt devices. Using a certified Thunderbolt 5 cable, connect the eGPU directly to a Thunderbolt 5 (USB-C) port on Olares One.
7. Press the power button on Olares One.
## Check the connection
1. Log in to Olares and open **Dashboard**.
2. Select the **GPU** card.
3. Check that the built-in GPU and eGPU both appear.
You can also check from the terminal:
```bash
nvidia-smi
```
If the eGPU appears in Dashboard and `nvidia-smi`, do not install the workaround.
If startup stalls or the eGPU does not appear in Dashboard or `nvidia-smi`, shut down Olares One, disconnect the eGPU, and start Olares One again. Install the workaround below before reconnecting the eGPU.
## Install the workaround if needed
The workaround sets the external GPU's PCIe link to Gen1 before the NVIDIA driver loads. It targets only Thunderbolt-connected NVIDIA GPUs and does not change the built-in GPU.
:::info Performance impact
The workaround reduces bandwidth between system memory and GPU memory. Model loading, CPU offload, gaming, and real-time rendering may be slower. It does not change the GPU's compute resources.
:::
:::warning Temporary workaround
This workaround is provided by Olares and is not an official NVIDIA fix. Install only the files linked from this page. A future Olares release will include the workaround, so manual setup will no longer be required.
:::
1. Start Olares One without the eGPU connected.
2. Download all three files to the same directory:
- `fix-egpu-link.sh`
- `egpu-gen1-fix.service`
- `99-egpu-gen1-fix.rules`
3. Open a terminal in that directory and check that `setpci` is available:
```bash
command -v setpci
```
The command should return a path such as `/usr/sbin/setpci`. If it returns nothing, stop and contact Olares support.
4. Install the files and enable the service:
```bash
sudo install -m 0755 fix-egpu-link.sh /usr/local/sbin/fix-egpu-link.sh
sudo install -m 0644 egpu-gen1-fix.service /etc/systemd/system/egpu-gen1-fix.service
sudo install -m 0644 99-egpu-gen1-fix.rules /etc/udev/rules.d/99-egpu-gen1-fix.rules
sudo systemctl daemon-reload
sudo udevadm control --reload-rules
sudo systemctl enable egpu-gen1-fix.service
```
5. Check the result:
```bash
sudo systemctl is-enabled egpu-gen1-fix.service
```
The command should return `enabled`.
6. Follow [Connect the eGPU](#connect-the-egpu) again.
## Check the workaround
After Olares One starts, check that the eGPU appears in Dashboard or `nvidia-smi`. Then check the workaround log:
```bash
sudo tail -n 20 /var/log/egpu-gen1-fix.log
```
Look for a line similar to this one:
```plain
after rescan: 0000:0a:00.0 speed=2.5 GT/s PCIe driver=nvidia
```
`2.5 GT/s PCIe` means the external GPU link is running at Gen1. The PCI address differs by system.
If the eGPU is still missing or unstable, follow [Troubleshoot eGPU issues](./ts-egpu.md).
## Disconnect the eGPU
1. Open **Settings** > **My hardware** > **Shutdown**.
2. Approve the shutdown in LarePass and wait until Olares One is completely off.
3. Turn off the eGPU.
4. Disconnect the Thunderbolt cable from Olares One.
5. Start Olares One again.
## Remove the workaround
:::warning Disconnect the eGPU first
Shut down Olares One and disconnect the eGPU before removing the workaround.
:::
1. Start Olares One without the eGPU connected.
2. Remove the workaround:
```bash
sudo systemctl disable egpu-gen1-fix.service
sudo rm /usr/local/sbin/fix-egpu-link.sh
sudo rm /etc/systemd/system/egpu-gen1-fix.service
sudo rm /etc/udev/rules.d/99-egpu-gen1-fix.rules
sudo systemctl daemon-reload
sudo udevadm control --reload-rules
```
3. Restart Olares One:
```bash
sudo reboot
```
## Related resources
- [Connect an eGPU to Olares One](./egpu.md)
- [Troubleshoot eGPU issues](./ts-egpu.md)
---
### One Egpu Windows (`docs/one/egpu-windows.md`)
---
outline: [2, 3]
description: Set up an NVIDIA eGPU on Olares One running Windows 11 and recover the built-in GPU if its driver reports an error.
---
# Set up an eGPU on Olares One with Windows
Use this guide for the first eGPU setup on Windows 11 or when the built-in GPU reports an error after you connect an eGPU.
:::warning Complete the cleanup before connecting
For the initial setup, leave the eGPU disconnected until CleanupTool finishes and Windows restarts. If the eGPU is already connected, shut down Olares One, disconnect it, and then start Windows again.
:::
## Before you start
Make sure the eGPU meets the [hardware requirements](./egpu.md#choose-hardware) and that you have administrator access to Windows.
If Windows is not installed, first follow [Install Windows on the primary drive](./install-windows-primary-drive.md). You do not need to reinstall Windows or use a specific Windows image just to add an eGPU.
## Set up the eGPU for the first time
1. Open **Settings** > **Windows Update**. Install all available updates, then check again until Windows reports that it is up to date.
2. Download and run [`CleanupTool_1.0.21.0`](https://cdn.olares.com/common/CleanupTool_1.0.21.0.exe) to remove all existing NVIDIA apps, graphics drivers, and related utilities.
3. When CleanupTool prompts you to restart, select **Yes** and wait for Windows to start again.
4. Shut down Olares One.
5. Prepare and power on the eGPU:
- If the GPU is already installed, connect the device's power adapter.
- If you use an eGPU dock or enclosure, install the desktop GPU and connect all required GPU power cables.
6. Disconnect other high-bandwidth Thunderbolt devices. Using a certified Thunderbolt 5 cable, connect the eGPU directly to a Thunderbolt 5 (USB-C) port on Olares One.
7. Start Olares One.
8. Install NVIDIA App.
9. In NVIDIA App, download and install the latest graphics driver available for your GPU.
10. Restart Windows.
## Recover the built-in GPU
Use these steps if the built-in GPU has a warning icon in Device Manager or disappears from NVIDIA App after you connect the eGPU.
Keep the eGPU connected during this procedure.
1. Open **NVIDIA App** > **Drivers** > **Reinstall**.
2. Select **Custom installation**.
3. Select **Perform a clean installation** and finish the installation.
4. Restart Windows.
## Check the setup
1. Open **Device Manager** > **Display adapters**.
2. Check that the built-in GPU and every connected eGPU appear without warning icons.
## If a GPU is missing or reports an error
Follow [Troubleshoot eGPU issues](./ts-egpu.md). Record the Device Manager error code before reinstalling the driver because the code helps identify the failure.
## Related resources
- [Connect an eGPU to Olares One](./egpu.md)
- [Troubleshoot eGPU issues](./ts-egpu.md)
---
### One Egpu (`docs/one/egpu.md`)
---
outline: [2, 3]
description: Learn what an eGPU is, check known hardware compatibility, and connect an NVIDIA eGPU to Olares One.
head:
- - meta
- name: keywords
content: Olares One, eGPU, external GPU, Thunderbolt 5, NVIDIA
---
# Connect an eGPU to Olares One
You can add GPU capacity to Olares One by connecting an external GPU (eGPU) over Thunderbolt.
:::danger Shut down before connecting on Olares OS
Do not connect or disconnect an eGPU while Olares OS is running. Shut down Olares One, power on and connect the eGPU, and then start Olares One.
:::
## Check known compatibility
The table lists available compatibility results, not recommended products or every possible combination. Results also depend on the dock or enclosure, power supply, cable, operating system, and NVIDIA driver. An unlisted combination may work, but has not been verified.
| External graphics hardware | Olares OS | Windows 11 |
|---|---|---|
| AOOSTAR EG02 eGPU dock + RTX 4060 Ti | **Works after setup.** Install the [Gen1 workaround](./egpu-olares-os.md#install-the-workaround-if-needed). | **Works after setup.** Reinstall the NVIDIA driver with the eGPU connected. |
| Razer Core X V2 eGPU enclosure + RTX 4090 | **Under verification.** Startup was unstable without the Gen1 workaround. Results with the workaround are not verified. | **Verified only in the tested multi-eGPU setup.** Standalone use has not been verified. |
| Razer Core X eGPU enclosure + RTX 4060 | **Not verified.** | **Verified only in the tested multi-eGPU setup.** Standalone use has not been verified. |
| eGPU dock or enclosure + desktop RTX 5090 | **Not supported.** The NVIDIA driver did not initialize, and no workaround is available. | **Not verified.** |
In this table, **Works** and **Verified** mean that the GPU completed a workload test. Detection in Dashboard, Device Manager, or `nvidia-smi` alone is not treated as a compatibility result.
:::info Multiple eGPUs
If you need multiple eGPUs, use Windows 11. Olares OS currently supports only one eGPU at a time.
We have verified one Windows 11 configuration with three eGPUs connected through a Razer Thunderbolt 5 Dock:
- AOOSTAR EG02 with RTX 4060 Ti
- Razer Core X V2 with RTX 4090
- Razer Core X with RTX 4060
In this configuration, the built-in RTX 5090M was limited to about 95 W instead of 175 W.
Multi-eGPU compatibility depends on the dock and connection topology. Start with one eGPU, then connect and verify additional devices one at a time.
:::
## Choose hardware
Prepare one of the following:
- A Thunderbolt external graphics device with a GPU already installed and its power adapter.
- A Thunderbolt eGPU dock or enclosure, a desktop NVIDIA GPU based on the Turing architecture or newer, and a power supply that meets the GPU requirements.
:::info Thunderbolt 5
Use a certified Thunderbolt 5 cable, preferably the cable supplied with the external graphics device.
Older Thunderbolt external graphics devices may work, but Thunderbolt 5 is recommended.
:::
## Set up your eGPU
Choose the guide for your operating system:
- [Set up an eGPU on Olares OS](./egpu-olares-os.md)
- [Set up an eGPU on Windows 11](./egpu-windows.md)
## Get help
If Olares One does not start, the eGPU is missing, or a GPU reports a driver error, see [Troubleshoot eGPU issues](./ts-egpu.md).
---
### One Expand Storage External Ssd (`docs/one/expand-storage-external-ssd.md`)
---
outline: [2, 3]
description: Learn how to manually mount an external SSD to Olares One for temporary or permanent storage expansion.
head:
- - meta
- name: keywords
content: Olares One, external SSD, expand storage
---
# Expand storage via external SSD
You can manually mount high-capacity external SSDs to specific system paths on Olares One.
This approach is recommended for long-term storage expansion, such as downloading more or larger local AI models.
:::warning HDD support
This guide is intended for SSDs. Mechanical Hard Disk Drives (HDDs) have not been tested with Olares One.
:::
:::info Mount path
Currently, only mounts under the `/olares/share` directory are supported.
Mounting flexibility will be improved in future versions.
:::
## Prerequisites
**Hardware**
- Your Olares One is set up and running.
- The external SSD is connected to Olares One.
**SSH access**
- [SSH access to Olares One](access-terminal-ssh.md).
**Experience**
- Basic familiarity with terminal commands and the command-line interface (CLI).
## Step 1: Identify the drive
1. Connect to your Olares One terminal via SSH or from the Control Hub.
2. Run the following command to view detected drives:
```bash
sudo fdisk -l
```
3. Identify your target drive from the output. Each drive lists its partitions under the **Device** column, such as `/dev/nvme1n1p1`, `/dev/nvme1n1p2`, or `/dev/sdb1`.
4. Note the target partition you intend to mount. For example: `/dev/nvme1n1p1`.
## Step 2: Mount the partition
### Option A: Temporarily mount a partition
Temporary mounting is suitable for one-time tasks such as data migration. The configuration will be lost if the device reboots.
1. Create a directory for the mount point:
```bash
sudo mkdir -p /olares/share/
```
Replace `` with a custom name.
2. Mount the partition to this directory:
```bash
sudo mount /dev/ /olares/share/
```
For example:
```bash
sudo mount /dev/nvme1n1p1 /olares/share/hdd0
```
3. Navigate to the **External** directory in Files to verify the mount. You should see the new folder content.
### Option B: Permanently mount a partition
For long-term usage, you must configure the system to mount the drive automatically at boot using the `/etc/fstab` file.
1. Get the UUID.
:::tip Use UUID to identify device
Using the UUID is safer than using device names (like `/dev/sdb1`), which can change if you plug drives into different ports.
:::
a. Run the following command:
```bash
lsblk -f
```
b. Note down following information:
- **FSTYPE**: File system type (e.g., `ext4`, `xfs`).
- **UUID**: Unique identifier of the partition.
2. Create the mount directory:
```bash
sudo mkdir -p /olares/share/
```
Replace `` with a custom name.
3. Open the configuration file.
```bash
sudo vi /etc/fstab
```
4. Add the mount entry. Add a new line at the end of the file using the following format:
```bash
UUID= /olares/share/ defaults,nofail 0 0
```
For example:
```bash
UUID=1234-ABCD /olares/share/my_disk ext4 defaults,nofail 0 0
```
5. Press `Esc`, type `:wq`, and hit **Enter** to save your changes and exit the editor.
6. Run the following command to verify the configuration.
```bash
mount -a
```
:::tip Prevent boot failure
An incorrect `/etc/fstab` configuration might prevent your system from booting.
It is strongly recommended to run `mount -a` first to validate the configuration before rebooting.
:::
If no errors appear, the setup is successful.
7. After reboot, confirm the drive is automatically mounted in the **External** directory.
## Step 3: Unmount a partition
:::warning Irreversible operation
Ensure no programs or terminals are accessing the directory before unmounting.
:::
To safely remove the drive or delete the mount point configuration:
1. Unmount the partition:
```bash
sudo umount /olares/share/
```
2. (Optional) Remove the directory If you no longer need the folder:
```bash
rm -rf /olares/share/
```
## Resources
- [Manage files in Olares](../manual/olares/files/index.md)
- [Expand storage via USB devices](expand-storage-usb-drive.md)
- [Expand storage using internal SSD](expand-storage-internal-ssd.md)
---
### One Expand Storage Internal Ssd (`docs/one/expand-storage-internal-ssd.md`)
---
outline: [2, 3]
description: Learn how to expand storage on Olares One using an NVMe M.2 SSD.
head:
- - meta
- name: keywords
content: Olares One, NVMe SSD, expand storage, LVM, olares-cli
---
# Expand storage with an NVMe M.2 SSD
If you have installed a secondary internal NVMe SSD in your Olares One, you can merge it into the main system storage using the `olares-cli`.
Unlike external drives which are mounted as separate folders, this method uses Logical Volume Management (LVM) to seamlessly extend your root file system.
## Before you begin
:::warning One-time irreversible operation
- This is a one-time operation. The SSD becomes an integral part of the system volume and cannot be easily separated later.
- If you physically uninstall this SSD after extension, the Olares file system will be incomplete, causing the OS to crash or fail to boot. You will need to manually reinstall Olares OS.
:::
The Olares One motherboard includes two PCIe SSD slots:
* PCIe 5.0 slot: Occupied by the preinstalled 2TB system SSD.
* PCIe 4.0 slot: Available for expansion.
You can use the PCIe 4.0 slot to expand your current system storage.
## Prerequisites
**Hardware**
- Your Olares One is set up and running.
- A secondary NVMe M.2 SSD is physically installed in Olares One.
**SSH access**
- [SSH access to Olares One](access-terminal-ssh.md).
**Experience**
- Basic familiarity with terminal commands and the command-line interface (CLI).
## Step 1: Identify the unmounted disk
1. Connect to your Olares One terminal via SSH or from the Control Hub.
2. List block devices on the host:
```bash
lsblk | grep -v loop
```
3. Check the size and mount points to identify the new disk.
Example output:
```text
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sda 8:0 0 931.5G 0 disk
├─sda1 8:1 0 512M 0 part /boot
└─sda2 8:2 0 931G 0 part /
nvme1n1 259:3 0 931.5G 0 disk
```
In this example, `sda` is the system drive which is mounted at `/` and `/boot`, while `nvme1n1` is the new, unmounted SSD.
## Step 2: Extend system storage
1. Verify that Olares recognizes the unmounted disk:
```bash
olares-cli disk list-unmounted
```
2. Run the extension command:
```bash
sudo olares-cli disk extend
```
3. When the command prompts for confirmation, type `YES` to proceed.
```bash
WARNING: This will DESTROY all data on /dev/
Type 'YES' to continue, CTRL+C to abort:
```
Example output:
```bash
Selected volume group to extend: olares-vg
Selected logical volume to extend: data
Selected unmounted device to use: /dev/nvme0n1
Extending logical volume data in volume group olares-vg using device /dev/nvme0n1
WARNING: This will DESTROY all data on /dev/nvme0n1
Type 'YES' to continue, CTRL+C to abort: YES
Selected device /dev/nvme0n1 has existing partitions. Cleaning up...
Deleting existing partitions on device /dev/nvme0n1...
Creating partition on device /dev/nvme0n1...
Creating physical volume on device /dev/nvme0n1...
Extending volume group olares-vg with logic volume data on device /dev/nvme0n1...
Disk extension completed successfully.
id LV VG LSize Mountpoints
1 data olares-vg <3.63t /var,/olares
2 root olares-vg 100.00g /
3 swap olares-vg 1.00g
...
```
## Step 3: Verify the extension
You can verify the storage increase from Control Hub (UI), or via the command line.
1. Open Dashboard.
2. Check the Disk section to confirm the total system storage capacity has increased.
1. Check the total size of the `/olares` directory:
```bash
df -h /olares
```
Example output:
```text
Filesystem Size Used Avail Use% Mounted on
/dev/mapper/olares--vg-root 1.8T 285G 1.4T 17% /olares
```
The **Size** column should now reflect the combined capacity.
2. Confirm the disk structure:
```bash
lsblk | grep -v loop
```
Example output:
```bash
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
nvme0n1 259:0 0 1.9T 0 disk
└─nvme0n1p1 259:2 0 1.9T 0 part
└─olares--vg-data 252:2 0 3.6T 0 lvm /olares /var
nvme1n1 259:3 0 1.9T 0 disk
├─nvme1n1p1 259:4 0 512M 0 part /boot/efi
└─nvme1n1p2 259:5 0 1.9T 0 part
├─olares--vg-root 252:1 0 100G 0 lvm /
└─olares--vg-swap 252:0 0 1G 0 lvm [SWAP]
```
You should see your new disk (e.g., `nvme0n1`) listed under the `olares--vg-data` group, sharing the same mount point as your primary data partition.
## Resources
- [Expand storage via USB devices](expand-storage-usb-drive.md)
- [Expand storage using external SSD](expand-storage-external-ssd.md)
---
### One Expand Storage Usb Drive (`docs/one/expand-storage-usb-drive.md`)
---
outline: [2, 3]
description: Learn how to expand storage on Olares One using USB devices.
head:
- - meta
- name: keywords
content: Olares One, USB storage, expand storage, file management
---
# Expand storage via USB devices
Olares One automatically detects and mounts inserted USB storage devices, allowing you to instantly expand your storage capacity for media, backups, or file transfers.
## Prerequisites
**Hardware**
- A compatible USB flash drive.
:::warning Compatibility
Olares One is tested with Samsung and SanDisk USB drives. Other brands might not be recognized by the system.
:::
## Connect and access storage
1. Insert your USB flash drive into an available USB port on Olares One. It will be mounted automatically.
2. Open the Files app and select **External** in the sidebar to access your files.
## Safely remove the device
Although the system automatically unmounts the device when you physically unplug it, removing a drive while data is being written can cause file corruption.
It is recommended to manually eject the device first:
1. Open the Files app.
2. Right-click the USB drive in the sidebar and select **Unmount**.
3. Once the drive disappears from the list, you can safely unplug it.
## Resources
- [Manage files in Olares](../manual/olares/files/index.md)
- [Expand storage using external SSD](expand-storage-external-ssd)
- [Expand storage using internal SSD](expand-storage-internal-ssd.md)
---
### One Factory Reset In Bios (`docs/one/factory-reset-in-bios.md`)
---
outline: [2, 3]
description: Learn how to restore BIOS defaults on Olares One to return the device to its initial setup state.
head:
- - meta
- name: keywords
content: Olares One, BIOS defaults, restore, BIOS setup
---
# Restore BIOS defaults
Restoring BIOS defaults resets the firmware configuration and returns your Olares One to its initial setup state. If you have a monitor and keyboard connected, you can perform this directly in BIOS.
:::warning Data loss
This will permanently delete all accounts, settings, and data on the device. This action cannot be undone.
:::
## Prerequisites
**Hardware**
- A wired keyboard connected to your Olares One.
- A monitor connected to your Olares One.
## Step 1: Load optimized defaults in BIOS
1. Power on Olares One or restart it if it is already running.
2. When the Olares logo appears, immediately press the **Delete** key repeatedly to enter **BIOS setup**.
3. Press **F9**, then select **Yes** to restore factory settings.
4. Press **F10**, then select **Yes** to save and exit. The device restarts automatically.
Once finished, Olares One reboots into the initial setup phase.
## Step 2: Complete activation via LarePass
You can then activate Olares One again via LarePass. For detailed instructions, see [First boot](first-boot.md).
---
### One Factory Reset (`docs/one/factory-reset.md`)
---
outline: [2, 3]
description: Learn how to factory reset your Olares One using LarePass.
head:
- - meta
- name: keywords
content: factory reset, Olares One, LarePass
---
# Factory reset via LarePass
If you have already activated Olares One and want to return it to the factory state, you can perform a reset in LarePass.
:::warning Data loss
This will permanently delete all accounts, settings, and data on the device. This action cannot be undone.
:::
## Prerequisites
**Hardware**
- Olares One is powered on.
- Your phone and Olares One are on the same network.
- You are signed in to LarePass as an administrator.
## Reset Olares One to factory settings
1. Open LarePass on your phone and go to **Settings**.
2. In the **My Olares** card, tap **System** to open the **Olares management** page.
3. Tap **Restore to factory settings**.
4. Review the risk prompt carefully, then tap **Restore to factory settings** to continue.
5. Enter your local LarePass lock-screen password and tap **Confirm**.
If you have not set a local password, you will be prompted to set one first.
6. Wait for the reset process to complete.
Once finished, Olares One reboots into the initial setup phase. You are redirected to the activation flow, where you can scan the local network to reactivate Olares.
For detailed instructions, see [First boot](first-boot.md).
---
### One Faq (`docs/one/faq.md`)
---
outline: [2,3]
description: Frequently asked questions regarding Olares One
head:
- - meta
- name: keywords
content: Olares One, Olares, personal cloud
---
# Olares One FAQs
Find answers to frequently asked questions about Olares One and system capabilities.
:::tip Support for Olares One owners
If you require assistance with product features, hardware warranty, or specific use cases, contact technical support directly via WhatsApp or email at hi@olares.com. We respond to inquiries within two business days.
:::
## Product & specifications
### What is Olares One?
Olares One is a dedicated personal cloud device designed for local AI. It integrates workstation-grade hardware with Olares OS, an open-source operating system that allows you to run AI agents and store data on hardware you physically control.
### What is a personal cloud?
A personal cloud is a private infrastructure that replicates the utility of public cloud services, such as anywhere-access to files and computing power. It runs entirely on your own hardware to ensure data sovereignty.
### What are the technical specifications for Olares One?
* **Processor**: Intel Ultra 9 275HX
* **GPU**: NVIDIA RTX 5090 Mobile
* **Memory**: 96GB RAM
* **Storage**: 2TB NVMe SSD
For details, see [Olares One specifications](spec).
### How loud is the device?
Olares One operates quietly even under load. In lab testing, the device generates 19dB when idle and remains under 39dB under maximum load.
### What is the power consumption?
The device consumes 30W in standby. Under load, the GPU power depends on your selected mode:
* **Silent Mode**: GPU 50W
* **Performance Mode**: GPU 175W
When the CPU is fully utilized on its own, power consumption reaches 120W. During combined maximum load, the system balances power distribution with the CPU operating at 55W and the GPU at 175W. The thermal design sustains these performance levels.
### What ports are available?
The device includes the following physical ports:
* 1 × Thunderbolt 5 with 80 Gbps bandwidth
* 1 × RJ45 Ethernet at 2.5 Gbps
* 1 × USB-A 3.2 Gen2 with 10 Gbps speed
* 1 × HDMI 2.1 with 48 Gbps bandwidth
### How is Olares One different from DGX Spark, AI Max+ 395 and other AI PCs?
Olares One functions as a personal cloud solution rather than a traditional personal computer.
A personal cloud runs as a stable, external service accessible anytime from any device. A PC acts as client-based software designed for direct interaction via a monitor and keyboard.
Olares One utilizes the NVIDIA CUDA stack on x86 architecture. This ensures broad compatibility with standard open-source AI applications, avoiding the adaptation challenges often found in ARM-based AI PCs or devices without CUDA support.
Olares OS simplifies local AI with one-click deployment and workflow integration, distinct from the manual software management typical of standard PCs.
### Is it possible to upgrade or expand the hardware?
Yes. You can modify the hardware through several internal slots and expansion ports:
* **Storage**: The motherboard includes two PCIe SSD slots, one PCIe 4.0 and one PCIe 5.0. The preinstalled 2TB SSD occupies the PCIe 5.0 slot. The PCIe 4.0 slot remains available for system storage expansion via LVM or for a dual-boot configuration.
* **Memory**: The RAM capacity can be upgraded to a maximum of 128GB.
* **External graphics**: You can connect a compatible Thunderbolt external graphics device. See [Can I use an eGPU with Olares One?](#can-i-use-an-egpu-with-olares-one)
* **External displays**: The Thunderbolt 5 port supports docking stations with up to two external monitors at up to 8K resolution. The built-in RTX 5090 Mobile handles video output.
### Can I use an eGPU with Olares One?
Yes. You can connect a Thunderbolt external graphics device with a GPU already installed, or install a compatible desktop NVIDIA GPU in a powered eGPU dock or enclosure. Hardware compatibility and setup differ between Olares OS and Windows 11.
See [Connect an eGPU to Olares One](egpu.md) for known compatibility, current limitations, and setup instructions.
### Is there a way to view the Olares OS UI via HDMI?
Currently, the HDMI output displays an Ubuntu shell or Steam Headless output for gaming, rather than a full desktop UI like a traditional PC.
We plan to introduce the ability to run a lightweight browser or ChromeOS instance directly via HDMI in future updates.
### Can I update or configure the BIOS?
Yes. You can update the BIOS and Embedded Controller (EC) firmware as new versions release. While the system hides advanced BIOS options by default to maintain stability, you can also unlock them to perform deep hardware configurations according to your needs.
For detailed instructions, see [Manage BIOS](../one/update-firmware.md).
### Is Olares One designed for "always-on" operation?
Yes. Olares One functions as a personal AI cloud and reliably supports 24/7 continuous operation for scenarios like Large Language Model (LLM) hosting.
### Does Olares One support out-of-band management?
Support for common out-of-band management capabilities on Olares One is as follows:
- **Automatic startup**: Supported. Olares One can start automatically when AC power is connected or restored after a power outage.
- On Olares OS, this feature requires Olares OS 1.12.6 or later and EC firmware 1.03 or later. See [Manage hardware settings](hardware-settings.md#set-automatic-startup).
- On Ubuntu, configure the setting from the command line. See **Configure automatic startup** in the [Ubuntu Server](install-ubuntu-server.md#configure-automatic-startup) or [Ubuntu Desktop](install-ubuntu-desktop.md#configure-automatic-startup) installation guide.
- **Wake-on-LAN (WOL)**: Supported on Olares One running Olares OS, Ubuntu, or Windows, with EC firmware 1.01 or later and a wired network connection. For setup and wake-up instructions on the same local network, see [Set up Wake-on-LAN for Olares One](wake-on-lan.md). The Windows steps cover waking from sleep.
- **Remote KVM**: Not supported.
- **IPMI**: Not supported.
### Are there additional fees to use Olares One?
No. Olares OS and system updates are completely free.
### Can I use the device without an internet connection?
After a one-time activation, the device can work entirely offline. You can access it via your local network without an internet connection.
### Does the device prevent data loss during power outages?
Olares One uses the ext4 Linux file system to prevent file system corruption during sudden power loss. The power supply and motherboard design include voltage regulation for hardware protection.
Olares OS also includes a built-in automatic backup mechanism for periodic, encrypted backups to external locations.
We plan to enhance support for UPS devices to ensure graceful shutdowns during power interruptions, alongside native support for snapshot backups similar to Time Machine.
### Does the device support a GPU MUX switch?
Yes. Olares One supports both GPU MUX and Optimus modes. The system defaults to GPU MUX mode to enable a direct connection to the discrete GPU. Change this setting in the BIOS if needed.
## AI & gaming
### Does Olares One support the Kimi K2 model?
Kimi K2 has around 1 trillion parameters and requires approximately 1024 GB of VRAM, making it unavailable in the Olares Market.
We anticipate that a Kimi-K2-level model might run on Olares One in the future as AI model sizes continue to shrink.
### Can local AI models access the internet for research?
Yes. Olares supports several applications that enable internet access:
* **Vane** (formerly Perplexica): An open‑source alternative to Perplexity. It retrieves the latest information using SearxNG and analyzes it with a local LLM.
* **DeerFlow**: An open‑source alternative to OpenResearch. It uses RAGFlow to configure a local knowledge base, integrates Tavily for web search, and performs analysis using a local LLM.
### Can I use a NAS for storage and use Olares for AI processing?
Yes, we highly recommend this workflow. You can mount your NAS to Olares One as an SMB share. Olares can then index, sort, and process the photos and videos stored on the NAS via apps like Immich.
### Can I use Olares AI features on my iPhone or Mac?
Yes. Olares supports secure remote access. You can use your iPhone or Mac to query the AI models running on your Olares One from anywhere.
### How does the 120B model perform on Olares One?
We tested the `gpt-oss:120b` model. Since the model size exceeds the dedicated GPU memory, the system loads part of the model into the 96GB of system memory for CPU processing.
In our testing, `gpt-oss:120b` achieves approximately 36.16 tokens/s.
For better efficiency, we recommend `qwen3-30b-a3b`. It delivers superior results while remaining significantly smaller, reaching speeds of up to 157 tokens/s, or around 81 tokens/s with 8 concurrent requests.
For the detailed testing methodology, see [Local AI Hardware Performance Benchmarking](https://blog.olares.com/local-ai-hardware-performance-benchmarking/).
### Can I use LM Studio to manage models on Olares?
LM Studio functions as a client-side desktop application rather than a server-side service, so it cannot be installed directly on Olares One.
However, you have two alternatives:
* Use native apps, such as OpenWebUI or LobeHub (formerly LobeChat), which offer similar functionality.
* Run a local instance of LM Studio on your computer and configure it to access the AI models hosted on Olares One via API.
### Does performance drop if I load multiple models simultaneously?
Loading multiple models that exceed GPU memory typically causes a crash. Olares addresses this with a time-slicing mechanism.
The system temporarily swaps models not actively in use to the 96GB system memory, and loads the active model into the GPU. This keeps multiple models ready with only about a 5% performance overhead during switching.
Alternatively, you can:
- Split the GPU memory so multiple apps run simultaneously without swapping.
- Assign the entire GPU to a single application for maximum raw performance.
Switch these modes directly from Olares Settings without additional modifications.
### Is the device capable of high-end gaming?
Yes. You can connect a monitor to play directly via Steam, or use the device as a game server to stream titles to your laptop, TV, or phone via Moonlight.
### Can I use Olares One for VR devices such as Quest 3?
We are actively testing compatibility with VR and AR devices, such as Quest 3, to include support in future updates.
### How does gaming performance compare to Windows?
Olares One supports gaming by streaming as a Steam server via Moonlight, or playing directly via a connected monitor.
In direct play scenarios, testing shows Cyberpunk 2077 achieves approximately 90% of the performance compared to the same hardware running Windows. This aligns with other high-end Linux gaming setups. We anticipate further compatibility improvements as SteamOS adoption grows.
## Operating system
### Can I run Windows on Olares One?
Yes. To run occasional Windows applications, install the Windows app from the Olares Market. This runs a virtual machine accessible via RDP, providing a seamless remote desktop experience when used with the built-in VPN.
Alternatively, you can install a second internal drive for a dual-boot setup or replace Olares OS with a native Windows installation.
### Can the Windows VM use the GPU?
Currently, GPU passthrough is not supported. The NVIDIA RTX 5090 Mobile functions as the primary GPU for Olares OS to power local AI applications. Assigning it to a virtual machine would detach it from the host OS and disable these features.
Windows VMs utilize the integrated Intel graphics, which handle lightweight tasks effectively. For GPU-intensive workloads like gaming, we recommend setting up a dual-boot configuration.
### Can I wipe Olares OS and install Linux or Windows natively?
Yes. You have full ownership of the hardware. You can wipe the pre-installed OS to install Windows or any Linux distribution. In this configuration, Olares One functions as a standard high-performance workstation equipped with an NVIDIA RTX 5090 Mobile GPU, allowing you to use a monitor, keyboard, and mouse like a standard desktop computer.
### How to set up a dual-boot system?
We recommend installing a second NVMe SSD in the available slot to keep the operating systems on separate drives.
For a clean installation, install Windows first, followed by Olares OS.
Since Olares OS is based on Ubuntu 24.04, it follows standard Linux dual-boot procedures.
### Does the system support switching between Olares OS and Windows?
Yes. Both the UEFI Boot Manager and GRUB support this configuration. You can set Olares OS as the persistent default boot option in the BIOS. To boot into Windows for specific tasks like gaming, select the Windows Boot Manager during the startup sequence.
## Clustering
### Is it possible to connect two Olares One units together?
Yes. Olares OS is built on Kubernetes, which allows multiple Olares devices to form a cluster. The system automatically schedules applications within the cluster and loads models across multiple devices.
Forming a cluster currently requires command-line operations. We plan to introduce a fully UI‑based experience to manage this process in future updates.
### Does clustering make a single game or AI task run faster?
No. Clustering improves total system throughput and concurrency, but it does not double the speed of a single task.
For example, by clustering two units:
- You can run Elden Ring on one unit and Cyberpunk 2077 on another simultaneously. However, you cannot combine two units to run a single instance of Cyberpunk 2077 at double the frame rate.
- You can generate two images in 6 seconds, rather than generating a single image in 3 seconds.
### How does clustering benefit AI workloads?
Clustering supports larger models or complex workflows that a single device cannot handle.
For LLMs, the system uses vLLM pipeline parallelism to distribute the model across multiple units. This supports much larger models than a single device handles, though inference speed decreases compared to using multiple GPUs on a single motherboard due to network latency.
It also enables complex pipelines. For example, you can run a digital human application where the LLM runs on one node while the Text-to-Speech (TTS) and Automatic Speech Recognition (ASR) services run on another.
### Does clustering increase the available memory?
Yes. The total available memory capacity roughly doubles when connecting two identical units. The system distributes applications across nodes to maximize available resources.
### Can I cluster with third-party devices like Mac Studio or DGX Spark?
Currently, Olares supports clustering only for devices with the same architecture running the same OS.
We plan to add clustering compatibility for third-party devices, such as Mac Studio, DGX Spark, and AI MAX 395+, in future updates.
### Can I use a NAS as part of the cluster?
No. Most NAS operating systems use closed environments and cannot run Olares nodes.
However, Olares One can mount NAS directories via the SMB protocol. This allows you to manage files on your NAS as if they were local folders on the Olares One.
### How does GPU scheduling work in a cluster?
Olares OS manages GPU allocation at the operating system level. GPU scheduling falls into four stages of complexity:
1. Single node, single GPU.
2. Single node, multiple GPUs.
3. Multiple nodes, multiple GPUs with the same architecture.
4. Multiple nodes, multiple GPUs with different architectures.
Olares currently operates at Stage 3, clustering multiple devices running the same OS and architecture.
Stage 4 remains partially automated and requires manual intervention, such as pulling the specific container images for the corresponding architecture. We plan to rewrite the scheduling algorithm to automate this support in future updates.
### Is federated learning or shared compute supported?
We are exploring advanced computing models, including federated learning, distributed AI training, and shared compute networks.
While the hardware easily handles these workloads, building a stable, production-ready solution is a long-term goal. Ultimately, these features rely on third-party applications rather than the core operating system.
### Why is the Ethernet port limited to 2.5Gbps if the device is meant for clustering?
We understand that 10Gbps is preferred for clustering to maximize data transfer between nodes. However, the inclusion of a 2.5Gbps Ethernet port is a strict limitation imposed by the hardware platform vendor.
## Advanced usage and configuration
### Does Olares support multiple users with their own accounts?
Yes. Olares functions as a multi‑user system. You can create separate accounts for friends or family, and they can connect using their own LaresPass app.
The system supports three account roles:
* **Super Admin**: The user who initially activates the system and manages admins.
* **Admin**: Perform cluster‑level tasks.
* **Member**: Access shared services.
### Can I host a mail server on Olares One?
Hosting a mail server is technically possible but complex.
Olares supports open‑source solutions like Mail‑in‑a‑Box, Mailserver, and Mailcow. However, major providers often flag self-hosted email servers as spam, making reliable delivery difficult.
### Is it possible to install a VPN for outbound traffic?
Yes. Olares provides built-in support for Tailscale and Headscale. Configure and use a specific exit node for your outbound traffic.
### Do I need a static IP to host Olares One as a server?
No. Olares provides two external access options: reverse proxy and VPN. These solutions allow you to securely access your device from anywhere without a static IP.
### Can I use my own domain to access Olares One?
Yes. You can host Olares One using your own domain name.
Currently, you must point the NS records of your subdomain to Olares' name servers to set up the reverse proxy.
We plan to introduce updates for users who wish to manage their own reverse proxy or do not require public internet access.
### Is there a way to access the device without the internet?
Yes. Olares provides a fully local access option using a `.local` domain.
If the device resides on a LAN but lacks public access, use the `.local` domain to access all features normally. Without internet connectivity, features relying on external services, such as the Olares Market, remain unavailable.
### Can Olares One function as a media server?
Yes. Olares One can function as a Plex server. It supports hardware-accelerated transcoding and utilizes both the CPU and GPU for efficient decoding.
### Can I use SMB to sync or back up files to a NAS?
Yes. Olares One supports SMB sharing, allowing you to sync files with or back up data to an external NAS.
### Is the file system encrypted?
By default, the system does not use full-disk encryption. We plan to make this a standard, user-configurable option in future updates.
---
### One First Boot (`docs/one/first-boot.md`)
---
description: Set up Olares One for the first time. Connect the hardware, install LarePass, create an account, activate the system, and log in.
head:
- - meta
- name: keywords
content: Olares, Olares One, first boot, initial setup, first time use
---
# First boot
This guide walks you through setting up your Olares One for the first time.
## Setup overview
- You do not need to connect a monitor, keyboard, or mouse to the Olares One. The entire configuration is handled via your mobile phone.
- The LarePass app is your primary tool for initial setup, authentication, and remote access management.
## Prerequisites
**Hardware**
- Olares One connected to Power.
- (Recommended) An Ethernet cable connecting Olares One to your router.
**Network**
- A reliable internet connection.
- Your mobile phone (iOS or Android) connected to the same network.
## Step 1: Power on and install LarePass
1. Power on Olares One. The status LED turns solid white, indicating the device is powered on.
2. Search for "LarePass" in the Apple App Store or Google Play Store. Install and open the app on your mobile device.
3. Follow the on-screen instructions to create your Olares ID. This unique identifier acts as your username across the entire Olares ecosystem.
{width=90%}
## Step 2: Connect Olares One
Once your ID is ready, you need to discover and link your Olares One.
1. Ensure your Olares One is connected to your router via Ethernet.
2. In the LarePass app, tap **Discover nearby Olares**.
{width=90%}
3. Select your Olares One from the list of available devices.
If wired access is not available, use Bluetooth to configure Wi-Fi credentials.
1. In the LarePass app, tap **Discover nearby Olares**.
2. Tap **Bluetooth network setup** at the bottom.
3. Select your device from the Bluetooth list and tap **Network setup**.
4. Follow the prompts to connect Olares One to the Wi-Fi network your phone is currently using.
5. Once connected, return to the main screen and tap **Discover nearby Olares** again to find your device.
## Step 3: Install & activate Olares OS
1. In the LarePass app, on the device you just found, tap **Install now**.
2. When installation finishes, tap **Activate now** to initialize the system.
3. Select a reverse proxy node that is closest to your location and tap **Confirm**. The reverse proxy node acts as a secure gateway for remote access. Choosing the nearest node ensures the fastest connection speed and best stability.
4. Select the language for Olares. Olares supports English, Simplified Chinese, German, Spanish, Italian, French, and Japanese.
:::info
This selection does not change the language of the LarePass app. The remaining activation steps stay in the current LarePass language. After activation, Olares Desktop uses the language selected here.
:::
5. Set the login password for Olares.
6. Copy or note down your personal desktop URL. You need this URL to access your Olares services.
7. Tap **Got it** to close the prompt.
## Step 4: Login to Olares Desktop
1. Open a web browser on your computer and go to your desktop URL.
2. On the login page, enter your login password.
3. You will be prompted to complete two-factor verification. Open LarePass to approve the login request, or manually enter the 6-digit verification code displayed in the app.
::: info
The verification code is time-sensitive. Ensure you enter it before it expires.
:::
## Next steps
Congratulations! Your Olares One is set up and active. It is strongly recommended to complete the following steps to secure your account and optimize your experience.
### Back up mnemonic phrase
:::warning Security warning
You are responsible for your security. Never share this phrase. If you lose these 12 words, you will permanently lose access to your Olares ID and all data stored in your Vault.
:::
Your Olares ID is secured by a unique 12-word mnemonic phrase. This phrase is the sole method to recover your account if you lose your phone or need to log in on a new device.
1. Open the LarePass app and go to **Settings** > **Safety**.
2. Tap **Mnemonic phrase** and verify your identity.
3. Tap **Click to view**.
4. Enter the local password as prompted.
5. Write the 12 words onto the **Recovery Sheet**, and then store the sheet in a secure, offline location.
### Reset SSH password
For instructions on how to SSH into Olares One, see [Connect to Olares One via SSH](access-terminal-ssh.md).
### Access Olares services securely
For secure remote access without complex network configuration, it is recommended to enable the LarePass VPN.
See [Access Olares services securely using LarePass VPN](access-olares-via-vpn.md).
### Explore
Olares OS comes with pre-installed system apps. You can also browse the **Market** to download additional applications that best suit your needs.
You can continue browsing this documentation to discover more use cases and advanced configuration scenarios.
## FAQs
For details, refer to [Set up a custom domain for your Olares](/manual/best-practices/set-custom-domain.md).
## Resources
- [Access Olares using local network](access-olares-via-vpn.md)
- [Olares ID](../developer/concepts/olares-id.md)
- [Back up mnemonic phrase](../manual/larepass/back-up-mnemonics.md)
---
### One Hardware Settings (`docs/one/hardware-settings.md`)
---
description: View Olares One hardware details and manage power mode, CPU frequency, automatic startup, and the SSH login password.
head:
- - meta
- name: keywords
content: Olares One, hardware settings, power mode, CPU frequency, automatic startup, SSH login password, My hardware
---
# Manage hardware settings
On the **My Olares** > **My hardware** page in Settings, you can view hardware details and manage performance options for your Olares One.
## View hardware details
Check information such as **Model**, **Device status**, **Device Identifier**, **CPU**, and **GPU**.
## Switch power mode
Olares One supports two performance profiles:
- **Silent mode**: Limits CPU and GPU power for quiet operation, suitable for everyday workloads.
- **Performance mode**: Enables maximum CPU and GPU performance for demanding tasks such as AI inference or gaming.
## Limit CPU frequency
Turn on this switch to limit the CPU frequency from 5.4 GHz to 5.0 GHz. Turn it off to restore the original maximum frequency.
## Set automatic startup
Turn on this switch to start the device automatically when power is connected or restored after a power outage.
:::info
Requires Olares OS 1.12.6 or later and EC firmware 1.03 or later. If either prerequisite is not met, the toggle is visible but disabled.
To check your current EC firmware version or update EC firmware, see [Manage BIOS and EC](update-firmware.md).
:::
## Reset SSH password
To use your own SSH password instead of the one generated during activation, reset it in Settings:
1. At the bottom of the **My hardware** page, click **Reset SSH login password**.
{width=70%}
2. Enter a new SSH password that meets all strength requirements, then click **OK**.
3. Open the LarePass app and scan the QR code shown on the screen.
4. Tap **Confirm** in LarePass to finish. The new SSH password is saved to Vault.
---
### One Install Nvidia Driver (`docs/one/install-nvidia-driver.md`)
---
outline: [2, 3]
description: Learn how to download and use the all-in-one driver package provided by Olares to install all necessary Windows drivers, including the NVIDIA graphics driver.
head:
- - meta
- name: keywords
content: Olares, Olares One, Windows drivers, NVIDIA graphics driver, GPU
---
# Install drivers on Windows
To ensure optimal performance and system stability when running Windows on your Olares One, Olares provides a tested all-in-one driver package. This package contains all the necessary drivers for your device, such as audio, network, and NVIDIA graphics drivers.
This guide walks you through downloading and installing the all-in-one driver package.
## Learning objectives
- Download and install all system drivers using the driver package.
## Before you begin
:::info About NVIDIA graphics driver update
This all-in-one package includes a stable, fully tested NVIDIA graphics driver specifically optimized for Olares One. To ensure system stability, avoid downloading and installing standalone graphics drivers directly from the official NVIDIA website, because that might introduce compatibility issues.
:::
- **Administrator access**: You need admin rights to install system drivers.
- **Internet connection**: The driver file is large (about 3.5 GB), so a stable connection is required.
- **Close applications**: Save your work and close any graphic-intensive programs like games or photo editors before starting the installation. The screen might temporarily turn black or blink during the update, which can cause open applications to crash or lose unsaved data.
- **Windows version**: For the best stability and driver compatibility, Windows 11 version 24H2 is recommended.
## Step 1: Download and extract the driver package
1. Download the [driver package](https://cdn.olares.com/common/OlaresOne_driver_251125.zip).
:::info Download time
The driver package is large. Depending on your internet connection speed, the download might take a while to complete.
:::
2. Locate the downloaded `.zip` file on your computer.
3. Right-click the file and select **Extract All**.
4. Open the extracted folder and verify that the files, including the `driver_install` application, are present.
```text
Extracted_Folder/
├── driver/
├── uwp/
├── driver_install
└── uwp_install
```
## Step 2: Install the drivers
1. In the extracted folder, locate the file `driver_install`, and then double-click it.
2. The system will automatically open a command prompt window and begin installing the driver. This process is fully automated.
:::tip Screen flickering
Your screen might turn black or blink for a few seconds during installation. This is normal behavior as the system switches to the new driver.
:::
3. When the driver is successfully installed, your device restarts automatically.
4. After the system reboots and you log back in to Windows, a command prompt window appears. Follow the on-screen instructions and press any key until the window closes. This indicates that the installation is completely finished.
---
### One Install Ubuntu Desktop (`docs/one/install-ubuntu-desktop.md`)
---
outline: [2,3]
description: Reinstall Olares One with Ubuntu Desktop by replacing the existing Olares OS on the primary SSD.
head:
- - meta
- name: keywords
content: Olares One, Ubuntu Desktop, NVMe SSD, OS installation, clean install, graphical setup
---
# Install Ubuntu Desktop on Olares One
Replace the pre-installed Olares OS with a clean installation of Ubuntu Desktop on the primary NVMe SSD of Olares One.
:::danger This erases Olares OS
Installing Ubuntu Desktop on the primary drive permanently deletes Olares OS, local accounts, installed apps, settings, and data stored on that drive. Back up anything you need before continuing.
:::
## Learning objectives
By the end of this guide, you will learn how to:
- Create a bootable Ubuntu Desktop installation USB drive.
- Boot Olares One from the installation USB drive.
- Overwrite the primary drive and install Ubuntu Desktop.
## Prerequisites
**Hardware**
- The primary NVMe M.2 SSD installed inside Olares One.
- A USB flash drive (8 GB or larger) for the installation media.
- A wired keyboard and mouse.
- A monitor connected to Olares One.
## Step 1: Create a bootable Ubuntu Desktop USB drive
1. Download the Ubuntu Desktop ISO from the [official Ubuntu website](https://ubuntu.com/download/desktop).
2. Download and install [balenaEtcher](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open balenaEtcher and follow these steps:
a. Click **Flash from file** and select the downloaded ISO.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait for the flashing and validation processes to finish, and then safely eject the USB drive.
## Step 2: Boot from the Ubuntu Desktop USB drive
1. Insert the Ubuntu Desktop USB drive into the USB port on Olares One.
2. Power on Olares One, or restart it if it is currently running.
3. When the Olares logo appears, press the **Delete** key repeatedly to enter the BIOS setup.
4. Go to the **Save & Exit** tab.
5. Under the **Boot Override** section, select your USB drive from the list, and then press **Enter**.
The system boots from the USB drive into the Ubuntu Desktop graphical boot menu.
## Step 3: Install and configure Ubuntu Desktop
The graphical installation wizard guides you through replacing Olares OS on the primary drive.
1. In GNU GRUB, select **Try or Install Ubuntu**. Wait for the initial loading sequence to finish and the language selection screen to appear.
2. Follow the on-screen prompts to finish the standard setup.
3. When you see Ubuntu is installed and ready to use, click **Restart now**.
4. Remove the installation USB drive and press **Enter** when prompted. The system restarts and reboots into your fresh Ubuntu Desktop environment.
5. Log in using the account credentials you set during configurations.
## Configure automatic startup
Configure Olares One to start automatically when AC power is connected or restored after a power outage.
:::warning Olares One only
These commands access the Embedded Controller (EC) directly and apply only to Olares One. Do not run them on another device.
:::
1. Confirm that the EC firmware is version 1.03 or later. To check the version or update the firmware, see [Manage BIOS and EC](update-firmware.md).
2. Install `ioport`:
```bash
sudo apt install ioport
```
3. Enable automatic startup:
```bash
sudo outb 0x302 0x5e && sudo outb 0x303 0x01
```
This writes the persistent automatic startup setting to the EC.
The setting remains enabled across restarts, power outages, and operating system reinstalls. You might need to configure it again after updating the EC firmware.
To optionally verify the setting:
1. Fully shut down Olares One.
2. Disconnect AC power briefly.
3. Reconnect AC power.
Olares One should start automatically.
## Resources
- [Configure the GPU mode on Ubuntu](configure-gpu-mode.md)
- [Install Ubuntu Server on Olares One](install-ubuntu-server.md)
- [Ubuntu Desktop documentation](https://documentation.ubuntu.com/desktop/en/latest/)
---
### One Install Ubuntu Server (`docs/one/install-ubuntu-server.md`)
---
outline: [2,3]
description: Reinstall Olares One with Ubuntu Server by replacing the existing Olares OS on the primary SSD.
head:
- - meta
- name: keywords
content: Olares One, Ubuntu Server, NVMe SSD, OS installation, clean install
---
# Install Ubuntu Server on Olares One
Replace the pre-installed Olares OS with a clean installation of Ubuntu Server on the primary NVMe SSD of Olares One.
:::danger This erases Olares OS
Installing Ubuntu Server on the primary drive permanently deletes Olares OS, local accounts, installed apps, settings, and data stored on that drive. Back up anything you need before continuing.
:::
## Learning objectives
By the end of this guide, you will learn how to:
- Create a bootable Ubuntu Server installation USB drive.
- Boot Olares One from the installation USB drive.
- Overwrite the primary drive and install Ubuntu Server.
## Prerequisites
**Hardware**
- The primary NVMe M.2 SSD installed inside Olares One.
- A USB flash drive (8 GB or larger) for the installation media.
- A wired keyboard and mouse.
- A monitor connected to Olares One.
## Step 1: Create a bootable Ubuntu Server USB drive
1. Download the Ubuntu Server ISO, version 26.04 LTS or later, from the [official Ubuntu website](https://ubuntu.com/download/server).
2. Download and install [balenaEtcher](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open balenaEtcher and follow these steps:
a. Click **Flash from file** and select the downloaded ISO.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait for the flashing and validation processes to finish, and then safely eject the USB drive.
## Step 2: Boot from the Ubuntu Server USB drive
1. Insert the Ubuntu Server USB drive into the USB port on Olares One.
2. Power on Olares One, or restart it if it is currently running.
3. When the Olares logo appears, press the **Delete** key repeatedly to enter the BIOS setup.
4. Go to the **Save & Exit** tab.
5. Under the **Boot Override** section, select your USB drive from the list, and then press **Enter**.
The system restarts and boots from the USB drive into the Ubuntu Server installation interface.
## Step 3: Install and configure Ubuntu Server
The text-based installation wizard guides you through replacing Olares OS on the primary drive.
1. In GNU GRUB, select **Try or Install Ubuntu Server**. Wait for the initial loading sequence to finish and the language selection screen to appear.
2. Select your language, and then press **Enter**.
3. Keep the default English US keyboard layout, and then press **Enter**.
4. On the **Choose the type of installation** screen, select **Ubuntu Server**, and then press **Enter**.
5. On the **Network configuration** screen, skip network configuration for now by selecting **Continue without network** at the bottom, and then press **Enter**.
:::tip
Connecting to the network triggers automatic background downloads for patches and dependencies. This can significantly delay the installation and might cause the installer to hang due to network fluctuations. Skipping this ensures a rapid, completely local installation from the pure ISO image.
:::
6. On the **Proxy configuration** screen, leave it blank unless your environment requires one, and then press **Enter**.
7. On the **Ubuntu archive mirror configuration** screen, keep the default Ubuntu archive mirror URL, ignore the "no network" warning, and then press **Enter**.
8. On the **Guided storage configuration** screen:
a. Ensure **Use an entire disk** is selected, and the primary disk containing Olares OS is displayed in the dropdown list below.
b. Go down to **Set up this disk as an LVM group** and clear the selection using the **Space** key.
:::tip
Disabling LVM forces the installer to automatically create stable, straightforward standard ext4 partitions. This eliminates unnecessary complexity and ensures a clean, traditional partition layout.
:::
c. Go to the bottom of the page, select **Done**, and then press **Enter**.
9. Verify the details on the **Storage configuration** summary screen. Under **USED DEVICES**, ensure the primary drive is in the "to be formatted" status, and then press **Enter**.
10. In the **Confirm destructive action** window, select **Continue**, and then press **Enter**.
11. On the **Profile configuration** screen, set up your account credentials, select **Done** at the bottom, and then press **Enter**.
12. On the **Upgrade to Ubuntu Pro** screen, select **Skip Ubuntu Pro setup for now**, and then press **Enter**.
13. On the **SSH Configuration** screen, select **Install OpenSSH server** to allow remote terminal management after connecting to the network later, and then press **Enter**.
14. The system begins deployment. Wait for the top banner to display **Installation complete**.
15. Select **Reboot Now** at the bottom, and then press **Enter**.
16. Remove the installation USB drive and press **Enter** when prompted. The system restarts automatically into your fresh Ubuntu Server environment.
17. Log in using the account credentials you set previously.
## Configure automatic startup
Configure Olares One to start automatically when AC power is connected or restored after a power outage.
:::warning Olares One only
These commands access the Embedded Controller (EC) directly and apply only to Olares One. Do not run them on another device.
:::
1. Confirm that the EC firmware is version 1.03 or later. To check the version or update the firmware, see [Manage BIOS and EC](update-firmware.md).
2. Install `ioport`:
```bash
sudo apt install ioport
```
3. Enable automatic startup:
```bash
sudo outb 0x302 0x5e && sudo outb 0x303 0x01
```
This writes the persistent automatic startup setting to the EC.
The setting remains enabled across restarts, power outages, and operating system reinstalls. You might need to configure it again after updating the EC firmware.
To optionally verify the setting:
1. Fully shut down Olares One.
2. Disconnect AC power briefly.
3. Reconnect AC power.
Olares One should start automatically.
## Resources
- [Configure the GPU mode on Ubuntu](configure-gpu-mode.md)
- [Install Ubuntu Desktop on Olares One](install-ubuntu-desktop.md)
- [Ubuntu Server documentation](https://ubuntu.com/server/docs)
---
### One Install Windows Primary Drive (`docs/one/install-windows-primary-drive.md`)
---
outline: [2, 3]
description: Install Windows on the primary drive of Olares One by replacing Olares OS.
head:
- - meta
- name: keywords
content: Olares One, Windows, primary drive, Olares OS, Windows installation, BIOS
---
# Install Windows on Olares One
Install Windows on the primary drive of Olares One when you want to use the device as a dedicated Windows machine.
This process replaces Olares OS. If you want to keep Olares OS and Windows on the same device, use a dual-boot setup instead.
:::danger This erases Olares OS
Installing Windows on the primary drive permanently deletes Olares OS, local accounts, installed apps, settings, and data stored on that drive. Back up anything you need before continuing.
:::
## Learning objectives
By the end of this guide, you will learn how to:
- Create a bootable Windows installation USB drive.
- Boot Olares One from the Windows USB drive.
- Install Windows on the primary drive by removing the existing Olares OS partitions.
- Install the Windows drivers provided for Olares One.
## Prerequisites
**Hardware**
- A USB flash drive, 8 GB or larger, for Windows installation media.
- A wired keyboard and mouse connected to Olares One.
- A monitor connected to Olares One.
- Connect an Ethernet cable to Olares One, as a wired internet connection is required during Windows setup.
- A Microsoft account for completing the Windows setup process.
## Step 1: Create a bootable Windows USB drive
1. Download the Windows 11 ISO from the [official Microsoft website](https://www.microsoft.com/en-us/software-download/windows11).
2. Download and install [balenaEtcher](https://etcher.balena.io/).
3. Insert the USB flash drive into your computer.
4. Open balenaEtcher and follow these steps:
a. Click **Flash from file** and select the ISO you downloaded.
b. Click **Select target** and select your USB drive.
c. Click **Flash!** to write the installer to the USB drive.
5. Wait for the flashing and validation to finish, and then safely eject the USB drive.
## Step 2: Boot from the Windows USB drive
1. Insert the Windows USB drive into a USB port on Olares One.
2. Power on Olares One, or restart it if it is already running.
3. When the Olares logo appears, press the **Delete** key repeatedly to enter BIOS setup.
4. Go to the **Save and Exit** tab.
5. Under **Boot Override**, select the Windows USB drive, and then press **Enter**.
Olares One restarts and boots into the Windows installer.
:::tip
If a Ventoy screen appears, select the Windows ISO file, and then select **Boot in normal mode**.
:::
## Step 3: Install Windows on the primary drive
The Windows setup wizard guides you through the installation.
1. Follow the on-screen prompts until you reach the **Select location to install Windows 11** screen.
2. Select each existing partition on the primary drive, and then click **Delete**.
:::danger **DO NOT DELETE "Ventoy" or "VTOYEFI" PARTITIONS**
These partitions belong to your USB installer, not the primary drive. Deleting them can corrupt your installation media.
:::
3. After all partitions on the primary drive are deleted, select the resulting **Unallocated Space**.
4. Click **Next** to install Windows.
5. Wait while Windows copies files and restarts several times.
6. When the final setup process starts, follow the on-screen prompts to configure Windows.
7. After the Windows desktop appears, unplug the Windows USB drive.
## Step 4: Install Olares One Windows drivers
Install the tested Olares One driver package after Windows starts. The package includes audio, network, chipset, and NVIDIA graphics drivers.
1. Follow [Install drivers on Windows](install-nvidia-driver.md) to download and install the all-in-one driver package.
2. Restart Windows if the driver installer prompts you to do so.
3. After Windows restarts, check that network, audio, display, and GPU devices are working normally.
---
--- METRICS ---
- Files Extracted: 101
- Estimated Token Budget: ~91861 tokens
- Canonical Reference: https://codewiki.google/github.com/beclab/Olares
