One curl command installs CasaOS on Debian, and on our Debian 13 test box the dashboard was answering on port 80 four minutes later. What the command does to the server is the part most guides skip: it pulls in Docker from the upstream script, pins an old rclone, starts Samba on every interface and creates world-writable data folders under /DATA. None of that is a reason to avoid CasaOS. It is a reason to know what you just installed.
This guide walks through how to install CasaOS on Debian 13 (Trixie) and Debian 12 (Bookworm), create the admin account, install apps from the CasaOS App Store, and then update it, reset the password or uninstall it without losing data. It closes with the security checks we ran on the finished personal cloud. If you are starting from a blank server, run through the Debian 13 post-install checklist first. Every step below was run on Debian 13.7 and Debian 12.15 in September 2026 with CasaOS v0.4.15.
What the CasaOS installer puts on your server
The installer at get.casaos.io is a shell script, and it changes more than the name suggests. This is what it left behind on both test VMs:
| Component | What it does | Where it listens |
|---|---|---|
| Docker Engine + Compose plugin | Installed from get.docker.com when Docker is missing. Every CasaOS app is a Compose project | No host port of its own |
| Docker API override | /etc/systemd/system/docker.service.d/override.conf sets DOCKER_MIN_API_VERSION=1.24 so the older CasaOS client can talk to a current Docker | n/a |
| casaos-gateway | Serves the web UI and proxies the API | TCP 80 on all interfaces |
| casaos, user-service, app-management, local-storage, message-bus | The backend services | 127.0.0.1 on random ports |
| rclone | Pinned to an old release, runs as rclone rcd on a Unix socket | Unix socket only |
| Samba (smbd) | File sharing for the /DATA folders | TCP 139 and 445 on all interfaces |
| udevil + devmon, mergerfs | USB auto-mount and drive pooling | n/a |
If you already run Docker from the Debian repository or from Docker’s apt repo, the script keeps that install as long as the daemon answers and the major version is 20 or newer. Two side effects matter on a box that already runs containers: the script overwrites /etc/systemd/system/docker.service.d/override.conf (the file systemctl edit docker writes, so any customisation there is lost), and it restarts Docker, which restarts every running container. If Docker is installed but stopped, the version check fails and it runs get.docker.com over the top. We tested on clean VMs, so both boxes got Docker 29 from get.docker.com.
Prerequisites
- Debian 13 or Debian 12, amd64 or arm64. The script also accepts armv7, but it installs the current Docker Engine from get.docker.com, and Docker no longer ships packages for 32-bit Raspberry Pi OS, so treat armv7 as unsupported
- At least 400 MB of RAM (the script refuses to run below that). Below 5 GB free on
/it asks whether to continue rather than stopping. Our VMs had 2 vCPU, 4 GB RAM and a 25 GB disk, which is a sensible floor once you add a few apps - A user with sudo rights and outbound internet access
- Ideally port 80 free. On first start the gateway takes port 80, or the first free port in 81-89 and then 8080-8089 if 80 is busy, and writes the choice to
/etc/casaos/gateway.ini. Port 80 was free on our VMs, so both ended up on 80. On a box that already runs a web server, read the port from the install banner
Small hardware works fine. A single board server such as the ZimaBoard 2 is made for this, and our homelab mini PC guide compares it with the usual N150 and Ryzen boxes.
Install CasaOS on Debian 13 / 12
Refresh the package index and make sure curl is present. The Debian cloud images ship without it:
sudo apt update
sudo apt install -y curlThen pipe the official installer into bash. If you prefer to read a script before running it as root, download it with curl -fsSL https://get.casaos.io -o casaos-install.sh first and run it from the file:
curl -fsSL https://get.casaos.io | sudo bashThe run took 4 minutes 1 second on Debian 13 and 4 minutes 9 seconds on Debian 12. Along the way it checks memory and disk, installs the dependencies, pulls Docker, writes the API override and starts the services in order. On both releases it prints six lines like the one below. They are harmless: each setup script looks for a release-specific folder that does not exist, then falls back to the plain debian folder.
/tmp/casaos-installer/tmp.LEaCo0ce0g/build/scripts/setup/script.d/01-setup-gateway.sh: line 18: pushd: debian/trixie: No such file or directoryA successful install ends with every service reported as running and the address of the dashboard:
[ OK ] casaos-app-management.service is running.
[ INFO ] Checking rclone.service...
[ OK ] rclone.service is running.
[ INFO ] Checking casaos.service...
[ OK ] casaos.service is running.
─────────────────────────────────────────────────────
CasaOS v0.4.15 is running at:
─────────────────────────────────────────────────────
- http://192.168.1.50 (eth0)
Open your browser and visit the above address.
─────────────────────────────────────────────────────
Uninstall : casaos-uninstallVerify the CasaOS services
Seven units make up a working install, plus devmon for USB drives. List them:
systemctl list-units 'casaos*' rclone.service [email protected] --no-pager --no-legendAll eight should read loaded active running:
casaos-app-management.service loaded active running CasaOS App Management Service
casaos-gateway.service loaded active running CasaOS Gateway
casaos-local-storage.service loaded active running CasaOS Local Storage Service
casaos-message-bus.service loaded active running CasaOS Message Bus Service
casaos-user-service.service loaded active running CasaOS User Service
casaos.service loaded active running CasaOS Main Service
[email protected] loaded active running devmon Service
rclone.service loaded active running rcloneNow check what is reachable from the network. This list decides where the box can safely live:
sudo ss -tlnp | grep -E 'casaos|smbd'Only the gateway on port 80 and Samba on 139 and 445 face the LAN. Everything else binds to loopback:
LISTEN 0 50 0.0.0.0:139 0.0.0.0:* users:(("smbd",pid=5947,fd=30))
LISTEN 0 4096 127.0.0.1:37667 0.0.0.0:* users:(("casaos-gateway",pid=8458,fd=11))
LISTEN 0 50 0.0.0.0:445 0.0.0.0:* users:(("smbd",pid=5947,fd=29))
LISTEN 0 4096 127.0.0.1:45463 0.0.0.0:* users:(("casaos-local-st",pid=8498,fd=8))
LISTEN 0 4096 127.0.0.1:36473 0.0.0.0:* users:(("casaos-app-mana",pid=8549,fd=8))
LISTEN 0 4096 127.0.0.1:44585 0.0.0.0:* users:(("casaos",pid=8565,fd=12))
LISTEN 0 4096 127.0.0.1:38447 0.0.0.0:* users:(("casaos-message-",pid=8470,fd=7))
LISTEN 0 4096 127.0.0.1:40755 0.0.0.0:* users:(("casaos-user-ser",pid=8483,fd=7))
LISTEN 0 4096 127.0.0.1:34755 0.0.0.0:* users:(("casaos-gateway",pid=8458,fd=7))
LISTEN 0 4096 *:80 *:* users:(("casaos-gateway",pid=8458,fd=8))
LISTEN 0 50 [::]:139 [::]:* users:(("smbd",pid=5947,fd=28))
LISTEN 0 50 [::]:445 [::]:* users:(("smbd",pid=5947,fd=27))Create the CasaOS admin account
Open http://192.168.1.50 (your server’s IP) in a browser. A fresh install has no user yet, so the first screen is the welcome card:
Click Go and pick a username and password. Whoever reaches this page first owns the box, so do it straight after the install rather than leaving an unclaimed CasaOS on the LAN:
After Create you land on the dashboard. CasaOS immediately asks whether it may pull the news feed from blog.casaos.io. Cancel keeps the dashboard from calling out to that site. The widgets on the left show CPU, RAM, the system disk and network traffic:
The Uptime Kuma tile in that screenshot came from a command line install we ran before opening the browser. A new box shows only App Store and Files.
Install apps from the CasaOS App Store
The App Store tile opens a catalogue that listed 633 apps on our install, because the installer registers two stores: the official CasaOS store and the community BigBear store. Search for the app, open its page, and the header shows the category, developer and the memory it reserves. We used Jellyfin as the test app:
Search results often show the same app twice. The Jellyfin search returned one entry from the official store (tagged Media, “The personal Media System”) and one from BigBear (tagged Home). They are different Compose files: the official one runs linuxserver/jellyfin on host port 8097, the BigBear one pins a newer image digest on 8096. Check which one you are clicking. Install pulls the image and brings the stack up, and the dialog can run in the background:
When the pull finishes, the app gets a tile on the dashboard, marked NEW until you open it:
Store apps do not always keep the upstream port. The official Jellyfin entry published linuxserver/jellyfin:10.11.10 on host port 8097, not Jellyfin’s usual 8096, and its first-run wizard loads there:
For a media server you plan to tune (hardware transcoding, library paths, users), a plain Jellyfin install on Debian gives you more control than the store template. The store is the fast path, not the only one.
Where CasaOS keeps your files and app data
Everything user-facing lives under /DATA. The Files app browses it, and each store app gets a folder under /DATA/AppData/<app> for its config and database:
The system side lives elsewhere. Configuration sits in /etc/casaos/, the Compose file of each installed app in /var/lib/casaos/apps/<app>/docker-compose.yml, the downloaded store catalogues in /var/lib/casaos/appstore/, and the user and settings databases in /var/lib/casaos/db/. Back up /DATA and /var/lib/casaos together and you can rebuild the box. The Files app also shares these folders over Samba, and our Samba share guide for Debian explains the config file if you want to lock the shares down by hand.
Most of the day-to-day work (installing, stopping, updating and removing apps) can also be done over SSH with the casaos-cli tool the installer drops in /usr/bin. casaos-cli app-management list apps is a quick way to see every app, its state and its web UI address without opening a browser. Our CasaOS and ZimaOS CLI cheat sheet covers the rest of the commands, including the ones that fail on the current release.
Update CasaOS
Updates use a separate script. Run it over SSH, not from the terminal inside the CasaOS web UI, because the script restarts the gateway that terminal runs through:
curl -fsSL https://get.casaos.io/update | sudo bashOn a box that is already current it finishes in under a minute (44 seconds here), swaps in a fresh copy of the local store snapshot and restarts all seven services. Installed apps kept running across the restart:
- INFO Install the necessary dependencies: Rclone
- INFO Target version already installed.
- OK CasaOS upgrade successfully
- INFO restart casaos-gateway.service...
- INFO restart casaos-message-bus.service...
- INFO restart casaos-user-service.service...
- INFO restart casaos-local-storage.service...
- INFO restart casaos-app-management.service...
- INFO restart rclone.service...
- INFO restart casaos.service...Confirm the running version afterwards with casaos -v. Apps are updated separately, from each app’s settings in the UI or with the CLI.
Check the App Store after an update. On our Debian 13 box the catalogue dropped from 633 apps to 177 after this script ran: the BigBear store was still registered, but the app-management log showed it looking for the store under a different folder (lstat /var/lib/casaos/appstore/github.com/1dfcdd9e390897b516b1d990c9197b56: no such file or directory). Removing and re-adding the store brought all 633 back within a few seconds:
casaos-cli app-management unregister app-store 1
casaos-cli app-management register app-store https://github.com/bigbeartechworld/big-bear-casaos/archive/refs/heads/master.zipRun casaos-cli app-management list app-stores first to confirm the BigBear ID on your box, since the unregister command takes the ID.
Reset a forgotten CasaOS password
There is no reset link. The account lives in /var/lib/casaos/db/user.db, and moving that file aside puts CasaOS back into first-run mode, where the welcome screen lets you create a new account. Apps and files are not touched:
sudo mv /var/lib/casaos/db/user.db /var/lib/casaos/db/user.db.backup
sudo systemctl restart casaos-user-service.serviceYou can confirm the reset without a browser. The status endpoint reports "initialized":false once the user database is gone:
curl -s http://localhost/v1/users/statusOn our Debian 13 box it flipped from true to false right after the restart:
{"success":200,"message":"ok","data":{"gpus":0,"initialized":false,"key":"63ab662f-3aed-4d65-980f-97c7ee62ea4c"}}Moving user.db.backup back and restarting the service again restores the old account, so the move is safer than the rm some guides suggest.
Uninstall CasaOS from Debian
The installer drops an uninstaller in /usr/bin. It asks questions, and it reads the answers from the terminal (/dev/tty), so run it in an interactive SSH session, not from a pipeline or an automation tool:
sudo casaos-uninstallIt asks three questions and has no default: pressing Enter on Y/n is rejected, so type y or n. The container and image steps are not limited to CasaOS apps. They target every container and every image on the host, including anything you run by hand or through another manager:
[ OK ] This script will delete the containers you no longer use, and the CasaOS configuration files.
Do you want delete all containers? Y/n :y
Do you want delete all images? Y/n :y
Do you want delete all AppData of CasaOS? Y/n :y
[ INFO ] Start deleting containers.What happens next depends on how many containers you have. On our first Debian 12 run there was one app, and yes to all three removed its container, its image and /DATA/AppData. On the second run we had two CasaOS apps plus an nginx container started by hand. The script passes the list of IDs to Docker as a single quoted argument, which only works when there is exactly one, so every Docker step failed:
[ INFO ] Start deleting containers.
Error response from daemon: page not found
[FAILED] Failed to stop containers.
Error response from daemon: page not found
[FAILED] Failed to delete all containers.
[ INFO ] Start deleting all images.
Error response from daemon: page not found
[FAILED] Failed to delete all images.It then carried on and deleted /DATA/AppData anyway, while all three containers kept running with their data folders gone. The safe order is to remove the apps yourself first, then run casaos-uninstall and answer no to the first question. Use casaos-cli app-management uninstall <appid> -n to keep each app’s data in /DATA/AppData; without -n the CLI deletes that folder, which we confirmed when Syncthing’s AppData disappeared on a plain uninstall. The no branch leaves AppData alone and only offers docker image prune -af, which is host-wide too: it removes every image on the box that no container is using.
What it removes: the CasaOS services and binaries, /etc/casaos, the contents of /var/lib/casaos and the logs. What it leaves on Debian: Docker, the rclone binary, mergerfs, udevil, Samba (still running and listening on 445) and the /DATA/Documents, Downloads, Gallery and Media folders with whatever you put in them. systemd also keeps three dead CasaOS units in memory (casaos-user-service shows as failed) until you reload it:
sudo systemctl daemon-reload
sudo systemctl reset-failedIf you do not want Samba running after CasaOS is gone, stop and disable smbd yourself. The uninstaller does not touch it. Docker stays too, which is usually what you want if you move the same apps to plain Compose or a manager such as Dockge.
Debian 13 vs Debian 12 differences
The install path is identical on both releases. The differences we saw were cosmetic:
| Item | Debian 13 (Trixie) | Debian 12 (Bookworm) |
|---|---|---|
| Kernel on the test VM | 6.12 | 6.1 |
| Install time | 4m 01s | 4m 09s |
| Unit file path shown by systemctl | /usr/lib/systemd/system/ | /lib/systemd/system/ |
| Harmless pushd warning | debian/trixie | debian/bookworm |
| CasaOS, Docker, rclone versions | Same | Same |
| Web UI, App Store, Samba | Same | Same |
The CasaOS wiki still lists Debian 12 as the recommended base and does not mention Debian 13. The script itself does not check the Debian version at all, and on our Trixie VM it worked end to end.
Lock it down before you expose it
We checked the finished install the way we would check any server before giving it a port forward. Four results matter.
The CasaOS API trusts loopback. A request to /v2/app_management/compose from another machine on the LAN got 401 Unauthorized, but the same request from the server itself returned the full app list with no token. We then ran two throwaway containers on the Debian 13 box: one on the default bridge network got the 401, and one started with --network host got the 200. Any app you install with host networking can therefore install, change or delete other apps. Check an app’s network mode before you install it from a community store, and be careful with anything that asks for host networking.
The same trust extends to SSH. An SSH tunnel to port 80 on the server reaches the API without a password, and casaos-cli works for any local user, not only root. Treat SSH access to a CasaOS box as admin access to CasaOS.
File permissions are loose. /var/lib/casaos/db and the /DATA folders (AppData, Documents, Downloads, Gallery) are created with mode 0777, so any local account or any container that mounts them can read and write them. On a single-user home server that is a trade-off you may accept. On a shared machine it is not.
The dashboard is plain HTTP on port 80, and Samba listens on every interface. Keep both on the LAN and reach them from outside through a VPN such as WireGuard rather than forwarding ports on your router. If you later move to ZimaOS on dedicated hardware, it is built on the same CasaOS code, and our ZimaBoard 2 setup guide and ZimaOS static IP walkthrough cover that side.
