CasOS: a one-file Kubernetes control plane with an app store

What CasOS adds beyond a plain Kubernetes node

CasOS solves the setup gap between downloading a generic Kubernetes distribution and operating a usable application environment. Its intended user is someone who wants a cluster, a web interface, and an application catalog without first configuring an API server, controller manager, scheduler, ingress controller, load balancer, or persistent store. The project is written primarily in Go and distributes its control-plane components as one executable. Once that executable starts, the current Linux host becomes a worker. On Windows, the worker runs through WSL, which CasOS can install when absent.

The project is aimed at more than application hosting. Its documented workflows include private Ollama and Open WebUI installation, NVIDIA GPU model selection, browser and SSH development environments, Git-based builds, and MCP access for tools including Claude Code, Cursor, and Codex. This makes CasOS closer to an opinionated management layer around Kubernetes than a command-only cluster distribution. The benefit is a shorter path to those functions. The cost is that users accept CasOS's UI, app catalog, initial account model, SQLite data layout, and its interpretation of supported deployment workflows.

The README positions k3s and minikube as tools that primarily give users a cluster. CasOS instead combines the cluster with UI and application management. It compares Coolify and CasaOS as Docker-oriented one-click app environments, while CasOS schedules workloads on Kubernetes and says that machines can be added over SSH. Those are real architectural differences, although the README does not document every setting required for multi-machine operation.

The startup path from one binary to a worker cluster

The binary embeds the Kubernetes API server, controller manager, and scheduler. This is the central mechanism behind the one-file claim. During startup, CasOS turns its host into a worker, starts an ingress controller and service load balancer, and stores cluster state in SQLite under its data directory. The ingress and load-balancer components explain how applications receive a reachable address, while SQLite removes the need to provision an external database.

Linux, Windows, and macOS do not have equivalent startup paths. A Linux deployment requires root or a user with passwordless `sudo`. Windows uses a local WSL2 distribution and may require a Windows restart after a new WSL installation. macOS cannot become the initial worker because a kubelet requires a Linux kernel. The README directs macOS users to add a Linux machine over SSH or run CasOS within a Linux virtual machine.

This startup design also has an operational boundary. A fresh install signs the user into a built-in `admin` account with password `123`, and anyone who can reach the port has administrative access until that password changes. Automatic sign-in stops when the password is no longer `123`. This is documented directly by the project, so changing the account password before exposing the UI beyond a trusted local context is the first concrete security check. The README does not describe the default TLS certificate arrangement, authentication provider configuration, or an application-level rollback procedure.

Installing CasOS and launching the interface

The documented Linux and macOS installation uses a remote shell script. It downloads the current release, unpacks the executable, and adds `casos` to the user `PATH`. The README notes that a new Linux or macOS shell may be required, or the user can run the `source` command printed by the installer.

curl -fsSL https://raw.githubusercontent.com/casosorg/casos/master/scripts/install.sh | bash

Windows users are given a PowerShell equivalent. The current PowerShell session can use the installed command immediately after the installer finishes.

irm https://raw.githubusercontent.com/casosorg/casos/master/scripts/install.ps1 | iex

After installation, start the server with the executable name shown in the README.

casos

On Windows, the README also permits double-clicking `casos.exe`, which starts the server and opens the browser. CasOS turns the host into a worker and reports progress on the Machines page, so that page is the first place to look after startup. Open `http://localhost:20080`; the fresh install signs in as `admin` with password `123`. Change that password through the account menu under `My Account` before proceeding.

A first App Store installation and Git deployment path

CasOS provides a short first application workflow through its App Store. The interface offers items from the sealos template catalogue and Helm charts. Selecting an item starts the documented sequence: CasOS pulls the chart, Kubernetes schedules it, and the UI presents the running app. The first-run checklist tracks four server-derived steps and remains synchronized after refresh or sign-in, according to the README.

For code deployment, the documented starting point is a public Git repository. CasOS builds it inside the cluster from a Dockerfile. If the repository has no Dockerfile, the README says it can recognize Node.js, Python, Go, and static projects. CasOS deploys the result with an address and does not require a separately configured registry. A rebuild is documented as shipping the latest commit. This is a useful convenience, but users should inspect build behavior and public-repository assumptions before placing code in that workflow.

CasOS also accepts `docker-compose.yml`. According to the README, each project runs in its own namespace, services resolve one another by name, published ports receive addresses, `${VAR}` values come from a `.env` box, and GPU reservations can use an NVIDIA card. A preview displays anything that cannot be carried over. This compatibility layer is useful for existing self-hosted applications, but it is not equivalent to running a general Compose implementation unchanged. The project specifically documents previewing unsupported constructs before deployment.

Private AI, DevBoxes, and the MCP control boundary

CasOS has a documented focus on AI workloads that remain on the user's hardware. Its App Store workflow can install Ollama and Open WebUI, select the largest listed model that fits available GPU memory, and expose the model through an OpenAI-compatible `/v1` API. The README says that apps and editors on the local network can use that endpoint and that the service can spread across machines running the model. Model examples include Qwen 3, DeepSeek R1, Gemma 3, and `gpt-oss`.

DevBoxes serve a different purpose. They provide VS Code in a browser or desktop VS Code over SSH. The documented starting sources are an empty environment, a Git URL, or a repository on the user's machine, with support for arbitrary images and GPU jobs. This is attractive for short-lived development environments, but the README does not define persistence limits, GPU scheduling policy, or cleanup behavior for DevBoxes themselves. It does state that MCP sandboxes are deleted when their allotted time expires.

The MCP server exposes application deployment, log access, rollback, and sandbox commands to agents. The README provides this client registration command:

claude mcp add --transport http --scope user casos http://localhost:20080/mcp --header "Authorization: Bearer <token>"

The token is created from the account menu under `AI Agents`. Since MCP can deploy applications, inspect logs, perform rollbacks, and open executable sandboxes, its authorization scope deserves careful review. The README documents the command and token source, but it does not describe granular MCP permissions or the exact rollback semantics.

Maintenance, licensing, and CasOS versus k3s

The repository is not archived, and its last push was on 2026-09-29. Releases `v1.57.0`, `v1.56.1`, and `v1.56.0` were published on 2026-09-28. This indicates recent development activity at those dates, but the README does not define a long-term support window, upgrade compatibility policy, or migration path between releases.

The repository uses the Apache-2.0 license. That permits use and modification under the license's stated conditions, while redistribution also requires attention to its notices and license text. This is a repository fact, not legal advice. The top-level `LICENSE` file is the relevant project file for an adoption review.

The clearest alternative named by the README is k3s. k3s supplies a Kubernetes cluster and leaves operators closer to standard cluster administration. CasOS embeds control-plane components in its own executable and adds a web UI, app store, guided Git and Compose workflows, GPU-oriented AI functions, DevBoxes, and MCP access. This convenience layer is the core trade-off. Choose k3s when direct control and conventional Kubernetes administration matter more. Choose CasOS when the managed UI and opinionated deployment paths are central to the intended workflow.

Editorial conclusion

CasOS is appropriate for developers who want a guided local or self-hosted Kubernetes environment, GPU-backed AI services, and browser-based deployment rather than a bare cluster tool. It is unsuitable for macOS hosts that expect the startup machine to become a worker, and it is a poor fit for operators that require a documented rollback procedure for every deployment before first use. Evaluate the current release by first confirming the host platform, reviewing the initial admin credential and port exposure, then installing one noncritical application and inspecting how its workload, address, logs, and Git rebuilds appear in the interface.

Frequently asked questions

Official sources

1. casosorg/casos on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases