Skip to content

docs: OlaresManifest 0.12.0 spec update #3247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
TShentu wants to merge 10 commits into
base: main
Choose a base branch
from
Draft

docs: OlaresManifest 0.12.0 spec update #3247

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
075a54a
[UPDATE][manifest] OlaresManifest 0.12.0 spec update
Jun 2, 2026
64df517
fix comma
TShentu Jun 3, 2026
d0e1548
fix punctuation marks
TShentu Jun 3, 2026
1d1b822
fix punctuation marks
TShentu Jun 3, 2026
5c6825d
fix apiVersion
TShentu Jun 3, 2026
0693a9d
Revert "docs(use-cases/hermes): add Olares skills, OpenAI API, and re…
TShentu Jun 3, 2026
f9b929d
fix some details
TShentu Jun 3, 2026
9aac1a1
fix mode
TShentu Jun 3, 2026
8a6a407
Apply suggestions from code review
TShentu Jun 23, 2026
b2d30d7
Merge branch 'main' into update-manifest-0.12.0
TShentu Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 110 additions & 14 deletions docs/developer/develop/package/manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,23 @@ outline: [2, 3]
Every **Olares Application Chart** should include an `OlaresManifest.yaml` file in the root directory. `OlaresManifest.yaml` provides all the essential information about an Olares App. Both the **Olares Market protocol** and the Olares depend on this information to distribute and install applications.

:::info NOTE
Latest Olares Manifest version: `0.11.0`
- Removed deprecated fields of sysData
- Updated the example of shared app
- Added the apiVersion
- Added the sharedEntrance section
Latest Olares Manifest version: `0.12.0`
- Modified the `apiVersion` field: added support for `v3` shared applications; the previous `v2` version of shared applications will be deprecated.
- Added `spec.accelerator` field for GPU resource declaration
- Added `workloadReplicas` field to declare all workload replica counts
- Added `overlayGateway` field for L2 overlay LAN discovery support
- Added `LLMGatewaySupported` in options for LLM Gateway support
- Added `appCommon` and `externalData` permissions
- Added `templateOnly` field to mark template-type applications

:::

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add a callout below this note to ask users to give special attention to certain fields when upgrading to 0.12.0?
such as

:::tip Upgrading to Manifest 0.12.0
If you maintain an existing app chart, pay special attention to apiVersion, workloadReplicas, and permission.externalData before upgrading. These fields contain breaking changes or new mandatory requirements that may require updates to your existing configurations.
:::

:::details Changelog
`0.11.0`
- Removed deprecated `sysData` field
- Updated shared app example
- Added `apiVersion` field
- Added `sharedEntrance` section

`0.10.0`
- Modified the `categories` field
- Added the `provider` field in the Permission section
Expand Down Expand Up @@ -111,14 +120,9 @@ options:
## olaresManifest.type

- Type: `string`
- Accepted Value: `app`, `recommend`, `middleware`

Olares currently supports 3 types of applications, each requiring different fields. This document uses `app` as an example to explain each field. For information on other types, please refer to the corresponding configuration guide.
- [Recommend Configuration Guide](recommend.md)
- Accepted Value: `app`, `middleware`

:::info NOTE
`recommend` apps will not be listed in the Olares Market, but you can install recommendation algorithms for Wise by uploading a custom Chart.
:::
Olares currently supports 2 types of applications, each requiring different fields. This document uses `app` as an example to explain each field.

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the previous versions, recommend was an accepted type. It may be helpful to explicitly mention that recommend has been removed to avoid confusion for developers familiar with the old spec.

:::info
The recommend type is no longer included in the current OlaresManifest specification. Use app or middleware according to your application type.
:::

## olaresManifest.version

Expand All @@ -140,10 +144,14 @@ olaresManifest.version: "3.0.122"
## apiVersion
- Type: `string`
- Optional
- Accepted Value: `v1`,`v2`
- Accepted Value: `v1`, `v3`
- Default: `v1`

For shared applications, use version `v2`, which supports multiple subcharts in a single OAC. For other applications, use `v1`.
For shared applications, use version `v3`, which will be installed in the `<appname>-shared` namespace. For other applications, use `v1`.

:::info NOTE
`apiVersion: 'v2'` is used for shared applications on Olares OS version 1.12.5 and earlier. Support for this version will be gradually discontinued after the release of 1.12.6. Please migrate your shared applications to `v3` as soon as possible.
:::
Comment thread
TShentu marked this conversation as resolved.
Outdated

## Metadata

Expand Down Expand Up @@ -438,6 +446,21 @@ Whether the app requires read and write permission to the `Cache` folder. If `.V

Whether the app requires read and write permission to the `Data` folder. If `.Values.userspace.appData` is used in the deployment YAML, then `appData` must be set to `true`.

### appCommon

- Type: `boolean`
- Optional

Whether the app requires read and write permission to the `App Common` folder (cross-node, cross-app shared files, such as models). Use `{{ .Values.userspace.appCommon }}` in the deployment YAML to get the App Common directory path.

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whether the app requires read and write permission to the App Common folder. When set to true, the app can access files shared across multiple apps or nodes, such as AI models. Use {{ .Values.userspace.appCommon }} in the deployment YAML to get the App Common directory path.



### externalData

- Type: `boolean`
- Optional

Whether the app requires read and write permission to the `External` directory, typically used for accessing mounted NAS or other external disk data. In version 0.11.0, applications have External access enabled by default. Starting from version 0.12.0, you need to explicitly declare this field.

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This field includes a breaking behavior change from 0.11.0 to 0.12.0. I suggest highlighting it with a warning block directly under the field.

Whether the app requires read and write permission to the External directory, typically used for accessing mounted NAS or other external disk data.

:::warning
Starting from Manifest 0.12.0, external access is no longer enabled by default. If your app needs access to mounted NAS or external disks, you must explicitly set externalData: true. If omitted, permission will be denied.
:::


### userData

- Type: `list<string>`
Expand Down Expand Up @@ -604,6 +627,47 @@ When set to `true`, only the admin can install this app.

When set to `true`, Olares forces the application to run under user ID `1000` (as a non-root user).

### accelerator
- Type: `map`
- Optional

Declares GPU resources required by the application. For apps that need GPU, use `spec.accelerator` to declare resources instead of `spec.requiredMemory` or similar fields.

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we better clarify this field？

Declares GPU or hardware accelerator resources required by the application. Use this field for accelerator-aware apps, such as LLMs, image generation, video processing, or AI model serving.

:::info NOTE
When accelerator is used, all related resource requirements (CPU, memory, disk, and GPU memory) must be declared inside this block, instead of relying on the root-level spec.requiredMemory or spec.requiredCpu fields.
:::

Supported Modes:

  • nvidia, nvidia-gb10, apple-m, strix-halo: For specific GPU/NPU hardware.
  • cpu: Used as a fallback or to explicitly force CPU-only computation in accelerator-aware applications.


:::info Example
```yaml
spec:
accelerator:
mode: nvidia # Supported modes: nvidia, nvidia-gb10, apple-m, strix-halo, cpu
limitedCpu: 7000m
requiredCpu: 150m
requiredDisk: 50Mi
limitedDisk: 500Gi
limitedMemory: 40Gi
requiredMemory: 5Gi
requiredGPUMemory: 1Gi
limitedGPUMemory: 24Gi
```
:::

## workloadReplicas
- Type: `map`
- Optional

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This field is marked as optional, but the description says that starting from 0.12.0, apps must add this variable to declare replica counts for all workloads. This may look contradictory to developers.

Could we clarify whether this field is required for Manifest 0.12.0 apps?
If it is strictly required for 0.12.0, it would be better described as:

  • Required (for Manifest 0.12.0 and later) / Optional (for earlier versions)


Declares the replica count for each workload in the chart. Starting from 0.12.0, apps must add this variable in `OlaresManifest.yaml` to declare replica counts for all workloads.

:::info Example
```yaml
workloadReplicas:
affine: 1
```
:::
The corresponding `values.yaml` must also include this value for backward compatibility:
```yaml
workloads:
affine:
replicaCount: 1
```

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current example splits OlaresManifest.yaml and values.yaml into separate blocks, which makes the mapping relationship a bit implicit. How about explicitly stating the naming rule and combining the code blocks so developers can compare them at a glance.

For example:

The workload name under workloadReplicas must match the corresponding workload name under workloads in values.yaml. This inclusion is required for backward compatibility.

workloadReplicas:
  affine: 1
workloads:
  affine:
    replicaCount: 1


## Middleware
- Type: `map`
- Optional
Expand Down Expand Up @@ -964,6 +1028,38 @@ allowedOutboundPorts:

This application supports deploying multiple independent instances within the same Olares cluster. This setting does not apply to paid applications or clients of shared applications.

### templateOnly
- Type: `boolean`
- Default: `false`
- Optional

When set to `true`, this application is marked as a template app. The app cannot be installed directly. An instance must be created before installation. If this option is enabled, `allowMultipleInstall` must also be set to `true`.

@Meow33 Meow33 Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about adding the reason to help developers understand why these two fields are coupled?

When set to true, this application is marked as a template and cannot be installed directly. An instance must be created first. Because a template app is designed to spawn multiple instances, allowMultipleInstall must also be set to true.


### LLMGatewaySupported
- Type: `boolean`
- Default: `false`
- Optional

When set to `true`, the application supports LLM Gateway calls. Mainly used for LLM services.

### overlayGateway
- Type: `map`
- Optional

Declares the app's support for L2 overlay LAN discovery. When enabled, other apps can access this app via IP address in the LAN.
Comment thread
TShentu marked this conversation as resolved.
Outdated
:::info Example
```yaml
overlayGateway:
enable: true # Enable L2 overlay LAN discovery, default false
entrances:
- port: 8096 # Overlay listening port
title: Jellyfin # Overlay entrance name
workload: jellyfin # Workload name for OAC validation
description: "Access Jellyfin using IP address in LAN"
protocol: tcp # Supported protocols: tcp/udp; defaults to both tcp and udp if omitted
```
:::

## Envs

Declare the environment variables required for your application to run here. You can allow users to manually enter these values or reference existing system environment variables directly.
Expand Down
90 changes: 1 addition & 89 deletions docs/use-cases/hermes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ You can restart the gateway manually using one of the following methods:
This is the fastest method. Open the Hermes CLI from the Launchpad, and then run the following command:

```bash
hermes restart-gateway
touch /opt/data/.gateway-restart-requested
```
- **Use the Hermes Dashboard**

Expand All @@ -240,94 +240,6 @@ After you complete the basic setup, explore the official resources to expand you
The Hermes CLI in the Olares environment does not support `sudo` commands. Ignore any steps in the official documentation that require `sudo` privileges.
:::

## Install Olares Skills

Hermes Agent supports installing Olares skills to extend its capabilities. These skills provide integration with Olares applications such as Files, Settings, and Dashboard.

To install Olares skills:

1. Open the Hermes CLI from the Launchpad.
2. Run the following command to install each skill:

```bash
hermes skills install clawhub/olares-shared --yes
```

3. Repeat the command for each of the following skills:
- `clawhub/olares-market`
- `clawhub/olares-dashboard`
- `clawhub/olares-settings`
- `clawhub/olares-files`

4. After installation, the skills can be used just like OpenClaw skills.

## Call Hermes Agent via OpenAI-compatible API

Hermes Agent supports being called by other applications through an OpenAI-compatible API, allowing you to integrate it with tools like OpenWebUI.

### Step 1: Enable the Gateway API

1. Open **Settings** > **Applications** > **Hermes Agent**.
2. In the environment variables section, set **API_SERVER_ENABLED** to `true`.
3. Set an **API_SERVER_KEY** value:
- The key must be at least 8 characters long.
- Allowed characters: letters, numbers, and `-_.`
- Avoid placeholder values like `your_api_key`.

![Enable Gateway API](/images/manual/use-cases/hermes-api-settings.png#bordered)

4. Wait for the application to restart.

### Step 2: Find the Gateway API URL

1. Go back to **Settings** > **Applications** > **Hermes Agent**.
2. Find the **Hermes Gateway API** URL and copy it. For example:

```
https://baf3d7172.olarestest003.olares.com
```

### Step 3: Verify the API is running

Open your browser and navigate to:

```
https://<your-gateway-url>/health
```

If enabled successfully, you will see a response confirming the API is running.

### Step 4: Connect from another application

1. Open the application you want to connect (for example, OpenWebUI).
2. Navigate to the admin panel and select **Connection** or **Models**.
3. Add a new OpenAI-compatible model entry with the following settings:
- **Base URL**: Your Hermes Gateway API URL + `/v1`
- For example: `https://baf3d7172.olarestest003.olares.com/v1`
- **Auth**: Select **Bearer** and enter the `API_SERVER_KEY` you set in Step 1.
4. Click the refresh button next to the toggle to check the connection.

5. Once connected, the Hermes Agent model will appear in your application, and you can start chatting with it.

![Connect OpenWebUI](/images/manual/use-cases/hermes-openwebui-connection.png#bordered)

## FAQ: Gateway API fails to start

**Symptom**
- Gateway API access shows "Unable to connect".
- Logs display: `[Api_Server] Refusing to start: API_SERVER_KEY is set to a placeholder value`

**Cause**

The API key does not meet Hermes security requirements.

**Solution**

Reset the API key in **Settings** > **Applications** > **Hermes Agent** with a value that:
- Is at least 8 characters long.
- Contains only letters, numbers, and `-_.`
- Is not a common placeholder value like `your_api_key`.

## Learn more

- [How do I create a server in Discord](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)
Expand Down
Loading