How to Use CasaOS: The Beginner's Guide (First Install, the Overlay Lesson, Your First App, Custom Containers, and the LAN-First Rule)

CodexFuse Team · 2026-11-01T12:08:29.476Z · 13 min read

Learn how to use CasaOS: the one-liner install, first boot, first app from the App Store, custom Docker containers, LAN-first remote access, and backups.

How to Use CasaOS: The Beginner's Guide (First Install, the Overlay Lesson, Your First App, Custom Containers, and the LAN-First Rule)

Learning how to use CasaOS is the fastest way to turn an old laptop, a mini PC, or a Raspberry Pi into a home server you can actually use. CasaOS is an open-source, beginner-friendly personal cloud system built by IceWhaleTech: a clean dashboard that sits on top of Debian, Ubuntu, or Raspberry Pi OS and wraps your server apps in Docker containers so you install them with one click. The project holds roughly 37,486 GitHub stars (per the live repository data fetched this run) and is Apache-2.0 licensed, which means the software itself is free forever. This CasaOS tutorial walks the complete first arc in one sitting: the one-liner install, the first boot, your first app from the App Store, adding a custom Docker container, the LAN-first remote-access lesson, and the backup habit that keeps your data safe. If Docker is new to you, our Docker beginner guide covers the container layer this guide builds on. One thing before you start: CasaOS serves its dashboard on port 80, so nothing else on the machine may be using that port — if you want to see what is listening on your network first, run our free port scanner.

What is CasaOS, exactly?

CasaOS is a home-server operating layer, not a full Linux distribution. That is the #1 beginner confusion, so say it once and keep it: you install CasaOS on top of a Linux you already run — Debian 12 (officially tested and recommended), Ubuntu Server 20.04 (tested), or Raspberry Pi OS (tested) — and it gives you a beautiful web dashboard for installing, managing, and accessing server apps.

Under the hood, nearly every app CasaOS installs is a Docker container. The dashboard hides the terminal entirely: instead of writing compose files by hand, you click an app in the App Store, and CasaOS pulls the image, sets the ports, creates the data folders, and wires it into your LAN. It runs on amd64, arm64, and armv7 hardware, which is why everything from a dusty Intel mini PC to a Raspberry Pi 4 makes a fine CasaOS box.

One note on direction: IceWhale, the company behind CasaOS, now banners its site with "We have upgraded CasaOS to ZimaOS," positioning ZimaOS as the successor platform. CasaOS itself remains the stable, well-documented open-source project — its latest stable release is v0.4.15 — and everything in this guide is verified against the current CasaOS documentation and repository.

How do you use CasaOS? The 8-step first arc

Before touching the terminal, here is the whole arc so you can see where you are going:

1. Prep the machine: install Debian 12 (recommended), Ubuntu Server 20.04, or Raspberry Pi OS, and free up port 80.
2. Run the one-liner: curl -fsSL https://get.casaos.io | sudo bash and wait 5–10 minutes.
3. First boot: open the dashboard IP the installer prints, click Go, and create your admin account.
4. First app: open the App Store and install one app with a single click — Jellyfin is the classic first pick.
5. Learn the dashboard: app tiles, the three-dot app settings, and the Files area.
6. Custom container: add your own Docker app by importing a docker-compose.yml file.
7. Remote access: keep the dashboard LAN-only; reach it from outside with Tailscale or Cloudflare Tunnel.
8. Back up: export each app's settings JSON and protect your /DATA/AppData folder.

What do you need before installing CasaOS?

You need far less hardware than you think. CasaOS is light: community guides commonly suggest 2GB of RAM as comfortable headroom, but that figure is their advice rather than an official stated requirement — in practice the dashboard itself sips resources and each app you add is the part that consumes them. Almost any machine made in the last decade will do.

The official support statement from the CasaOS README (fetched this run) is what you should build on. A CasaOS Raspberry Pi build is the cheapest way in — a Pi 4 or 5 with external storage makes a fine first server:

If you are deciding between bare metal and a VPS: CasaOS shines on hardware you own (old laptops, mini PCs, Raspberry Pis, NAS-style boxes). If you need a server in the cloud to practice on, our what is VPS hosting guide explains the rental-server side.

How do you install CasaOS?

The CasaOS install is one command. On your fresh Debian 12, Ubuntu Server 20.04, or Raspberry Pi OS machine, open the terminal and run:

sudo apt update && sudo apt upgrade -y
sudo apt install curl -y
curl -fsSL https://get.casaos.io | sudo bash

The installer takes about 5–10 minutes. It pulls the CasaOS packages, sets up the dashboard service, and configures the Docker plumbing. When it finishes, the terminal prints your dashboard address — usually your machine's LAN IP on port 80, something like http://192.168.1.50.

Two gotchas that catch beginners. First, port 80 must be free: if you have Apache or Nginx installed on the same machine, the install will collide. Stop or remove the other web server first (the most detailed install walkthroughs all carry this in their error tables). Second, run the installer as root or with sudo — a plain user without privileges will fail halfway with confusing permission errors.

Later, three housekeeping commands matter: casaos -v checks your installed version, re-running the installer script from https://get.casaos.io/update updates CasaOS, and casaos-uninstall removes it if you ever want the machine back.

What happens on CasaOS first boot?

Open the dashboard IP in your browser. The first screen asks you to click Go, then create your administrator username and password. This account is created once and owns the dashboard — pick a strong password, because this account can install and delete apps on your server.

Not ready to touch your own machine yet? Try before you install: the project runs a public live demo at demo.casaos.io with the credentials casaos / casaos (confirmed by two independent community guides this run). The demo resets itself, so you can click through the dashboard, the App Store, and the app settings without installing anything.

How do you install your first app on CasaOS?

Click the App Store icon on the dashboard to open the CasaOS App Store. You will see two shelves: the official pre-installed Docker apps (over 20, per the project's site) and the community-verified apps (over 50). Pick one, click Install, and wait while CasaOS pulls the image and starts the container. The app's tile appears on your dashboard; click it to open the app's web UI.

Jellyfin makes the perfect first app. It is a media server — install it, point it at a folder of videos, and you can stream your own collection to any device in the house. If you want to go deeper on what Jellyfin itself can do, our Jellyfin beginner guide walks through libraries, users, and remote streaming.

Now learn the dashboard's internals, because you will live here. Click the three-dot menu on any app tile to reach its Settings: you can adjust resource limits (like a memory slider), change the exposed port, open the terminal for that container, or remove the app. The Files area browses the server's storage from the dashboard. Spend ten minutes clicking through these panels now — that familiarity pays off every time something misbehaves later.

How do you add a custom Docker container to CasaOS?

The App Store covers the popular apps, but the real power move is the CasaOS custom container import: installing any Docker container as a first-class CasaOS app. CasaOS supports importing a docker-compose.yml file directly, and the most detailed walkthrough of this flow (from late 2024, still the reference arc) goes like this:

1. On the dashboard, click the + icon beside the "App" header.
2. Choose "Install a customized app", then switch to the Import tab.
3. Paste your docker-compose.yml content and click Submit.
4. Set the exposed host ports — if the defaults collide with something already running, pick free ones (the walkthrough uses 9095/9096 as the example pattern for avoiding conflicts).
5. Name the app, set its Web UI port, and click Install.

The imported container gets its own dashboard tile, its own three-dot settings, and the same one-click start/stop as any App Store app. The port-conflict lesson is the one to internalize: two apps cannot share a host port, and when a custom app refuses to load, the exposed port is the first thing to check.

Once you outgrow CasaOS's dashboard for container management — many containers, stacks, or team access — the next step up is a dedicated Docker GUI. Our Portainer beginner guide covers exactly that lane; CasaOS stays the beginner's front door, Portainer is the power tool behind it.

How do you access CasaOS from outside your home network?

Out of the box, CasaOS is LAN-first: the dashboard lives on your home network and is not reachable from the internet. That is a feature, not a limitation — your admin panel is not sitting on the open internet waiting to be probed.

When you want outside access, CasaOS remote access works through two safe paths, and this is the community consensus (no official CasaOS remote-access doc page was verifiable this run):

The rule every guide repeats: do not forward the CasaOS dashboard port directly from your router. Port forwarding port 80/443 straight to the admin panel is consistently called out as the least secure option. If you want the dashboard from outside, reach it over your Tailscale network; if you want to share an app (like Jellyfin) publicly, put that app — not the dashboard — behind a tunnel or an HTTPS reverse proxy with authentication.

How do you back up CasaOS?

Be honest about what CasaOS gives you here: there is no single official "back up everything" button documented in the project's wiki. Your CasaOS backup routine has two halves, and you should do both.

First, export each app's settings as JSON. CasaOS apps let you export a JSON file with their configuration — community members specifically recommend keeping those exports so reinstalls are quick. Second, protect the app-data folder. App data lives under /DATA/AppData/<AppName>/ on the CasaOS machine, following the project's AppStore pattern — that folder holds the databases, media indexes, and state that actually matter. Back up that directory (rsync to another disk, a scheduled copy to a USB drive, whatever you trust) and keep the JSON settings exports with it.

What not to back up: the OS itself and the CasaOS installation. If the machine dies, you reinstall Debian, re-run the one-liner, re-import your apps, and restore /DATA/AppData plus the JSON exports. Test the restore once on a spare disk — an untested backup is just a hope.

CasaOS vs YunoHost: which one should you pick?

This is the comparison beginners ask about most, because both promise "self-hosting for normal people." They are different products wearing similar clothes:

The honest framing: CasaOS is the fastest path from "old laptop in a drawer" to "working home server," because it slots into whatever you already run and speaks Docker. YunoHost is the deeper commitment — a fresh install that owns the whole server but gives you user management, domains, email, and backups in return. Neither is a rival of the other; they answer different questions.

Beginner mistakes to avoid with CasaOS

Sources

• GitHub — IceWhaleTech/CasaOS repository, fetched 2026-11-01: ~37,486 stars, Apache-2.0 license, created 2021-09-26; officially tested and recommended on Debian 12; Ubuntu Server 20.04 and Raspberry Pi OS tested; amd64, arm64, armv7; latest stable v0.4.15, newest pre-release v0.4.17-alpha1.
• GitHub — IceWhaleTech/CasaOS README (official install flow), fetched 2026-11-01: curl -fsSL https://get.casaos.io | sudo bash install; https://get.casaos.io/update update path; casaos -v version check; casaos-uninstall removal.
• casaos.io (official site), fetched 2026-11-01: "fully compatible with Ubuntu, Debian, Raspberry Pi OS, and CentOS with one-liner installation"; "over 20 pre-installed docker based apps and 50+ community-verified apps from app store"; "We have upgraded CasaOS to ZimaOS" banner; community testimonial on exporting a JSON file with app settings.
• globalaiforce.com — "CasaOS: How to Install and Set Up Guide 2026" (published 2026-07-03, updated 2026-08-25), fetched 2026-11-01: install arc, first-boot admin account creation, port-80-free requirement with the apache2/nginx error entry, App Store walkthrough, free-vs-paid and alternatives tables.
• maketecheasier.com — "Use CasaOS to Easily Manage Your Homelab Server" (published 2024-11-29), fetched 2026-11-01: 5–10 minute install timing, first-boot Go button + username/password creation, Nextcloud first-app walkthrough, three-dot app settings with resource sliders, custom-container import flow (+ icon → "Install a customized app" → Import → docker-compose.yml → Submit → host ports → name + Web UI port → Install).
• kextcache.com — "How to Access CasaOS Remotely", fetched 2026-11-01: CasaOS runs on port 80 by default; Cloudflare Tunnel or Tailscale recommended over port forwarding; direct port forwarding called the least secure option.
• link360.io — CasaOS remote-access walkthrough, fetched 2026-11-01: dashboard on port 80, admin account on first boot, Tailscale-based remote access.
• umatechnology.org — 2026 CasaOS guide (31 days old), fetched 2026-11-01: "Do not forward the CasaOS dashboard port directly from the router"; VPN for remote administration; expose only selected apps behind an HTTPS reverse proxy with authentication.
• deepwiki — CasaOS AppStore documentation, fetched 2026-11-01: app data persists under /DATA/AppData/<AppName>/.
• linuxconsultant.org + raspberrytips.com, fetched 2026-11-01: public live demo at demo.casaos.io with casaos / casaos credentials.
• techrepublic.com, promakai.com, techdecode.online (YunoHost coverage), fetched 2026-11-01: Debian-based self-hosting system; one-click catalog; built-in user/SSO-LDAP management; multi-domain handling; automatic Let's Encrypt SSL; email stack; native backups.

Frequently Asked Questions

Is CasaOS free?

Yes. CasaOS is open source under the Apache-2.0 license — no license fee, no per-app pricing, no paid tier for the dashboard itself. Your only costs are the hardware (often a machine you already own) and the electricity to run it.

Is CasaOS its own operating system?

No — this is the most important thing to get right. CasaOS is a dashboard overlay that installs on top of an existing Linux system (Debian 12 is officially tested and recommended; Ubuntu Server 20.04 and Raspberry Pi OS are also tested). You do not wipe your machine to install it.

Can CasaOS run on a Raspberry Pi?

Yes. The project's official README still lists Raspberry Pi OS as officially tested and supported, and the project ships arm64 and armv7 builds alongside amd64. A Raspberry Pi 4 or 5 with external storage makes a perfectly good first CasaOS box.

How do I access CasaOS remotely and safely?

Keep the dashboard LAN-only by default and reach it from outside over a private network like Tailscale, or put individual apps (not the dashboard) behind Cloudflare Tunnel. Do not forward the dashboard port directly from your router — every community guide flags that as the least secure option.

What should I back up on CasaOS?

Two things: each app's exported JSON settings, and the /DATA/AppData folder on the CasaOS machine, which holds your apps' actual data. Back up both regularly; if the machine dies, you reinstall, re-run the one-liner, and restore them.