CasaOS handles the basics well—it gives you a clean dashboard for your homelab and installs Docker containers with one click. But if you want actual visibility into what’s running, you need metrics. That’s where integrating CasaOS with Grafana makes sense. Instead of glancing at the resource meter on the CasaOS dashboard, you get a proper monitoring stack that persists data, lets you build custom dashboards, and doesn’t disappear when you restart.
Why CasaOS + Grafana Works (and Where It Doesn’t)
CasaOS comes with a basic system dashboard. It shows CPU, memory, disk space, and network traffic. Good enough to know if your machine is choking, not good enough if you actually want to understand patterns. Grafana solves that, but it adds complexity. You’re now running Prometheus to scrape metrics, Grafana to visualize them, maybe Alertmanager if you want notifications. It’s worth it if you’re running multiple services or tuning performance. It’s overkill if your homelab is three Docker containers.
That said, CasaOS isn’t fighting you here. It runs on standard Docker. Prometheus can scrape metrics from the host. Grafana can talk to Prometheus. There’s no proprietary lock-in. The integration is straightforward, though nobody pretends it’s truly seamless—you’re still gluing together three pieces of open-source software.
Prerequisites and Hardware
You need a CasaOS instance already running. I’m assuming you’ve got it installed on a Linux box (bare metal, VM, doesn’t matter) and can SSH in or access its terminal. You’ll also need another machine or container space for Prometheus and Grafana, though you can run them on the same hardware if it has headroom.
RAM matters here. CasaOS itself is lightweight. Prometheus will consume 200–500 MB depending on how many metrics you’re scraping and how long you keep them. Grafana takes another 100–200 MB. If you’re running on a 2 GB Raspberry Pi with three other services, this gets tight. I’d recommend at least 4 GB total if you’re doing anything serious.
Network access: CasaOS needs to expose metrics on a port (default 9100 for node-exporter, or you can use the built-in cAdvisor on 8080). Prometheus needs to reach that port. Grafana needs to reach Prometheus. If everything’s on the same LAN and you’re not filtering traffic, you’re fine. If you’ve got strict firewall rules, you’ll need to poke holes.
Installing Prometheus and Grafana via CasaOS App Store
This is where CasaOS’s strength shows. Both Prometheus and Grafana are in the app store. You can install them in about two minutes without touching Docker Compose or environment variables.
Log into your CasaOS dashboard. Go to the App Store tab. Search for “Prometheus.” Click install. Wait maybe thirty seconds. Repeat for Grafana. Both will start automatically.
Prometheus defaults to port 9090. Grafana defaults to 3000. Check that they’re running by visiting http://your-casa-ip:9090 and http://your-casa-ip:3000. Grafana’s default login is admin/admin—change it immediately if this is exposed to anything other than your local network.
Here’s where the CasaOS experience gets a little thin: the app store installations are mostly defaults. Prometheus isn’t configured yet. It has no targets to scrape. Grafana is running but has no data source. You’ll need to get your hands a little dirty anyway.
Configuring Prometheus to Scrape CasaOS Metrics
Prometheus needs a configuration file that tells it what to scrape and where. You have two approaches: edit the Prometheus config directly, or use CasaOS’s file manager to add a custom config.
The cleaner path is SSH into the CasaOS machine and find where Prometheus is running. If you installed it via CasaOS app store, it’s likely in a Docker volume. You can find the container ID with:
docker ps | grep prometheusThen inspect the volume:
docker inspect <container-id> | grep -A 5 MountsPrometheus’s config is usually at /var/lib/docker/volumes/<volume-name>/_data/prometheus.yml. Back it up, then edit it. You need to add a scrape job for the CasaOS host. At minimum:
scrape_configs:
- job_name: 'casaos-host'
static_configs:
- targets: ['localhost:9100']
labels:
instance: 'casaos-main'But wait—this assumes node-exporter is already running on port 9100. CasaOS doesn’t install it by default. You have two options. One: install node-exporter as a separate container (available in the app store). Two: use CasaOS’s cAdvisor metrics endpoint, which is usually on port 8080.
I went with node-exporter because it’s more reliable and gives you OS-level metrics, not just container stats. Install it from the app store. Then update Prometheus config:
scrape_configs:
- job_name: 'casaos-host'
static_configs:
- targets: ['localhost:9100']
- job_name: 'cadvisor'
static_configs:
- targets: ['localhost:8080']Save the file. Restart Prometheus (easiest via CasaOS dashboard—stop and start the container). Within a minute, check the Prometheus UI at port 9090. Go to Status > Targets. You should see your jobs in the “Up” state. If they’re “Down,” you have a port or network issue.
This is the friction point, honestly. Setting up targets feels like it should be a UI in CasaOS, but it isn’t. You’re editing config files. It’s not hard, but it breaks the “one-click” promise.
Connecting Grafana and Building a Dashboard
Once Prometheus is scraping, Grafana needs to know about it. Log into Grafana. Go to Configuration > Data Sources. Add a new Prometheus data source. URL: http://prometheus:9090 (if they’re on the same Docker network) or http://your-casa-ip:9090 (if they’re separate containers). Save and test. You should get a green checkmark.
Now create a dashboard. Instead of building from scratch, import a community dashboard. Search for “Node Exporter Full” on Grafana.com (ID 1860). Copy the ID, go back to Grafana, and import it. Select your Prometheus data source. The dashboard builds itself in seconds.
You’ll see CPU usage, memory, disk I/O, network traffic—all the stuff CasaOS shows you, but now with history and proper visualization. Drill down by hour or day. Set up alerts when CPU hits 80%. This is what you paid nothing for by running it yourself instead of using a SaaS monitoring tool.
The imported dashboards sometimes need tweaking. Variable names might not line up perfectly depending on how you labeled your scrape jobs. If you see “no data” on a panel, click the edit button and check the query. Usually it’s a label mismatch. Change instance="node" to whatever you actually named it in Prometheus config.
Handling Data Retention and Storage
Prometheus stores metrics in a time-series database. By default, it keeps 15 days of data at a 15-second resolution. If you’re running a homelab, that’s probably fine. But if you want longer history, you need to adjust retention or enable external storage.
To change retention, edit the Prometheus startup command. CasaOS runs containers with predefined settings, so you’ll need to either modify the app’s configuration or manage Prometheus yourself via Docker Compose.
The easier path: accept the defaults for now. If you find yourself wanting six months of metrics, you’ll already understand the setup well enough to add a persistent volume or migrate to something like Victoria Metrics. Don’t over-engineer on day one.
Common Issues and Fixes
Targets showing “Down” in Prometheus: First, check network connectivity. Can you ping the target from inside the Prometheus container? Run docker exec <prometheus-container> curl localhost:9100. If that fails, node-exporter isn’t running or isn’t on port 9100. Verify it’s installed and check which port it’s using.
Grafana can’t reach Prometheus: Make sure you’re using the correct hostname. If both are Docker containers on the same network, use the container name (usually just “prometheus”). If they’re on different networks or machines, use the IP address. “localhost” won’t work from Grafana if Prometheus is a separate container.
Prometheus consuming too much disk: Check its volume size. A week of metrics from a moderately active host is typically 1–2 GB. If you’re running out of space, either reduce retention or move the volume to a bigger disk.
Dashboard panels show no data: Check the time range selector in Grafana (top right). If you just started scraping, try “Last 1 hour.” Also verify that labels in your dashboard queries match what Prometheus is actually collecting. Use the Prometheus UI to test queries.
When to Keep CasaOS’s Dashboard Instead
Not every homelab needs Grafana. If you’re running a small setup and just checking in once a day, CasaOS’s built-in dashboard is sufficient and uses less resources. The integration only makes sense if you’re actively tuning performance, running multiple services, or want historical data for troubleshooting.
Where I found the combo valuable: I had a Plex container that was consuming way more CPU than expected. With CasaOS alone, I could see it was hot right now. With Grafana, I could see the spike happened every night at 2 AM—a scheduled library scan. That kind of visibility takes real monitoring, not a status page.
The integration also freed me from obsessively checking the dashboard. Grafana alerts can notify you (via email, Slack, Discord, whatever) when things go wrong. CasaOS has no alert system. You’re either watching or you’re blind.
I will say this though: setting up Prometheus and Grafana properly takes longer than the CasaOS marketing suggests. You’re not clicking one button and getting a professional monitoring stack. You’re using CasaOS as a convenient package manager, then doing the real work yourself. That’s fine—that’s actually what CasaOS is good for—but don’t expect it to hide the complexity.
FAQ
Does CasaOS work with Prometheus out of the box?
CasaOS can install Prometheus via its app store, but Prometheus needs to be configured with scrape targets. It doesn’t automatically discover CasaOS metrics. You’ll need to add a job that points to node-exporter (port 9100) or cAdvisor (port 8080) to actually collect data.
Can I use CasaOS with an existing Prometheus instance?
Yes. CasaOS doesn’t care where Prometheus is. As long as Prometheus can reach your CasaOS host on the metrics port (9100 for node-exporter, 8080 for cAdvisor), you can scrape it. You’ll just configure the target in your external Prometheus config.
What’s the performance impact of adding Prometheus and Grafana?
Prometheus uses 200–500 MB RAM depending on how much you’re scraping. Grafana uses 100–200 MB. If you’re running on tight hardware (under 2 GB total), it’s noticeable. On a modern homelab machine (4 GB+), it’s negligible.
Does CasaOS have a built-in monitoring system I can use instead?
CasaOS has a basic dashboard showing CPU, memory, and disk. It’s sufficient for quick checks but doesn’t persist data, doesn’t alert, and doesn’t let you build custom views. Grafana is a real monitoring platform. They’re solving different problems.
Can I monitor multiple CasaOS instances with one Prometheus?
Absolutely. Add a scrape job for each host, giving each one a different label so you can distinguish them in Grafana. For example, one job with targets: ['casa-main:9100'] and another with targets: ['casa-backup:9100']. Same Prometheus, multiple sources.
Explore CasaOS in our AI Homelab Toolkit.