App Store

The App Store is a browser for Helm charts. Instead of a small set of hand-maintained templates, it connects to public chart repositories — including ArtifactHub's catalog of thousands of charts — and installs them into your cluster as managed Helm releases. Pick a chart, review its values, and install it; CasOS runs Helm on the backend and tracks the result as a release you can later upgrade, roll back, or uninstall.

Choosing a source

A sidebar on the left lists the chart sources you can browse. CasOS ships with several presets:

Source	What it is
ArtifactHub	The artifacthub.io index — 8,000+ charts aggregated from across the ecosystem.
Bitnami	Bitnami's ~200 curated, production-hardened charts.
Rancher	The Rancher chart repository.
ingress-nginx	The official ingress-nginx chart repository.

Click a source to browse its charts. ArtifactHub is searched live across every repository it indexes; the other presets load the full chart list from a single repository's index.

Searching and browsing

Each chart appears as a card showing its icon, name, version, and a short description. Use the search box at the top to filter:

• On ArtifactHub, the search term is sent to the ArtifactHub API and matched across all indexed charts, with results paged in as you scroll.
• On a single repository, the search filters the already-loaded chart list by name and description locally.

Click Refresh to reload the current source.

Adding your own repository

To install from a private or third-party repository that isn't in the presets, click Add Repo in the sidebar and enter a name and the repository's URL (for example https://charts.example.com). It's saved under My Repos in the sidebar and can be browsed like any preset. Remove a custom repository with the delete icon next to its name.

OCI-based repositories

Charts are increasingly published to OCI registries — a container registry such as Docker Hub or GitHub Container Registry — instead of a classic index.yaml-based repository. To add one, use its oci:// URL as the repository URL, for example oci://registry-1.docker.io/casbin/casdoor-helm-charts. CasOS detects the oci:// scheme and pulls the chart straight from the registry rather than fetching an index file.

An OCI reference addresses a single chart rather than a whole catalog, so the source lists just that one chart; install it exactly like any other. When you leave the install Version blank, CasOS lists the registry's tags and resolves to the newest one by semantic version — so a registry that also carries older releases or non-semver tags still installs the latest real release rather than whatever tag happens to sort first. You can also pin a version directly in the URL: a :tag suffix (oci://registry-1.docker.io/casbin/casdoor-helm-charts:1.2.3) selects that tag, and a @sha256:… digest pins an exact, immutable image — which is why a digest reference can't be combined with a separate Version. OCI pulls use the same proxy-aware Helm client as everything else, so a configured socks5Proxy applies here too.

Installing a chart

Click Install on a chart card to open the install dialog. Fill in:

• Release name — a name for this installation, unique within the namespace. It must be lowercase and may contain letters, numbers, and hyphens. It defaults to the chart name.
• Namespace — the namespace to install into. CasOS loads the available namespaces and defaults to default.
• Version — the chart version to install. Leave it blank to use the latest.
• Values (YAML) — the chart's configuration. CasOS fetches the chart's default values.yaml and shows it in an editable text area, so you can review every setting and override just the ones you need before installing.

Click Install. The dialog switches to a live console that streams the Helm install log line by line as the backend works, so you can watch the release come up instead of waiting on a spinner. When the install succeeds, the final line turns green and a Done button appears — click it to close the dialog and find the application on the Helm Releases page, where you can upgrade it, view its revision history, roll it back, or uninstall it. If the install fails, the error is shown inline in red so you can read exactly what Helm reported.

CasOS considers the install finished once Helm has created the release's Kubernetes objects — it does not block waiting for every Pod to become ready. A chart that pulls large images or waits on storage can still be settling after the dialog reports success; watch the release's status on Helm Releases, or the individual objects on their own pages, to see when everything is actually running.

Each install runs under a time limit on the backend, so a release that never converges is reported as a failure instead of streaming forever, and the dialog only shows Done when the backend has actually signaled completion — if the connection drops mid-install the log ends with an error rather than falsely reporting success.

When an install does fail, CasOS doesn't just surface Helm's own error. It inspects the target namespace for the objects the release created and appends a diagnostic report to the message: the state of the Deployments, ReplicaSets, Services, and Pods (replica counts, pod phases, restart counts, container states and termination reasons) together with the most recent related Kubernetes events. A chart that fails because an image can't be pulled or a Pod is crash-looping usually says so directly in the log, so you can tell what went wrong without switching to kubectl.

Aborting an install

While an install is in progress the dialog stays open — you can't dismiss it by clicking outside — and shows an Abort button next to the log. Click Abort to cancel: CasOS stops the backend operation instead of leaving it running after you've walked away. Because Kubernetes objects are created as the install proceeds, aborting part-way can leave a partially created release behind, and CasOS warns you when it does. If you see that warning, uninstall the release from Helm Releases to clean up whatever was created before trying again.

tip

The values editor is pre-filled with the chart's real defaults, not a blank box. The safest way to customize an install is to change only the keys you care about — image tags, resource limits, ingress hostnames — and leave the rest as the chart author intended.

If the chart's default values can't be loaded — the repository is unreachable, or the chart archive is malformed — the install dialog shows the error inline instead of presenting an empty editor, so you know the values you're about to install with aren't the real defaults.

Fetching charts through a proxy

CasOS downloads repository indexes and chart archives with a Helm-compatible HTTP client that honors the optional outbound proxy. If you've set socks5Proxy in the configuration, chart browsing and installs route through it automatically — the same way the platform reaches container registries. This is what lets the App Store reach public chart repositories from clusters whose egress is restricted to a proxy.

The client also identifies itself with a standard Helm User-Agent, so repositories that reject or throttle generic HTTP clients serve CasOS the same responses they'd give the helm CLI.

Troubleshooting

A chart you expect isn't listed, or install fails with "chart not found." Some repositories publish index files that CasOS's parser previously couldn't read fully, so charts appeared to be missing. CasOS now parses repository indexes the same way Helm itself does, so charts that used to be skipped show up and install normally. Click Refresh on the source to re-fetch its index.

Browsing a repository shows fewer charts than the repository advertises. A repository's index.yaml can contain legacy or malformed entries with missing metadata. Rather than failing the whole listing, CasOS skips only the unreadable entries and shows the rest, so one bad entry no longer blocks an entire source from loading.

A repository won't load at all. Confirm the URL points at a Helm repository root (the directory containing index.yaml, e.g. https://charts.example.com, not a link to a specific chart). If the repository is only reachable through your network's proxy, make sure socks5Proxy is configured as described above.

A chart refuses to install, citing an incompatible Kubernetes version. Many charts gate their templates on the cluster's version — declaring a kubeVersion range, or branching on .Capabilities.KubeVersion to pick the right API for an object. CasOS reports its real Kubernetes version to Helm for these checks, but first normalizes it the same way it does for worker-node binaries: the +build metadata is dropped and distribution suffixes like -k3s1 or -eks are stripped back to the plain upstream release (so v1.36.1-k3s1 becomes v1.36.1), while genuine upstream pre-releases such as -alpha, -beta, and -rc are preserved. This keeps a chart's version constraint comparing against a clean semantic version rather than a distribution tag it doesn't recognize, so charts render for the version you're actually running. If discovery of the cluster's version or API set fails entirely, CasOS falls back to Helm's built-in defaults and notes it in the install log rather than aborting the install.

A chart fails to load and the error is hard to place. Loading a chart involves several steps that can each fail on their own — fetching a repository's index.yaml, resolving the entry to a download URL, pulling an OCI reference, downloading the chart archive, and parsing it. CasOS labels the failure with exactly which of these steps broke and for which chart, repository, and version, so an error reads as "download chart archive failed" for a specific URL rather than a bare "download chart." That context usually tells you whether the problem is the repository, the network, or the chart itself without any further digging.

A failing repository URL contains a password or token. Repository and OCI URLs sometimes carry credentials inline — as user:pass@host userinfo or as sensitive query parameters like token, secret, or access_key. Before CasOS puts a URL into an error message it redacts those secrets, replacing embedded userinfo and known credential parameters with REDACTED, so a failed install doesn't leak your registry password into the install log or the UI. The redaction is applied to the URL CasOS reports and to any copy of it that a lower-level Helm error echoes back, and it holds even when the URL is malformed enough that it can't be parsed cleanly.

Managing installed applications

Everything you install through the App Store is a Helm release. Manage the full lifecycle — upgrades, rollbacks, history, and uninstalls — on the Helm Releases page, reachable from the My Releases → button in the App Store header. The individual Kubernetes objects a chart creates (Deployments, Services, and so on) also show up on their respective pages, but managing the release as a unit keeps related resources together.