HPM

01 OVERVIEW #

Each package is a plain git repository with an info.hk manifest and a contents/ directory, or a build.toml describing how to obtain the binary. No .deb archives — just git.

Every package runs in an isolated environment using Linux namespaces + Landlock. GUI apps get X11/Wayland/D-Bus access and are registered in the system app menu automatically.

Install flow

# 1. Central index
{ "mypkg": { "repo": "https://github.com/user/mypkg" } }

# 2. hpm install mypkg
  → fetch repo.json              (HTTP, no clone)
  → clone git repo
  → checkout latest semver tag
  → read info.hk
  → install apt deps
  → run build.toml / build.info
  → copy contents/ → store
  → install .desktop + icon      (GUI apps)
  → create /usr/bin wrapper

# 3. Running
$ mypkg → hpm run mypkg → sandbox → exec

02 QUICKSTART #

sudo hpm refresh          # update package index
hpm search editor         # find packages
hpm info hedit            # show package details
sudo hpm install hedit    # install
hedit myfile.txt          # use it
sudo hpm update           # update all packages
sudo hpm remove hedit     # remove

03 COMMAND REFERENCE #

Package Commands

Query Commands

Maintenance Commands

04 VERSION MANAGEMENT #

hpm reads versions from git tags in the format v1.2.3 or 1.2.3. Multiple versions can be installed side by side.

sudo hpm install hedit@1.9.0   # install specific version alongside current
sudo hpm switch hedit 1.9.0    # switch active version
sudo hpm pin hedit 1.9.0       # pin — prevents automatic updates
sudo hpm unpin hedit            # unpin when ready to update
sudo hpm remove hedit@1.9.0    # remove specific version only

05 SANDBOX #

hpm automatically selects the right isolation level. No manual configuration required — the sandbox is transparent to the user.

Sandbox modes

Sandbox options in info.hk

[sandbox]
-> network   => false   # allow network access
-> gui       => true    # bind X11/Wayland/D-Bus/PulseAudio/PipeWire
-> full_gui  => false   # gui + /dev/shm (Electron/Chromium apps)
-> dev       => false   # expose /dev devices
-> disabled  => false   # disable sandbox entirely
-> filesystem => {}     # extra host paths to bind-mount

What Landlock protects

06 REPOSITORY LAYOUT #

07 INFO.HK MANIFEST #

Complete manifest reference

[metadata]
-> name    => my-package
-> version => 1.0.0
-> authors => Your Name
-> license => MIT
-> gui     => false               # shorthand for sandbox.gui = true
-> bins.my-binary => ""           # each binary gets a /usr/bin wrapper

[description]
-> summary => One-line shown in hpm search
-> long    => Longer description shown in hpm info

[sandbox]
-> network   => false
-> gui       => false
-> full_gui  => false
-> dev       => false
-> disabled  => false
-> filesystem => {}

[build]
-> commands => {}
-> deb_deps => {}

[runtime]
-> deb_deps => {}

[specs]
-> dependencies.other-pkg => ">=1.0"

[desktop]
-> display_name => My Application
-> icon         => icons/my-package.png
-> categories   => Utility;GTK;
-> comment      => Short description for the app menu
-> mime_types   => text/plain;
-> keywords     => tool;utility;
-> desktop_file => my-package.desktop

08 BUILD.TOML #

When absent, hpm copies contents/ directly. Add build.toml when the binary needs downloading or compiling.

type = "download"

type         = "download"
url          = "https://github.com/user/repo/releases/download/v{version}/bin-linux-x86_64"
install_path = "bin/mybinary"
runtime_deps = ["libssl3"]

# From a tar.gz archive:
type             = "download"
url              = "https://example.com/v{version}/tool.tar.gz"
binary_path      = "tool/bin/tool"
strip_components = 0
install_path     = "bin/tool"

type = "build"

type         = "build"
commands     = ["cargo build --release"]
output       = "target/release/mytool"
install_path = "bin/mytool"
build_deps   = ["build-essential"]
runtime_deps = ["libssl3"]

[env]
CARGO_PROFILE_RELEASE_LTO = "true"

09 GUI APPLICATIONS #

When gui = true or sandbox.gui = true, hpm automatically:

• Runs in compat mode — shares X11/Wayland/D-Bus with the host
• Installs a .desktop file to /usr/share/applications/
• Installs the icon to hicolor and pixmaps
• Runs update-desktop-database and gtk-update-icon-cache

GUI info.hk example

[metadata]
-> name    => myapp
-> version => 1.0.0
-> gui     => true
-> bins.myapp => ""

[sandbox]
-> gui      => true
-> network  => false

[runtime]
-> deb_deps => { libgtk-3-0 => "" }

[desktop]
-> display_name => My App
-> icon         => icons/myapp.png
-> categories   => Graphics;Viewer;

Electron / Chromium apps

[sandbox]
-> full_gui => true    # adds /dev/shm for shared memory
-> network  => true    # if the app needs internet access

10 PUBLISHING #

1. Create the repository

mkdir my-package && cd my-package && git init
mkdir -p contents/bin
cp /path/to/binary contents/bin/my-package
chmod +x contents/bin/my-package
# create info.hk (see section 07 for full reference)
git add . && git commit -m "initial release"
git tag v1.0.0 && git push origin main --tags

2. Add to repo.json

{
  "packages": {
    "my-package": {
      "repo": "https://github.com/yourname/my-package"
    }
  }
}

3. Submit a pull request

Open a PR to HackerOS-Package-Manager ↗ adding your entry to repo/repo.json.

11 REPO.JSON #

{
  "packages": {
    "hello-hpm": {
      "repo": "https://github.com/HackerOS-Linux-System/hpm-example-repo"
    },
    "hedit": {
      "repo": "https://github.com/hackerOS/hedit",
      "versions": ["1.0.0", "2.0.0", "2.1.0"]
    }
  }
}

12 STORE LAYOUT #

13 HPM VS AUR VS PPA #

14 HK FORMAT #

The info.hk manifest uses the HK format — HackerOS's native configuration language. Readable, hierarchical, with built-in interpolation, strong typing and precise error messages.