|

Docs

HammerAI on Linux

Installation

Installing HammerAI on Linux is done in two parts; (1) downloading and installing the chosen file, either .deb, .flatpak or .rpm, and (2) installing Ollama and LLM's (models) through the app.

First download the correct package from https://www.hammerai.com/desktop and follow the appropriate guide below. If you are unsure which you should download, you can search your distro in a search-engine and check what it is based on and/or if it either comes with Flatpak, which can be done here: https://flatpak.org/setup.

Installing HammerAI on any Linux distro will ==not== provide automatic future updates and you will have to update the app manually, or add the GitHub to your distro's repo list (if possible).

Flatpak

Flatpak is the universal packaging format and is designed to work on most Linux distributions. However, for some distro's, this may require to install or enable flatpak. Fedora, Nobara and Mint are some that already has Flatpak installed by default. If you are unsure about your distro or want to use Flatpak, see https://flatpak.org/setup.

To install open the terminal in the location you downloaded or moved the .flatpak install file to. To do this you right click on an empty space in the folder and click "Open Terminal Here"

Then either (1) type or (2) copy-paste the following command:

(1) Copy-paste this command.

flatpak install io.atom.electron.HammerAI_stable_x86_64.flatpak

Or:

(2) Copy the downloaded .flatpak files whole name and paste it next to the following command;

flatpak install [filename]

Then run the command.

It may ask you if you want to install the app. Type "y" for yes and "n" for no and press enter.

HammerAI should now be installed like most apps.

Debian

This is primarily meant for Debian based distros like Ubuntu. Open the terminal in the location you downloaded or moved the HammerAI_[version]_amd64.deb install file to. To do this you right click on an empty space in the folder and click "Open Terminal Here".

Type or copy-paste the following command and add the whole name of the HammerAI deb file. You can right click the install file and copy the whole file name, including the ".deb" part and paste it into your terminal.

sudo apt install ./[filename]

It should look something like this before you run the command:

sudo apt install ./hammerai_0.0.228_amd64.deb

Run the command. HammerAI should now be installed like most apps.

Installing Ollama and LLMs

The HammerAI app makes this very easy. If the app does not detect any Ollama versions or LLM's installed in it's directory, it will prompt you to install one when opening the app. You can let it choose the Ollama and a LLM, or you can choose to install it manually in the HammerAI app. If you choose to install Ollama manually, go to Models in the sidebar -> Ollama and choose an Ollama version. 

For AMD GPU users, it is required to download the Linux AMD GPU Support (ROCm Package)!

If you download more than one Ollama version, then make sure to click the Star symbol on the far right side of the Ollama version to set it as the chosen version.

Common Installation Issues

  • If you're having problems with the .flatpak file. Remember to check if your distro has it installed, if you need to enable it or install other packages as well. See: https://flatpak.org/setup.
  • error: Application requires the runtime org.freedesktop.Platform/x86_64/19.08: this is an error showing that you did not install Flatpak correctly and is not linked to the HammerAI flatpak file.
  • No emojis showing up: you may be missing emojis when installing the Flatpak on Arch. Fix this by by running `noto-fonts-emoji`.
  • Slow responses or responses that stutter: make sure the LLM model you're using is appropriate for you GPU. A model that needs more VRAM than the GPU has is often the cause.
  • Slow responses or very stuttery responses on AMD GPU: make sure ROCm is supported and installed on your distro. AMD's 9000 series cards is ONLY supported on Windows and Ubuntu 24.04.2 and 22.04.5, RHEL 9.6 and RHEL 9.4 as of last ROCm update (18-08-2025). This means that if you are using any distro that either is not Ubuntu or does not include the latest update of RHEL, then ROCm is not officially supported nor installed by default. See https://rocm.docs.amd.com/en/latest for the latest information about ROCm and check relevant distro communities for information about ROCm for the distro you are using. To install ROCm on Ubuntu, follow AMD's guide: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html. Alternatively, you can post the link into ChatGPT or Grok and tell it to help you install ROCm by following the guide provided. Note that while GPT and Grok can be useful, they does not necessarily know that a distro is not supported at all, but will still act as it is. Be wary.
  • Check out the HammerAI Discord if you have a problem that is not listed here.

Updating

To check if there is a new version you can check Release Notes in the bottom left corner of the HammerAI app or you can go to https://www.hammerai.com/release-notes. Updating the HammerAI app is identical to the way you install it.

  • Go to https://www.hammerai.com/desktop. Download the file you originally used to install it with and install it just as is you did when first installing the app. That means that if you installed the Debian file, then you will want to use the new Debian install file to update.
  • If you already have the Debian version, and install the flatpak version, then you will end up with two separate versions of HammerAI.
  • Your characters, chats, images, models etc. will not be deleted when you update the app like this. However, if you are worried about losing local characters, it is wise to keep a backup of the .json files in a separate folder or drive.

File Location

The folders and files you might be interested in backing up and/or accessing: Models (where LLM models are stored), images, stories, image models and generated-images, background images.json, characters.json, config.json, conversation.json, imageGeneration.json, personas.json, stories.json.

  • Flatpak users on Fedora based distros can find them under: `/home/[user]/.var/app/io.atom.electron.HammerAI/config/HammerAI/`
  • Flatpak users on other distro's want to look for the same file name as the one above; "io.atom.electron.HammerAI"
  • .deb users on Ubuntu can find them under: `/home/[user]/.config/HammerAI`