Title: Install Codemany on Linux · Codemany docs
URL: https://codemany.com/docs/get-started/linux
Description: Install Codemany on Linux with systemd: the desktop app on a Linux desktop, or one command or the apt repository on a server or VM, then finish setup in a browser.
All pages as Markdown: https://codemany.com/llms.txt

---

[Get started](https://codemany.com/docs#get-started)

# Install on Linux

Codemany runs on Linux too: the same daemon the Mac app bundles, with its web dashboard. Your workflows' Linux jobs then run on that machine instead of GitHub-hosted runners.

## What you need

- A 64-bit Linux machine (x86-64 or ARM64) with systemd and glibc. Ubuntu 22.04 and 24.04 LTS and Debian 12 or newer use the apt repository; Fedora and other glibc distros use the install script.
- A GitHub account that can add self-hosted runners to the repository or organization (repo admin, or org owner).

Setting up a mini PC or a cloud VM from scratch? Follow the [Linux server guide](https://codemany.com/docs/machines/linux-server), or let Codemany create a [cloud machine](https://codemany.com/docs/machines/cloud) for you.

## On a Linux desktop

Install the desktop app: it starts Codemany and walks you through setup, like on a Mac. Download the `.deb` from [the download page](https://codemany.com/download) (x86-64 or ARM64), or install it from the apt repository below with `sudo apt install codemany-desktop`.

The app finds the daemon, shows its dashboard with the controls unlocked, and offers **Install and start** when the service isn't running. Quitting the app leaves the runners running. Stock GNOME shows the tray icon only with the AppIndicator extension.

## On a server or VM

One line

One line (Ubuntu, Debian, Fedora and other glibc distros):

```
curl --proto '=https' --tlsv1.2 -fsSL https://codemany.com/install.sh | sh
```

It downloads the latest release for your CPU, checks its SHA-256, and installs `codemany` to `/usr/local/bin`. It uses `sudo` for that copy when the directory isn't yours, and once for `codemany system-setup`, which allows keep-awake. Set `CODEMANY_INSTALL_DIR=$HOME/.local/bin` to install without sudo.

apt (Debian, Ubuntu)

On Debian and Ubuntu, the apt repository keeps Codemany updated with `apt upgrade`. The key is installed only if its fingerprint is `92EA E8F4 E140 E71F E883 C291 DBC1 D871 7AE5 E521`:

```
curl --proto '=https' --tlsv1.2 -fsSLo codemany.gpg \
  https://codemany.com/download/linux/apt/codemany-archive-keyring.gpg
gpg --show-keys --with-colons codemany.gpg | grep -qx 'fpr:::::::::92EAE8F4E140E71FE883C291DBC1D8717AE5E521:' \
  && sudo install -m 644 codemany.gpg /usr/share/keyrings/codemany-archive-keyring.gpg \
  || echo "codemany.gpg is not Codemany's key: stop" >&2
echo "deb [signed-by=/usr/share/keyrings/codemany-archive-keyring.gpg] https://codemany.com/download/linux/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/codemany.list
sudo apt update && sudo apt install codemany      # and codemany-desktop on a desktop
```

## Finish setup

**In a browser.** Before there is a config, the service serves first-run setup instead of the dashboard. Print its link, and open it from any computer on your network:

```
codemany setup-link                      # http://<lan-ip>:8825/#code=…
```

Only someone with the link's one-time code can use it. Then sign in to GitHub, pick repositories or an organization, and start runners. Over an SSH tunnel, `codemany setup-link --port 18825` prints the link for your end.

**Or in a terminal**, as the user the jobs should run as (not root):

```
codemany setup --target your-org/your-repo --token-from-gh   # or --token-stdin
codemany install-service --config ~/.codemany/config.json
```

`install-service` writes a systemd user service, then enables and starts it. On a machine without a desktop it also turns on lingering, so Codemany keeps running after you log out and starts at boot.

## Use the runners

Runners register with the labels `self-hosted`, `Linux`, `X64` or `ARM64`, plus your pool labels (default `codemany`):

```
jobs:
  test:
    runs-on: [self-hosted, Linux, codemany]
```

Keep `Linux` in `runs-on` if you also run Codemany on a Mac. Without it, the same labels match both machines.

## What differs from macOS

|  | macOS | Linux |
| --- | --- | --- |
| Service | LaunchAgent | systemd user service |
| GitHub token | Keychain | vault file (mode 0600), or the desktop keyring with `codemany vault keyring` |
| Keep awake | power assertions | logind inhibitor lock (`sudo codemany system-setup`; the .deb and install.sh run it) |
| Isolation | host, user, vm (macOS VMs, at most 2) | host, user, vm (QEMU/KVM) |
| Updates | the app updates itself | `apt upgrade` or install.sh; the daemon restarts into the new version after busy runners finish |

## Check on it

`codemany doctor` checks the service, the dashboard, the licence, GitHub, the runners, KVM, Avahi and lingering, and exits non-zero on a failure. `codemany status` shows the runners, and `journalctl --user -u codemany` the log.

## Uninstall

```
codemany uninstall-service
sudo rm /usr/local/bin/codemany          # or: sudo apt remove codemany
rm -rf ~/.codemany ~/.local/share/com.codemany.cli
```

Runners that were online when you uninstalled are ephemeral: GitHub removes them after their job, or after a day offline.

[Previous Install on Mac](https://codemany.com/docs/get-started/mac)[Next Connect GitHub](https://codemany.com/docs/get-started/github)