Skip to content
subcloakdocs
subcloak.comDownload

Get started

Install on Linux (beta)

Since 0.4.0 Requires Cloak Proxy 0.4.0 or later.

Install the Cloak Proxy beta on Ubuntu, Debian, Fedora and other Linux desktops from a .deb, an RPM, an AppImage or a portable folder, trust its certificate, use the desktop's proxy, and uninstall it.

Cloak Proxy for Linux is in beta. It’s the same engine as the Mac app, so capture, HTTPS decryption, the debugging tools, cloakctl and the MCP server work the same way, with the traffic window, the API client and the other windows shown in GTK windows. A few things differ: see What the beta doesn’t do yet.

Cloak Proxy on Ubuntu 24.04.

Cloak Proxy's window on Linux: the sidebar groups requests by app and domain, and the traffic list shows four requests captured from curl

Check the requirements

Section titled “Check the requirements”
Requirement Details
Distribution Ubuntu 24.04 or later, Debian 13 (trixie) or later, Fedora 43 or later and RHEL 10-compatible distributions, or another distribution with GTK 4 and WebKitGTK 6.0 (with the AppImage or the portable folder)
Processor x86_64 (amd64) or ARM64 (aarch64)
Desktop GNOME or KDE Plasma for the system proxy switch. Other desktops work too: point apps at the proxy yourself.
Disk space About 120 MB once installed, plus WebKitGTK if you don’t have it yet
Account None. Cloak Proxy is free for life.

Download and install

Section titled “Download and install”

  1. Go to subcloak.com/apps/cloak-proxy and click Download for Linux. Pick the .deb for your processor: cloak-proxy_0.4.2_amd64.deb for most PCs, cloak-proxy_0.4.2_arm64.deb for ARM computers. Not sure? Run dpkg --print-architecture.

  2. Optional: check the file is the one Subcloak published. Compare the output with the SHA-256 on the download page:

    Terminal
    sha256sum ~/Downloads/cloak-proxy_0.4.2_amd64.deb

  3. Install it with apt, which also installs the libraries it needs (GTK 4, WebKitGTK and the tools that trust the certificate in Chrome and Firefox):

    Terminal
    sudo apt install ~/Downloads/cloak-proxy_0.4.2_amd64.deb

    Keep the ./ or full path: without it, apt looks for a package of that name online. Double-clicking the file opens it in your software center, which works too.

  4. Open Cloak Proxy from your app menu, or run cloak-proxy in a terminal.

Open Cloak Proxy the first time

Section titled “Open Cloak Proxy the first time”

Like on the Mac, the first launch sets things up on your computer only. Nothing is sent anywhere.

  1. It creates a root certificate and its private key in ~/.local/share/cloakproxy. It uses them to decrypt HTTPS for the hosts and apps you choose. See Root certificate.

  2. It starts the proxy on port 9090, on 127.0.0.1, so only this computer can use it until you allow other devices.

  3. It opens its window. Without a display (an SSH session, for example) it opens the same page in your default browser instead. The page is served on 127.0.0.1 only, with a key that changes every launch.

Unlike the Mac app, the Linux beta doesn’t change your proxy settings or trust the certificate until you ask it to. The next two sections do both.

Trust the certificate

Section titled “Trust the certificate”

To decrypt HTTPS, the apps you debug must trust Cloak Proxy’s certificate. Linux has no single place for that: command-line tools read the system’s certificates, and Chrome and Firefox keep their own databases. Cloak Proxy installs it in all of them at once.

  1. Open Settings from the menu button (Ctrl ,) and choose Certificate.

  2. Click Install Everywhere.

  3. Your desktop asks for your password. The prompt says Cloak Proxy wants to change the system’s trusted certificates: that’s the system store, which curl, Python, Node, Git and most other tools read. Chrome, Chromium and every Firefox profile (including the Snap and Flatpak ones) are your own files and need no password.

  4. Where it’s trusted lists each store with Trusted next to it. Restart Chrome and Firefox if they were open.

From a terminal, cloak-proxy --install-ca does the same, and cloak-proxy --trust-status lists where it’s trusted.

With the AppImage, Install Everywhere trusts the certificate in Chrome and Firefox but leaves the system’s store alone, and shows the command that adds it there (sudo install -m 644 … && sudo update-ca-certificates on Debian and Ubuntu, sudo trust anchor --store … on Fedora). Run it once in a terminal; Where it’s trusted then shows the system store as trusted.

Send this computer’s traffic through Cloak Proxy

Section titled “Send this computer’s traffic through Cloak Proxy”

Open Device Setup… from the menu button and click Use the System Proxy. Cloak Proxy points the desktop’s proxy setting (GNOME’s network proxy, or KDE Plasma’s) at itself, and puts your previous setting back when it quits. If it’s killed instead, a small guard process restores the setting for you.

GNOME and KDE apps, Chrome, Chromium and Firefox (when set to use the system proxy, its default) follow this setting. To turn it on at every launch, open Settings › General and turn on Use the desktop’s proxy setting on launch.

Then turn on SSL Proxying for the hosts or apps you want to read, and the Quick start carries on from there.

Run it without a window

Section titled “Run it without a window”

On a server, in a container or in CI, run the proxy headless and drive it with cloakctl or the MCP server:

Terminal
cloak-proxy --headless --install-ca --system-proxy
cloakctl list

It stops on Ctrl C, restoring the proxy setting. cloak-proxy --help lists every option, and man cloak-proxy and man cloakctl Since 0.4.2 explain them. See Headless and CI.

Where Cloak Proxy keeps its files

Section titled “Where Cloak Proxy keeps its files”
  • Directory~/.config/cloakproxy/
    • proxy-configuration.json settings and debugging tool rules
    • preferences.json
    • web-ui.json the window’s layout: tabs, columns, pane sizes
    • system-proxy-snapshot.json your own proxy setting, while Cloak Proxy has changed it
  • Directory~/.local/share/cloakproxy/
    • cloak-proxy-ca.pem the root certificate
    • cloak-proxy-ca-key.pem its private key (readable only by you)
    • api-token the token for cloakctl and MCP
    • DirectorySession/ captured traffic, kept across launches
      • …
    • DirectoryWorkspace/ the API client workspace
      • …
  • Directory~/.local/state/cloakproxy/ logs
    • …

The .deb and the RPM install the app in /usr/lib/cloak-proxy, its page in /usr/share/cloak-proxy, cloak-proxy and cloakctl in /usr/bin, and their man pages. The AppImage installs nothing: --integrate adds only a menu entry, icons, two links in ~/.local/bin and the man pages, all in your home folder. API client secrets go to your desktop’s keyring (the Secret Service) when there is one, or to a file only you can read.

Update to a new version

Section titled “Update to a new version”

Download the new .deb and install it the same way: sudo apt install ./cloak-proxy_VERSION_amd64.deb replaces the old version and keeps your settings, certificate and workspace. With the RPM, sudo dnf install ./cloak-proxy-VERSION-1.x86_64.rpm does the same. With the AppImage, replace the file, and run --integrate again if its name changed. With the portable folder, unpack the new one and run its install.sh again.

Help › Check for Updates… Since 0.4.1 says when there’s a new version, but it doesn’t install it for you: How to Update opens the download page. In 0.4.1 the automatic check (Check for updates automatically in Settings › General, or Check for updates once a day in the update window) is on by default: it checks when the window opens and shows Update available in the status bar. Turn it off there if you don’t want it. The check asks download.subcloak.com for the latest version number and nothing else.

Since 0.4.2 From 0.4.2, automatic checks are off until you turn them on in Settings › General › Updates, as on the Mac. If you used 0.4.1 or earlier, where the daily check was on by default, 0.4.2 turns it off unless you’d chosen it yourself; turn it on again if you want it. The same section adds Help count active installs (anonymous), off by default, which sends the app version and platform with each check. See Check for updates.

Uninstall Cloak Proxy

Section titled “Uninstall Cloak Proxy”

  1. Remove the certificate, while Cloak Proxy is still installed: Settings › Certificate › Remove Everywhere, or cloak-proxy --uninstall-ca. Uninstalling the package doesn’t do this for you, and a certificate left trusted is one less safeguard. Settings › Advanced › Undo All System Changes Since 0.4.1 does this and more in one go: it puts the desktop’s proxy setting back, removes the certificate from the system and the browsers, and turns DNS capture off, after one password prompt.

  2. Quit Cloak Proxy, so your proxy setting comes back.

  3. Remove the package:

    Terminal
    sudo apt remove cloak-proxy

    On Fedora and RHEL, sudo dnf remove cloak-proxy. With the AppImage, run it with --unintegrate if you used --integrate, then delete the file. With the portable folder, run ./install.sh --uninstall and delete the folder.

  4. Delete its files, if you don’t want to keep them. Copy ~/.local/share/cloakproxy/Workspace first if it holds collections you need.

    Terminal
    rm -rf ~/.config/cloakproxy ~/.local/share/cloakproxy ~/.local/state/cloakproxy

If websites stop loading after Cloak Proxy is gone, your desktop’s proxy may still point at it: open Settings › Network › Network Proxy in GNOME (or System Settings › Network › Proxy in KDE) and choose Disabled (No proxy), or run gsettings set org.gnome.system.proxy mode none.

What the beta doesn’t do yet

Section titled “What the beta doesn’t do yet”

Since 0.4.1 the Linux beta has the Mac app’s windows: the traffic list and inspector, the debugging tools, Insights and Privacy Map, the Doctor and DNS capture, the testing windows (Authorization Matrix, API Contracts, Release Diff, Make Tests, Compare Environments, Failure Scenarios), Distributed Tracing, Report Bug, the query bar, live sharing, the browser extension, the in-app SDK listener, and the API client with every protocol, the runner, mocks, flows, monitors, specs and Git. What’s still different:

  • The web companion isn’t in the Linux app. To show your traffic in someone else’s browser, use Live sharing.
  • DNS capture needs the .deb or the RPM, and systemd-resolved; the AppImage and the portable folder can’t capture domains. See On Linux.
  • Not tried on Linux yet: the browser extension in a real browser, Postgres and MySQL servers in the API client, and MQTT over TLS or WebSocket. They’re the same code as on the Mac; tell us if they don’t work.
  • KDE Plasma proxy switching has only been checked against a simulated desktop. If it doesn’t stick on your Plasma version, open an issue.
  • Packages: .deb, RPM Since 0.4.2, AppImage Since 0.4.2 and a portable folder. Flatpak comes later; the RPM has been tried on Fedora 43 and 44 and AlmaLinux 10, the AppImage on Ubuntu 24.04.

Found something broken? Open an issue with your distribution, desktop and the version you installed (dpkg -s cloak-proxy | grep Version, rpm -q cloak-proxy, or the AppImage’s file name).

Section titled “Related”