# Install on Linux (beta)

> 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.

Source: https://docs.subcloak.com/cloak-proxy/getting-started/install-linux/

Added in Cloak Proxy 0.4.0.

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](#what-the-beta-doesnt-do-yet).

*[Screenshot: Cloak Proxy's window on Linux: the sidebar groups requests by app and domain, and the traffic list shows four requests captured from curl. Cloak Proxy on Ubuntu 24.04.]*

## 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](https://docs.subcloak.com/cloak-proxy/getting-started/free-for-life/). |

## Download and install

**Ubuntu and Debian (.deb)**

1. Go to [subcloak.com/apps/cloak-proxy](https://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:

   ```bash title="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):

   ```bash title="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.

**Fedora and RHEL (RPM)**

1. Go to [subcloak.com/apps/cloak-proxy](https://subcloak.com/apps/cloak-proxy) and click **Download for Linux**. Pick the RPM for your processor: `cloak-proxy-0.4.2-1.x86_64.rpm` for most PCs, `cloak-proxy-0.4.2-1.aarch64.rpm` for ARM computers. Not sure? Run `uname -m`.

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

   ```bash title="Terminal"
   sha256sum ~/Downloads/cloak-proxy-0.4.2-1.x86_64.rpm
   ```

3. Install it with dnf, which also installs the libraries it needs (GTK 4, WebKitGTK 6.0, and `nss-tools` to trust the certificate in Chrome and Firefox):

   ```bash title="Terminal"
   sudo dnf install ~/Downloads/cloak-proxy-0.4.2-1.x86_64.rpm
   ```

   The RPM isn't signed, so dnf installs it from the file without a key. On RHEL 10 and compatible distributions (AlmaLinux, Rocky Linux), WebKitGTK 6.0 comes from EPEL: run `sudo dnf install epel-release` first.

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

**Any distribution (AppImage)**

The AppImage is one file that runs without installing anything. It uses GTK 4 and WebKitGTK 6.0 from your distribution rather than bringing its own copy, which keeps it smaller and gets WebKit's security fixes from your updates.

1. Download `cloak-proxy-0.4.2-x86_64.AppImage` (or `-aarch64` for ARM) from [subcloak.com/apps/cloak-proxy](https://subcloak.com/apps/cloak-proxy), and make it executable:

   ```bash title="Terminal"
   chmod +x ~/Downloads/cloak-proxy-0.4.2-x86_64.AppImage
   ```

2. Run it. If WebKitGTK 6.0 isn't installed, it says so and shows the command for your distribution, for example:

   ```bash title="Terminal"
   sudo apt install libwebkitgtk-6.0-4 libsqlite3-0 libbrotli1 libnss3-tools      # Debian, Ubuntu
   sudo dnf install webkitgtk6.0 sqlite-libs libbrotli nss-tools                  # Fedora
   ```

3. Optional: add it to your app menu, and `cloak-proxy`, `cloakctl` and their man pages to `~/.local`, for you only and without a password:

   ```bash title="Terminal"
   ~/Downloads/cloak-proxy-0.4.2-x86_64.AppImage --integrate
   ```

   Keep the AppImage where it is afterwards, or run `--integrate` again after moving it. AppImageLauncher and Gear Lever also add it to the menu by themselves.

`cloakctl` is inside the AppImage: run `cloak-proxy-0.4.2-x86_64.AppImage cloakctl list`, or `cloakctl list` after `--integrate`. The MCP setup in **Settings › Advanced** points at the AppImage for you.

> **What the AppImage can't do:**
> Two things need the `.deb` or the RPM, because they change the system with small root-owned helpers that only the packages install: [DNS capture](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/#on-linux), and trusting the certificate in the system's store. The AppImage still trusts it in Chrome and Firefox, and gives you the one `sudo` command for the system store.

**Other distributions (portable folder)**

The portable folder runs without installing anything system-wide. It needs GTK 4, WebKitGTK 6.0, SQLite and Brotli from your distribution, and `certutil` to trust the certificate in browsers.

1. Install the libraries:

   ```bash title="Terminal"
   sudo dnf install webkitgtk6.0 sqlite-libs libbrotli nss-tools   # Fedora
   sudo apt install libwebkitgtk-6.0-4 libnss3-tools                # Debian, Ubuntu
   ```

2. Download `cloak-proxy-0.4.2-linux-x86_64.tar.gz` (or `-aarch64` for ARM) from [subcloak.com/apps/cloak-proxy](https://subcloak.com/apps/cloak-proxy) and unpack it where you keep apps:

   ```bash title="Terminal"
   tar -xzf ~/Downloads/cloak-proxy-0.4.2-linux-x86_64.tar.gz -C ~/Applications
   ```

3. Run it from the folder, or add it to your app menu and `~/.local/bin` (for you only, no password):

   ```bash title="Terminal"
   ~/Applications/cloak-proxy-0.4.2-linux-x86_64/cloak-proxy
   ~/Applications/cloak-proxy-0.4.2-linux-x86_64/install.sh
   ```

## 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](https://docs.subcloak.com/cloak-proxy/capture/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](https://docs.subcloak.com/cloak-proxy/capture/network-settings/).

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

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 (<kbd>Ctrl</kbd> <kbd>,</kbd>) 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.

> **Browsers need certutil:**
> Chrome and Firefox are changed with `certutil`, from the `libnss3-tools` package (`nss-tools` on Fedora). The `.deb` and the RPM install it unless you turned off recommended packages (weak dependencies, in dnf); if **Where it's trusted** says to install certutil, run `sudo apt install libnss3-tools` (`sudo dnf install nss-tools` on Fedora) and click **Install Everywhere** again.

## Send this computer's traffic through Cloak Proxy

**GNOME and KDE**

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**.

**Terminals**

Programs in a terminal read the `http_proxy` and `https_proxy` variables instead. To send one terminal through Cloak Proxy:

```bash title="Terminal"
eval "$(cloak-proxy --print-env)"
```

This also sets `NODE_EXTRA_CA_CERTS`, so Node.js trusts the certificate. Other terminals aren't affected. From 0.4.2 the lines also set `no_proxy` (`localhost,127.0.0.1,::1,*.local`), `NODE_USE_ENV_PROXY=1`, so Node.js 24's built-in `fetch` uses the proxy, and `REQUESTS_CA_BUNDLE`, which points Python `requests` at `ca-bundle.pem`: the system's root certificates plus Cloak Proxy's. (added in Cloak Proxy 0.4.2) **Device Setup…** has the same lines to copy, plus setups for Docker, Java, Flutter, Electron and Android.

**Other desktops**

On other desktops, set your browser's or app's HTTP and HTTPS proxy to `127.0.0.1` port `9090`, or start Chrome with `--proxy-server=http://127.0.0.1:9090`.

Then turn on [SSL Proxying](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/) for the hosts or apps you want to read, and the [Quick start](https://docs.subcloak.com/cloak-proxy/getting-started/quick-start/) carries on from there.

## Run it without a window

On a server, in a container or in CI, run the proxy headless and drive it with [`cloakctl`](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/) or the [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/):

```bash title="Terminal"
cloak-proxy --headless --install-ca --system-proxy
cloakctl list
```

It stops on <kbd>Ctrl</kbd> <kbd>C</kbd>, restoring the proxy setting. `cloak-proxy --help` lists every option, and `man cloak-proxy` and `man cloakctl` (added in Cloak Proxy 0.4.2) explain them. See [Headless and CI](https://docs.subcloak.com/cloak-proxy/automation/headless-and-ci/).

## Where Cloak Proxy keeps its files

- ~/.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
- ~/.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
  - Session/ captured traffic, kept across launches
  - Workspace/ the API client workspace
- ~/.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

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…** (added in Cloak Proxy 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.

(added in Cloak Proxy 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](https://docs.subcloak.com/cloak-proxy/reference/settings/#check-for-updates).

## 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** (added in Cloak Proxy 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](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/#on-linux) off, after one password prompt.

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

3. **Remove the package**:

   ```bash title="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.

   ```bash title="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

Since 0.4.1 the Linux beta has the Mac app's windows: the traffic list and inspector, the [debugging tools](https://docs.subcloak.com/cloak-proxy/tools/overview/), Insights and Privacy Map, the Doctor and [DNS capture](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/#on-linux), 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](https://docs.subcloak.com/cloak-proxy/sessions/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](https://docs.subcloak.com/cloak-proxy/capture/apps-that-ignore-the-proxy/#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](https://github.com/subcloak/cloak-proxy/issues) 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](https://github.com/subcloak/cloak-proxy/issues).
- **Packages:** `.deb`, RPM (added in Cloak Proxy 0.4.2), AppImage (added in Cloak Proxy 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](https://github.com/subcloak/cloak-proxy/issues) 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).

## Related

- [Install on macOS](https://docs.subcloak.com/cloak-proxy/getting-started/install/)
- [Quick start](https://docs.subcloak.com/cloak-proxy/getting-started/quick-start/)
- [Root certificate](https://docs.subcloak.com/cloak-proxy/capture/certificate/)
- [cloakctl](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/)