CasOS

A cloud operating system built on Kubernetes

Website: casos.net · Live demo: demo.casos.net

CasOS is a cloud operating system built on Kubernetes. It embeds the Kubernetes API server, controller manager and scheduler, so you do not need an existing cluster, a control plane, or a single line of YAML. Download one file, run it, and you have a working cluster with a web UI and an app store.

Quick start

Three steps and about five minutes. No prior Kubernetes knowledge needed.

1. Install

Linux / macOS

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

Windows (PowerShell)

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

The installer downloads the latest release, unpacks the executable and adds it to your user PATH. On Windows the current PowerShell session can use it right away; on Linux and macOS, open a new shell (or run the source command the installer prints). Prefer not to run a script? Download the archive for your system from the releases page and unpack it — it holds a single executable, nothing else.

2. Start it

casos

On Windows you can also just double-click casos.exe — it starts the server and opens your browser for you.

3. Open the UI

Go to http://localhost:20080 and you are signed in as admin.

⚠️ Change the password first. A fresh install has the built-in account admin / 123 and signs you in automatically, which means anyone who can reach the port is an administrator. Open the account menu in the top-right corner → My Account → set a real password. The automatic sign-in stops the moment the password is no longer 123.

4. Install your first app

Open the App Store and install anything you like. That is the whole workflow — CasOS pulls the chart, schedules it, and shows you the running app.

The dashboard has a first-run checklist that tracks these steps and disappears once all four are done. Every step is read from the server, so it stays accurate after a refresh or a sign-in from another browser.

What CasOS sets up by itself

You do not have to add nodes, install a CNI or configure storage. On startup CasOS:

Turns the machine it runs on into a worker node. On Linux that is the host itself. On Windows it uses your WSL distribution — and installs WSL for you when there is none. Watch the progress on the Machines page.
Starts an ingress controller and a service load balancer, so apps get a reachable address.
Stores everything in SQLite under the data directory — no database to set up.

Host	Worker node
Linux	The host itself. CasOS must run as root, or as a user with passwordless `sudo`.
Windows	The local WSL2 distribution, installed automatically when missing. A brand-new WSL install can need one Windows restart.
macOS	Not possible — a kubelet needs a Linux kernel. Add a Linux machine over SSH on the Machines page, or run CasOS inside a Linux VM.

If something goes wrong

Symptom	Fix
The page does not load	Another program may hold port 20080. Change `httpport` in `conf/app.conf`.
The cluster has no node	Look for `automatic node setup` in the CasOS log. Fix what it reports, or add a machine by hand on the Machines page.
macOS refuses to run the binary	The release is not notarized. A browser download is quarantined: `xattr -d com.apple.quarantine ./casos`. The installer above is unaffected.
Lost the admin password	There is no recovery. Delete the row from the `user` table in `data/casos.db` and restart to get the default account back.
Reporting a bug	Include the output of `casos --version`. A released binary prints its tag, commit and build date; a self-built one reports `dev`.

Upgrade and uninstall

Rerun the install command to upgrade. To uninstall:

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

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/casosorg/casos/master/scripts/install.ps1))) -Uninstall

Your data directory is not deleted. It holds the SQLite databases, the control-plane TLS material and the key that decrypts stored SSH credentials, so removing it is a separate, deliberate step — the uninstaller prints the path and the exact command for it.

Installer options — pin a version, or choose the install directory

Both installers read the same settings:

Variable	Default	Purpose
`CASOS_VERSION`	`latest`	Release tag, such as `v1.32.0`
`INSTALL_DIR`	`$HOME/.local/bin`, `%LOCALAPPDATA%\CasOS\bin`	Directory to install into
`CASOS_REPOSITORY`	`casosorg/casos`	Release repository to pull from

On Linux and macOS, pass them to bash, not to curl:

curl -fsSL https://raw.githubusercontent.com/casosorg/casos/master/scripts/install.sh | CASOS_VERSION=v1.32.0 INSTALL_DIR="$HOME/.local/bin" bash

PowerShell has no equivalent prefix syntax. iex runs the installer inside the current session, so set the variables as $env: entries on their own lines first:

$env:CASOS_VERSION = 'v1.32.0'
irm https://raw.githubusercontent.com/casosorg/casos/master/scripts/install.ps1 | iex

Those entries outlive the install and would pin any later run in the same window, so clear the ones you no longer want:

Remove-Item Env:\CASOS_VERSION

Releases are x86_64 only. An Apple Silicon Mac and a Windows on ARM machine both get that build and run it under emulation; an arm64 Linux host has to build from source.

Features

Embedded Kubernetes — API server, controller manager and scheduler in one binary. No external cluster and no kubeadm.
Zero-configuration worker node — the machine you start CasOS on joins the cluster by itself; more machines are added over SSH from the Machines page.
App Store — install and manage Helm releases from the UI.
Full resource management — Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, Pods, Services, Ingresses, ConfigMaps, Secrets, PVCs, StorageClasses, HPAs, quotas, namespaces and RBAC.
Observability — dashboard, cluster topology, monitoring, log search, and pod terminals in the browser.
Security — Casbin-backed admission and authorization policies, plus Trivy image scanning.
Sign-in that needs no setup — a built-in admin account out of the box, with optional Casdoor single sign-on.
Multi-language UI (i18n).

Configuration

Most people never need this section: CasOS runs on its defaults, and the setting a fresh install is most likely to touch is the HTTP port.

Settings live in conf/app.conf next to the executable:

httpport      = 20080      ; web UI and REST API
apiserverPort = 20443      ; embedded Kubernetes API server
dataDir       = ./data     ; databases, TLS material, credential key

driverName    = sqlite     ; default; "mysql" is also supported
casdoorEndpoint =          ; blank = built-in admin account
autoEnrollLocalNode = true ; make this machine a worker node on startup

A binary started without conf/app.conf stores its data in the per-user data directory instead: ~/.local/share/casos, ~/Library/Application Support/CasOS, or %LOCALAPPDATA%\CasOS. CasOS logs the directory it resolved as casos data directory: <path> on startup.

Sign-in

casdoorEndpoint decides how you sign in, and nothing else has to be set up:

`casdoorEndpoint`	Sign-in
blank (default)	Built-in `admin` account, stored in the CasOS database
set	Casdoor single sign-on; the built-in account is never created

To use Casdoor, fill in all five Casdoor settings before the first start. Each one also reads an environment variable of the same name, so clientSecret does not have to be written to disk:

casdoorEndpoint=https://your-casdoor-instance clientId=... clientSecret=... casdoorOrganization=... casdoorApplication=... casos

Data directory, MySQL, outbound proxy, manual nodes, upgrade notices

Data directory. SQLite stores CasOS business data in data/casos.db and Kubernetes state in data/kine/state.db. The directory also holds the control-plane TLS material and the key that encrypts stored SSH private keys, so an installation that loses track of it can no longer decrypt existing machine credentials.

Breaking change: dataDir used to default to /var/lib/casos. It now defaults to ./data, which is resolved against the working directory of the CasOS process — so starting CasOS from a different directory points it at a different, and most likely empty, data directory. Set dataDir to an absolute path such as /var/lib/casos for any system installation, make sure the service user can write to it, and move an existing /var/lib/casos to the new location before restarting.

MySQL. Set driverName=mysql, configure dataSourceName and dbName, and optionally set a complete kineEndpoint. Switching an existing installation from MySQL to SQLite starts with empty SQLite databases; existing MySQL data is not imported automatically.

Outbound proxy. socks5Proxy accepts host:port, socks5:// and socks5h:// addresses. When it is set, CasOS fails requests that cannot use the configured proxy instead of silently falling back to direct access; destinations matched by the CasOS process NO_PROXY continue to use direct access. When it is blank, CasOS follows HTTP_PROXY, HTTPS_PROXY and NO_PROXY, and uses direct access when no environment proxy is configured.

Upgrade notice: the previous example default of 127.0.0.1:10808 has been removed. Set socks5Proxy explicitly before upgrading if that local proxy is a required control-plane dependency.

Upgrade notice: earlier releases shipped conf/app.conf pointing at a shared public Casdoor demo application, credentials included. Those values are now blank. An installation that relied on them must configure its own Casdoor application, or clear the five settings to switch to the built-in account.

Manual worker nodes. Set autoEnrollLocalNode = false to manage nodes yourself. worker-setup.md walks through building a WSL2 worker by hand, and machine-setup.md covers preparing a machine for SSH enrollment.

Development

Prerequisites: Go 1.26+, Node.js 20+ and Yarn 1.x. All frontend commands run inside web/, and yarn is the package manager — the lock file is web/yarn.lock.

git clone https://github.com/casosorg/casos.git
cd casos

Backend — serves the API and the UI on port 20080:

go run main.go

Frontend — dev server on port 8002, proxying the API to localhost:20080 (override with BACKEND_URL):

cd web
yarn install    # first time only
yarn start

Tests and lint:

cd web
yarn lint          # ESLint with --fix
yarn lint:ci       # the same check without --fix, as CI runs it
yarn test:unit     # unit tests
yarn ui:test       # Playwright end-to-end suite; starts its own backend and dev server

See web/FRONTEND.md for the component contract and the selector hooks the Playwright suite depends on.

Building a release binary

The backend reads web/build/ from disk, so during development a frontend rebuild alone is enough. To produce the single self-contained file that releases ship, build the frontend first and compile with -tags embed:

cd web && yarn build && cd ..
CGO_ENABLED=0 go build -trimpath -tags embed -o casos .

Every release publishes that binary for Linux, macOS and Windows on x86_64, as a .tar.gz (Linux, macOS) or .zip (Windows) holding the executable alone.

Project structure

casos/
├── main.go          # Entry point
├── conf/app.conf    # Backend configuration
├── controllers/     # HTTP controllers (Beego routing)
├── object/          # Business logic and data models
├── routers/         # Route configuration and filters
├── server/          # Embedded Kubernetes control plane
├── deploy/          # Node deployment and the local-node bootstrap
├── store/           # Helm and App Store logic
├── proxy/           # kube-proxy related logic
├── i18n/            # Backend translations
└── web/             # React frontend
    └── src/
        ├── pages/       # One file per screen
        ├── components/  # shadcn/ui components and shared widgets
        ├── backend/     # API client helpers
        ├── hooks/ lib/ locales/
        └── routes.jsx

Layer	Technology
Backend	Go 1.26+, Beego, embedded Kubernetes, SQLite via kine (MySQL optional)
Frontend	React 18, shadcn/ui (Radix + Tailwind v4), Vite, recharts, i18next
Auth	Built-in account, or Casdoor (OAuth2 / OIDC)

License

Apache 2.0

Navigation Menu

Uh oh!

Repository files navigation

CasOS

Quick start

1. Install

2. Start it

3. Open the UI

4. Install your first app

What CasOS sets up by itself

If something goes wrong

Upgrade and uninstall

Features

Configuration

Sign-in

Development

Building a release binary

Project structure

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
casdoor		casdoor
conf		conf
controllers		controllers
deploy		deploy
i18n		i18n
object		object
proxy		proxy
routers		routers
scripts		scripts
server		server
store		store
util		util
web		web
wsl		wsl
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.releaserc.json		.releaserc.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
machine-setup.md		machine-setup.md
main.go		main.go
shutdown.go		shutdown.go
worker-setup.md		worker-setup.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

CasOS

Quick start

1. Install

2. Start it

3. Open the UI

4. Install your first app

What CasOS sets up by itself

If something goes wrong

Upgrade and uninstall

Features

Configuration

Sign-in

Development

Building a release binary

Project structure

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages