Proxmox VE gives you a great web interface for managing virtual machines and containers — but it has no idea what's happening inside those containers. If you want to check disk usage, restart a service, or view logs on a specific LXC container, you're normally reaching for SSH and a terminal. That's fine if you're comfortable there, but it's one more thing to remember, and it's not exactly beginner-friendly.
Cockpit fixes that gap. It's a lightweight, browser-based admin panel that runs directly on a Linux system and gives you a proper GUI for managing that machine — services, logs, users, storage, even a full terminal — all from a web page. Install it in an LXC container on Proxmox VE and you get a second, complementary web interface: Proxmox manages the container from the outside, Cockpit manages what's running on the inside.
This guide walks through installing Cockpit in a fresh Debian LXC container on Proxmox VE, explains what you're actually looking at once it's running, and covers the handful of things that trip people up the first time — mostly around firewalls, PAM logins, and what does and doesn't work inside an unprivileged container.
What You Will Learn
- What Cockpit actually is and why it's different from the Proxmox web UI
- How to create a Debian LXC container suited for running Cockpit
- How to install and enable Cockpit with apt, step by step
- How to log in and find your way around the interface
- The most common errors beginners hit, and how to fix each one
- Which Cockpit features won't work properly inside an unprivileged container, and why
What Is This Feature?
Cockpit is an open-source server administration tool originally built by Red Hat, and it now ships in the default repositories of Debian, Ubuntu, Fedora, and most other mainstream distributions. Once installed, it runs a small web server on port 9090 and lets you log in with your regular Linux username and password — the same credentials you'd use over SSH.
Under the hood it's built around systemd and PAM (Pluggable Authentication Modules, the standard Linux login system). When you log into Cockpit, you're authenticating against the same user accounts as the rest of the system, and the actions you take go through the normal system tools — starting a service through Cockpit runs the same systemctl start command you'd type yourself. Nothing about it is a separate, parallel management layer. It's a GUI wrapped around the tools already on the machine.
The base install gives you a system overview (CPU, memory, and uptime graphs), a live log viewer, service management, user account management, a software updates page, and a terminal — right there in the browser, no SSH client required. Depending on what else is installed on the container, additional modules can appear automatically, like storage management or network configuration.
Why Would You Use It?
Honestly, if you're happy on the command line, you don't strictly need this. SSH plus a decent shell gets you everywhere Cockpit does, usually faster once you know the commands. But there are a few situations where Cockpit earns its keep:
You're new to Linux and would rather see a graph of memory usage than parse free -h output. You manage a container for someone else — maybe a family member's Nextcloud box or a small business server — and you want them to have a safe, visual way to check on it without giving them full shell access. Or you just want a quick way to tail logs and restart a stuck service from your phone's browser without opening a terminal app.
It's also worth being clear about what Cockpit is not. It doesn't replace the Proxmox web interface. Proxmox manages the container itself — CPU limits, memory allocation, snapshots, backups, whether the container is running at all. Cockpit only sees what's happening on the inside, from the container's own point of view. You'll likely end up using both: Proxmox to manage the container as a unit, Cockpit to manage the Linux system running inside it.
| Tool | What it manages | Where you access it |
|---|---|---|
| Proxmox VE web UI | The container/VM itself — resources, snapshots, backups, start/stop | https://your-node-ip:8006 |
| Cockpit | What's running inside the container — services, users, logs, updates | https://container-ip:9090 |
| SSH | Same as Cockpit, but command-line only | ssh root@container-ip |
Prerequisites
You don't need anything exotic for this. Cockpit is light on resources and doesn't need privileged access to do its basic job.
- A working Proxmox VE 8.x or 9.x host with at least one storage location that has a Debian container template
- A Debian 12 (bookworm) or Debian 13 (trixie) LXC container template downloaded — Ubuntu works too, but this guide uses Debian
- At least 512 MB of RAM and 1 vCPU assigned to the container (Cockpit itself is light, but leave headroom for whatever else the container runs)
- Around 300 MB of free disk space for Cockpit and its dependencies
- Basic comfort typing a few commands in the Proxmox shell or an LXC console — you don't need to be an expert, just able to copy and paste
Step-by-Step Tutorial
Step 1: Create a Debian LXC container
If you already have a container you want to manage with Cockpit, skip ahead to Step 2. Otherwise, from the Proxmox web UI, click Create CT in the top right.
- General: give it a hostname like
cockpit-demo, and set a root password (or add an SSH key — either works). - Template: pick a Debian 12 or Debian 13 template. If you don't see one listed, go to your storage's CT Templates tab and download it first.
- Disk: 4-8 GB is plenty for a management-only container.
- CPU/Memory: 1 core and 512 MB RAM is fine to start.
- Network: attach it to your usual bridge (commonly
vmbr0) with DHCP, or set a static IP if that's how you normally run things.
Leave everything else at its default. You don't need privileged mode and you don't need nesting enabled — Cockpit doesn't touch either of those. Start the container once it's created.
Step 2: Update the container and install Cockpit
Open the container's console from the Proxmox UI (select the container, click Console) or SSH into it. Run:
apt update && apt full-upgrade -yThis refreshes the package list and applies any pending updates, so you're not installing on top of a stale image. Then install Cockpit:
apt install -y cockpitThis pulls in the core Cockpit packages plus a handful of optional modules Debian bundles by default, things like storage management and software update tooling. Expect this to download somewhere around 30-50 MB depending on what's already present, and it usually finishes in under a minute on a reasonable connection.
Step 3: Confirm Cockpit is running
On Debian, installing the package automatically enables and starts the cockpit.socket unit — you shouldn't need to start it manually. Check anyway, because it's a two-second sanity check that saves confusion later:
systemctl status cockpit.socketYou're looking for Active: active (listening) in the output. If it says inactive or failed instead, enable and start it yourself:
systemctl enable --now cockpit.socketThen double-check something is actually bound to port 9090:
ss -tlnp | grep 9090Step 4: Find the container's IP address
If you don't already know it, either check the Summary tab for the container in the Proxmox UI, or run this inside the container:
ip -4 addr show eth0Note the address after inet — that's what you'll browse to.
Step 5: Log in through the browser
From a machine on the same network, go to:
https://CONTAINER-IP:9090Your browser will warn you the connection isn't private. That's expected — Cockpit generates a self-signed certificate on first run, the same way Proxmox's own web UI does. Click through the warning (in Chrome, Advanced → Proceed; in Firefox, Advanced → Accept the Risk and Continue).
Log in with the root username and the password you set when creating the container. If you'd rather not log in as root over the web — a reasonable instinct — create a regular user first and add it to the sudo group:
adduser yourname
usermod -aG sudo yournameLog in as that user instead, and check the Reuse my password for privileged tasks box when Cockpit asks, so it can escalate with sudo when needed.
Step 6: Take a look around
Once you're in, the left sidebar is your map. Overview shows CPU, memory, and disk graphs updating in real time. Logs lets you filter the systemd journal by service, priority, or time range without touching journalctl syntax. Services lists every systemd unit with start/stop/restart buttons. Terminal gives you a real shell in the browser tab, which is genuinely handy when you're on a tablet or a locked-down work laptop with no SSH client installed.
Spend five minutes clicking through before you rely on it for anything important. It's a small enough interface that a quick tour is all you need.
Commands Explained
| Command | What it does |
|---|---|
apt update | Refreshes the local list of available packages and versions from Debian's repositories, without installing anything yet |
apt full-upgrade -y | Installs available updates, including ones that add or remove packages if a dependency changed — safer than a plain upgrade on a fresh template |
apt install -y cockpit | Installs the Cockpit metapackage and its default modules; -y skips the confirmation prompt |
systemctl status cockpit.socket | Shows whether the Cockpit listener is active and bound to a port, plus recent log lines |
systemctl enable --now cockpit.socket | Enables the socket to start on boot and starts it immediately, in one command |
ss -tlnp | Lists listening TCP ports and the process bound to each — useful for confirming Cockpit is actually reachable before you blame the network |
usermod -aG sudo yourname | Adds an existing user to the sudo group, letting them run privileged commands (and use Cockpit's admin features) without being root |
Common Errors
"This site can't be reached" / connection times out. Almost always one of three things: Cockpit isn't running yet, you've got the wrong IP address, or a firewall is in the way. Check systemctl status cockpit.socket first before anything else.
"ERR_CONNECTION_REFUSED" instead of a timeout. This is actually a slightly better sign than a timeout — it means the network path is fine, but nothing is listening on port 9090. Run the ss -tlnp check from Step 3 again.
"Authentication failed" when you're sure the password is right. Double-check you're not accidentally including a trailing space when copy-pasting a password, and confirm the account isn't locked. Run passwd -S root — if the status shows L instead of P, the account has no usable password and Cockpit's PAM login will reject it even though the container itself is running fine.
Storage or Network tabs are missing, or show almost nothing. This isn't a bug, it's expected. The Storage module wants direct access to block devices, which an unprivileged LXC container doesn't have — it's virtualized. Same story with the Networking module, which depends on NetworkManager, a service that Debian's default LXC templates don't run (they use the simpler ifupdown setup instead). Cockpit isn't broken; it just doesn't have those pieces to work with inside a container.
Troubleshooting
If the browser warning about the self-signed certificate feels wrong to skip, that instinct is healthy in general — just not here. Every fresh Cockpit install generates its own certificate, and there's no CA behind it to verify against unless you set one up yourself. For a container only reachable on your own LAN, clicking through is normal. If it genuinely bothers you, later on you can drop a proper certificate into /etc/cockpit/ws-certs.d/ and Cockpit will pick it up automatically on restart.
If the page loads but hangs on "Connecting" indefinitely, it's usually a WebSocket issue — something between your browser and the container is stripping the upgrade headers Cockpit needs. This shows up most often if you're trying to reach Cockpit through a reverse proxy that wasn't configured for WebSocket passthrough. Accessing it directly by IP, as this guide does, sidesteps that entirely.
If you enabled the Proxmox VE firewall on this container (under the container's Firewall tab), remember it defaults to blocking inbound traffic that isn't explicitly allowed. Add a rule permitting TCP port 9090 from your management network, or temporarily disable the firewall on that container while you confirm everything else works, then lock it back down properly afterward.
Locked yourself out because you can't remember the root password? You don't need Cockpit for this one — open the container's console from the Proxmox UI (which doesn't need a password) and run passwd to set a new one directly.
Best Practices
Don't expose Cockpit to the internet by forwarding port 9090 through your router. It's a full administrative interface to the container — treat it the same way you'd treat SSH or the Proxmox UI itself, reachable only from your own network or through a VPN like WireGuard or Tailscale if you need remote access.
Create a dedicated non-root user for day-to-day logins rather than using root directly, even in a homelab. It costs you thirty seconds during setup and means an accidental typo in a destructive command needs an extra confirmation step first.
If you're running Cockpit on more than one container or VM, it's worth knowing Cockpit supports adding other machines from within the interface itself, giving you one dashboard for several hosts. That's outside the scope of a beginner install, but it's the natural next step once you're comfortable with a single instance.
Keep the container updated the normal way — apt update && apt full-upgrade periodically — the same as any other Debian system. Cockpit doesn't manage its own updates outside of that.
Frequently Asked Questions
Does Cockpit replace the Proxmox VE web interface?
No. Proxmox manages containers and VMs from the outside — resources, snapshots, backups. Cockpit only manages what's running inside one specific container or VM. Most people end up using both.
Can I install Cockpit directly on the Proxmox host itself?
Technically yes, since Proxmox VE is built on Debian. In practice it's not recommended — you'd be adding a second web-based admin panel to a system that already has one, and the two aren't aware of each other. Running Cockpit inside a dedicated container, as this guide does, keeps things cleanly separated.
Do I need a privileged container for this?
No. Everything covered in this guide works fine in the default unprivileged container. You'd only need privileged mode for Cockpit features that touch raw hardware, and those aren't things a beginner setup needs anyway.
Why does Cockpit use port 9090 specifically?
It's just the project's default, set in the systemd socket unit. There's nothing special about the number — you could remap it by editing cockpit.socket, though most people leave it as-is since it rarely conflicts with anything else on a dedicated container.
Is Cockpit safe to leave running all the time?
Yes, assuming it's only reachable on your own network. It's actively maintained, ships in Debian's stable repositories, and gets security updates through the normal apt update process — same as any other package on the system.
What happens if I stop the container Cockpit is running in?
Cockpit stops along with it, same as any other service in the container. It has no dependency on anything outside that container, so restarting the container brings it right back.
Conclusion
Cockpit is a small install with an outsized payoff for anyone still getting comfortable on the command line: a real dashboard for the system living inside your container, reachable from any browser on your network, backed by the exact same tools you'd use over SSH. It won't replace the Proxmox interface, and it's not trying to — the two sit at different layers and complement each other well.
If you found this useful, the same container makes a fine testbed for trying out a few of Cockpit's other modules once you're comfortable, or for practicing the kind of system administration tasks that are easy to fumble the first time on a bare terminal.