COCKPIT-WS(8)

💅 COCKPIT-WS(8) — the cockpit manual, bestie edition ✨

okay so. <rainbow>cockpit-ws</rainbow>?? That's the Cockpit web service, and it's section 8 of the cockpit manual. sit down, hydrate, and let's get into it 🫶

---

✨ NAME ✨

cockpit-ws — the Cockpit web service, aka the little guy doing all the talking 💬

---

🎀 SYNOPSIS 🎀

cockpit-ws [--help] [--port PORT] [--address ADDRESS] [--no-tls]
[--for-tls-proxy] [--local-ssh] [--local-session BRIDGE]

that's the whole vibe. onto the details 👑

---

🦋 DESCRIPTION 🦋

cockpit-ws is the web service component. It's the thing that handles communication between your browser app and all the various configuration tools and services like cockpit-bridge(1). So it's basically the mutual bestie connecting two friend groups 💞

IMPORTANT: users and administrators should never need to start this program themselves. It gets started automatically by systemd(1) on boot up, through cockpit-tls(8). It starts itself. It's independent. main character energy, no notes 💅

---

🔐 TRANSPORT SECURITY 🔐

normally cockpit-ws runs behind the cockpit-tls TLS terminating proxy, and it only deals with unencrypted HTTP by itself. periodt.

BUT (and this is the plot twist 🎬) for backwards compatibility it can also handle TLS connections by itself if you run it directly. and if you wanna know how to configure certificates? bestie, go read the cockpit-tls(8) documentation. iykyk 📜

---

⏰ TIMEOUT ⏰

when it's started via systemd(1), cockpit-ws will exit after 90 seconds if nobody logs in. or after the last user is disconnected. it simply will not wait around for you, bestie. it has boundaries ✋💀

---

👑 OPTIONS 👑

• --help — shows the help options. the classic. the icon 🫶
• --port PORT — serve HTTP requests on PORT instead of port 9090. but lowkey: usually Cockpit is started on demand by systemd socket activation, so this option has no effect. in that case you update the ListenStream directive in the cockpit.socket file in the usual systemd manner. (yes, the socket file. not a typo, it's the systemd way 💅)
• --address ADDRESS — bind to address ADDRESS instead of binding to all available addresses. same deal as above: usually Cockpit starts on demand via systemd socket activation, so this option has no effect. in that case, update the ListenStream directive in the cockpit.socket file in the usual systemd manner.
• --no-tls — disable the http to https redirection. simple. clean. no drama 🚫🔒
• --for-tls-proxy — tells cockpit-ws that it's running behind a local reverse proxy doing the TLS termination. then Cockpit puts https:// URLs into the default Content-Security-Policy, and accepts only https:// origins instead of http: ones by default. HOWEVER — if Origins is set in the cockpit.conf(5) configuration file, that will override this default. the config file said "not today" 😭
• --local-ssh — normally cockpit-ws uses cockpit-session and PAM to authenticate the user and start a user session. with this option enabled, it will instead authenticate via SSH at 127.0.0.1 port 22. plot twist, but make it SSH 🧚
• --local-session BRIDGE — skips all authentication and cockpit-session, and launches the cockpit-bridge specified in BRIDGE in the local session. if BRIDGE is specified as - then expect an already running bridge that's connected to stdin and stdout of this cockpit-ws process. this lets the web server run as any unprivileged user in an already running session ✨

this mode implies --no-tls, bestie. so you need to use http:// URLs with this. no cap.

⚠️ WARNING ⚠️ with --local-session BRIDGE, you have to isolate the opened TCP port somehow — for example in a network namespace — otherwise all other users (or even remote machines, if the port isn't just listening on localhost) can access the session!! that's not a vibe. that's a security incident 💀🔥

---

🌈 ENVIRONMENT 🌈

the cockpit-ws process will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) to find its cockpit.conf(5) configuration file 📂

in addition, the XDG_DATA_DIRS environment variable from the XDG basedir spec (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) can be used to override the location to serve static files from. these are the files that get served to a non-logged in user. mysterious. anonymous. love that for them 👻

---

💀 BUGS 💀

please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/cockpit-project/cockpit/issues/new — they wanna hear it, fr fr 🙈

---

💖 AUTHOR 💖

Cockpit has been written by many contributors 🌸 — https://github.com/cockpit-project/cockpit

---

🔥 SEE ALSO 🔥

• cockpit-tls(8)
• cockpit.conf(5)
• systemd(1)

---

and that's the whole page bestie, we ate and left no crumbs 🍓 this gorgeous little thing came out of cockpit and it's dated 2026-10-22 — so go forth, never start cockpit-ws by hand, and slay 💅✨👑