CasaOS: the install is one line, and the release binary is upx-packed

Installation is one remote script piped into sudo bash

The whole install, on a system freshly installed from the supported list, is one of these:

wget -qO- https://get.casaos.io | sudo bash

curl -fsSL https://get.casaos.io | sudo bash

Two fetches, one host, and root. Nothing in either command pins a version, checks a checksum, or names a file you could inspect first, which is the ordinary trade in a one-liner installer and worth naming rather than pretending otherwise. The thing to notice is that get.casaos.io is not just the installer. The same host serves the updater at https://get.casaos.io/update, so the domain that installs your system is also the domain that changes it later. That is a small trust surface, and a small blast radius if it is ever wrong.

The project does not hide behind the one-liner, at least. Uninstalling is a command on the box rather than another download, casaos-uninstall for v0.3.3 or newer, with a separate script at https://get.icewhale.io/casaos-uninstall.sh for anything older, and the version is one command too, casaos -v. So the parts you would reach for in a panic are the parts that do not require the network.

An update from the web UI cannot be finished from the web UI

This is the most surprising operational rule in the documentation, and it is stated twice in the update section. CasaOS can be updated from the interface through Settings and Update. Alternatively it can be updated from a terminal session, and here is the constraint: that terminal update must be done either from a secure shell session to the device or from a directly attached terminal and keyboard, and it cannot be done from the terminal via the CasaOS User Interface.

So the browser path and the terminal path are not two ways to do the same thing. The browser path is for starting an update; the terminal path is for carrying it out, and it needs you to be logged in over ssh or sitting at the machine. On a headless box that means ssh. On a box in another room it means a keyboard.

For most people that is a non-issue, since a home server you do not update is worse than the friction. For an unattended deployment it is a real constraint, because the update is then a scheduled ssh session rather than a click, and the updater is the same root-level remote script as the installer:

wget -qO- https://get.casaos.io/update | sudo bash

Worth knowing before you automate anything around it.

Debian 12 is the recommended base, and Alpine, OpenWrt and ArchLinux are untested

The compatibility list separates what the project has tested from what the community has tried, and the wording is precise. Official support covers Debian 12, marked tested and recommended, Ubuntu Server 20.04, marked tested, and Raspberry Pi OS, marked tested. Community support covers Elementary 6.1 and Armbian 22.04, both marked tested, and then three distributions marked not fully tested yet: Alpine, OpenWrt and ArchLinux.

That distinction matters more than the length of the list. A system that manages drives, mounts storage and runs your containers is not a place to be the first tester of a distribution nobody has validated. The README also says the project is fully compatible with Ubuntu, Debian, Raspberry Pi OS and CentOS with one-liner installation, which is a wider claim than the tested list, and those are two different sentences making two different claims.

On hardware the list is short and explicit: amd64 or x86-64, arm64, and armv7. armv7 is the one that surprises people, since it covers 32-bit ARM boards such as older Raspberry Pi hardware, and it is a genuine differentiator against Docker-first alternatives that assume a 64-bit host. The project came out of a pre-installed system for the crowdfunded ZimaBoard, and ZimaBoard, Intel NUC and Raspberry Pi are the three machines the README names as fully supported.

The backend build statically links CGO and then runs upx on the result

The Makefile is short enough to read completely, and its build-backend target is one line that does four things:

export CGO_ENABLED=1;export CGO_LDFLAGS=-static;go build -o ./casa main.go;upx --lzma --best casa

CGO is enabled and the linker flags ask for a static binary, which is what lets one artifact run across the amd64, arm64 and armv7 targets listed in the README. Then the binary is passed to upx with --lzma --best, which compresses and packs the executable.

The packing is the part to have an opinion about. UPX reduces the download size of a self-contained server binary, and it also makes that binary harder to inspect, trivially so, because the original is compressed inside it. It is a well-known source of false positives in scanning tools, so a packed casaos binary arriving from a third-party mirror is exactly the shape of file that gets flagged for reasons that have nothing to do with what it does. If you build it yourself and it trips something, that is a place to look first.

The other half of the build is the part that will bite a contributor. build-ui changes into CasaOS-UI and runs yarn install and yarn build, and CasaOS-UI is not in the repository root listing. There is a .gitmodules file, so the front end arrives as a submodule, and a checkout without it will not build the UI target at all.

The Makefile help target prints call john, and DEVELOPING.md does the real work

The declared targets are build, build-ui, build-backend and help, and the help target is this:

@echo "call john"

It is a joke left in a production build file, and it is worth mentioning for one reason: the Makefile is a build tool, not a developer interface. Four targets, one of which is a punchline, none of which run the server, check types, run a linter or run a test. If you arrive expecting make to give you a workflow, there is nothing there.

The developer documentation lives in files instead. DEVELOPING.md is committed at the root next to CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md and LICENSE, and the Go source is organised into conventional directories, with cmd/, internal/, service/, route/, model/, api/, drivers/, common/, conf/, interfaces/, pkg/ and types/ alongside main.go. The release configuration is a pair of goreleaser files, .goreleaser.yaml and .goreleaser.debug.yaml, which tells you a debug-flavoured artifact is a first-class build output rather than something you improvise.

The Go module declares go 1.21, so that is the floor for anyone building from source, and it depends on the IceWhaleTech shared package CasaOS-Common at v0.4.11-alpha4. That last detail is the one to hold onto: the project's own common library is pinned to a prerelease, so CasaOS and CasaOS-Common are versioned together in practice, even though the dependency looks like any other line in go.mod.

Three generators can produce the SDK, and the package is still 0.0.1

The repository is Go with a TypeScript sibling at the root, package.json describing @icewhale/casaos-openapi as a Casaos Typescript plus Axios SDK. Its version is 0.0.1, it depends on axios, and its types come from a spec at api/casaos/openapi.yaml.

What is unusual is that the manifest defines three different generators for that one spec. There is generate:local using openapi-generator-cli with the typescript-axios generator, a generate:npx doing the same thing through the npx form of the tool, and a generate:ts using the entirely separate openapi-typescript-codegen package. Three tools, one input file, and no indication in the manifest of which is canonical. The client your application ends up importing depends on which one a given developer ran, and the two families of generator produce differently shaped code.

The build script has a quirk worth flagging too. It reads rm -rf dist && tsc && yarn clean, and clean is rm -rf generate. So a build compiles and then deletes the generated client, while the files array publishes a directory called generate. The start script sequences it as generate then build, which means the only way the published layout exists is if someone regenerates after building. For a package still at 0.0.1 that is forgivable. For an SDK other people depend on, it is the kind of thing that produces a broken install in someone else's CI.

Last push 2025-08-06, and the newest tag is still an alpha

The maintenance picture is the deciding factor for a system of this kind, and it deserves stating plainly. The repository is not archived, but the last push was on 2025-08-06. The three most recent releases are v0.4.17-alpha1 from 2025-04-17, v0.4.15 from 2024-12-19 and v0.4.14 from 2024-12-10. So the newest published tag is a prerelease from April 2025, the last code change is from August 2025, and the project has never left the 0.4 line.

The gap is not subtle once you line it up against the dependencies. go.mod pins golang.org/x/crypto at v0.23.0 and golang.org/x/sys at v0.20.0, both of which have had a lot of releases since, and the runtime stack includes a systemd library, a socket.io server, an SMB client, a pure-Go SQLite driver, GORM, Echo and a file-type sniffer. A year of no pushes on a base system means a year of no dependency bumps, which cuts both ways: nothing new is breaking under you, and nothing known has been fixed either.

For a personal dashboard over Docker apps on a machine you can rebuild, that is a reasonable position. For storage holding anything you would miss, verify the state of the project yourself before you rely on it, and keep your own backup outside it. The uninstall path is clean enough that leaving is a real option, which is the only comfort available in this situation.

Editorial conclusion

Adopt CasaOS if you have a spare x86 or ARM machine and want a home dashboard over Docker apps, and you are content to run the officially tested base systems rather than a distribution you prefer. Do not adopt it as a storage system you will not touch again, because the last push was on 2025-08-06 and the newest tag is v0.4.17-alpha1 from 2025-04-17, so the code predates the current ecosystem by a year or more. Before you install, read what the updater will do to your system from a browser session, since the documentation requires updates to be launched over ssh or a local keyboard rather than from the web UI, and note that the installer runs as root from a single host with no checksum in the command.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes