Harbor

A lightweight open-source system that helps developers distribute code and users to download the most compatible by packaging projects into portable Harbor containers with metadata, compatibility checks, integrity hashes, and optional encrypted exports.

---

What is Harbor?

Harbor helps developers distribute code and users to download the most compatible

It scans the project tree, detects known stacks, writes metadata, copies code into a clean Code/ area, stores root files in Info/, creates recursive SHA-256 integrity hashes, compresses the result as a .harb file, and can also create a password-encrypted .bcb export.

Then, the dev can make an HarborSpecs folder with the sources and a HarborMap.yaml that tells the system where to find the right source for the system.

After this, anyone with the harbor CLI can download the most compatible (or other) version in the default or other branch.

Harbor is not Docker. It is closer to a project packager, verifier, and compatibility assistant.

Features

• wrapper: create a Harbor container from a project directory.
• inflate: extract a .harb container.
• restore: decrypt and extract an encrypted .bcb export.
• verify: validate the recursive .hash.txt integrity tree.
• uphash: recalculate container hashes after intentional changes.
• compatibility: check the current OS, architecture, and runtimes against container metadata.
• .harbignore support with gitwildmatch-style rules.
• run: runs an .harbinstall, a installing script.
• install: Install a project from GitHub.
• Stack detection for Python, Node.js, Go, Rust, Java, Docker, React, Vue, and more.

Install

Install from PyPI (recommended):

pipx install byharbor

Or install from source:

git clone https://github.com/kauanmezavila/harbor.git
cd Harbor
pip install .

(Note: we use pyproject.toml to habilite the global command)

Usage

harbor <command> <args>

Commands:
  wrapper <path>                            Create a Harbor container
  inflate <file.harb> [--out <directory>]   Extract a .harb container
  restore <file.bcb> --password <password>  Restore an encrypted .bcb export
  verify <path>                             Verify container hashes
  uphash <path>                             Recalculate container hashes
  compatibility <path>                      Check container compatibility
  run <path>                                Runs the .harbinstall
  install <username/repo@version> <args>    Install a project from GitHub

Examples:

harbor wrapper MyApp
harbor inflate "MyApp-Any-Any-[HARBOR].harb" --out ./restored
harbor restore "MyApp-Any-Any-[HARBOR]_encrypted.bcb" --password "secret" --out ./restored
harbor verify "MyApp-Any-Any-[HARBOR]"
harbor compatibility "MyApp-Any-Any-[HARBOR]"
harbor run "MyApp-Any-Any-[HARBOR]"
harbor install linus/myapp@latest --branch master

Note: for security reasons, run will may only run .harbinstall when runned in the project root dir

Container Output

For a project named MyApp, Harbor creates:

MyApp-Any-Any-[HARBOR]/
├── Code/             copied project files
├── Info/             header.json, tree.json, .harbignore, .harbinstall
└── .hash.txt         root integrity hash

It also creates:

MyApp-Any-Any-[HARBOR].harb

If encryption is enabled, Harbor creates:

MyApp-Any-Any-[HARBOR]_encrypted.bcb

The Any-Any part changes when you set specific architectures or operating systems during wrapping.

Ignore Rules

Add a .harbignore file to the project root to exclude files or folders from the container. Just like an .gitignore

Example:

.git/
__pycache__/
node_modules/
*.log

Stack editor

In the new stack editor we now support more operators like:

• >=
• <=
• !=
• ==
• >
• <
• =

And limiters like:

• python>=3.12, <3.14

But, REMENBER: weird sintax logics like python>3.12, <3.11 probaly will break the system, so please, use your brain while making this :).

HarborSpecs

In 1.3.0 we added the HarborSpecs, a folder in your project root directory. In this folder you will put the OS folder, after the version.

An example:

.
├── ContainerStuff
│   ├── access.py
│   ├── compatibility.py
│   ├── dirtrain.py
│   ├── header.py
│   ├── install.py
│   ├── Obsidian
│   │   └── BaseSystem
│   │       ├── crypto.py
│   │       ├── hasher.py
│   │       └── main.py
│   ├── runinstall.py
│   ├── stack.py
│   ├── wrapper.py
│   └── WrapperStuff
│       ├── containerflux.py
│       ├── hashflux.py
│       └── verifyflux.py
|
├── HarborSpecs                                                <--- Here is HarborSpecs folder
|   ├── HarborMap.yaml                                         <--- Here is the HarborMap file
│   ├── any                                                    <--- In "Any" you put the code that run in ANY OS
│   │   ├── v1.1                                               <--- The version
│   │   │   └── HarborBeacon-Any-Any-[HARBOR].harb             <--- The code source
│   │   └── v1.2
│   │       └── HarborBeacon-Any-Any-[HARBOR].harb
│   ├── linux
│   │   ├── v1.0
│   │   │   └── HarborBeacon-x86_64-linux-[HARBOR].harb
│   │   ├── v1.1
│   │   │   └── HarborBeacon-arm64-linux-[HARBOR].harb
│   │   └── v1.2
│   │       └── HarborBeacon-x86_64-arm64-linux-[HARBOR].harb
│   ├── mac
│   │   └── v1.2
│   │       └── HarborBeacon-arm64-macos-[HARBOR].harb
│   └── windows
│       └── v1.1
│           └── HarborBeacon-x86_64-windows-[HARBOR].harb
├── imgs
│   ├── Harbor2.png
│   ├── HarborBanner.png
│   └── Harbor.png
├── main.py
├── OfficeStuff
├── pyproject.toml
├── README.md
├── README.pt-BR.md
├── requirements.txt
└── UPDATES.md

The only thing here that you actually needs to follow is the folder HarborSpecs be in the root directory and after, the sources

HarborMap.yaml

This is the HEART of harbor install, in there you can configure some things that will guide the system.

What you NEED to follow to construct:

• Names like:
  • project
  • description
  • variants
  • type
  • path
  • version
  • os
  • architecture
  • runtime
• Indentation

An example, if you follow it, your users will have an amazing experience:

project: HarborBeacon # The project name
description: Same fictional project packaged as HarborSpecs variants by OS, architecture, and version. # Project description

variants:
  - type: .harb                                            # IMPORTANT: tell how harbor will treat the variant, in this case like a .harb
    path: any/v1.1/HarborBeacon-Any-Any-[HARBOR].harb      # IMPORTANT: the location of the .harb
    version: 1.1.0                                         # Important: good for version control
    os: Any                                                # Important: for compatibility verification
    architecture: Any                                      # Important: for compatibility verification
    runtime: python>=3.12                                  # important: for compatibility verification, but the container header can make this too
                                                           # URL VARIANT BELOW
  - type: .harb
    path: any/v1.2/HarborBeacon-Any-Any-[HARBOR].harb
    version: 1.2.0
    os: Any
    architecture: Any
    runtime: python>=3.12

  - type: .harb
    path: linux/v1.0/HarborBeacon-x86_64-linux-[HARBOR].harb
    version: 1.0.0
    os: linux
    architecture: x86_64
    runtime: python>=3.12

  - type: .harb
    path: linux/v1.1/HarborBeacon-arm64-linux-[HARBOR].harb
    version: 1.1.0
    os: linux
    architecture: arm64
    runtime: python>=3.12

  - type: .harb
    path: linux/v1.2/HarborBeacon-x86_64-arm64-linux-[HARBOR].harb
    version: 1.2.0
    os: linux
    architecture: x86_64, arm64
    runtime: python>=3.12

  - type: .harb
    path: mac/v1.2/HarborBeacon-arm64-macos-[HARBOR].harb
    version: 1.2.0
    os: macos
    architecture: arm64
    runtime: python>=3.12

  - type: .harb
    path: windows/v1.1/HarborBeacon-x86_64-windows-[HARBOR].harb
    version: 1.1.0
    os: windows
    architecture: x86_64
    runtime: python>=3.12

  - type: url                                                   # IMPORTANT: tell to harbor how to treat this variant
    url: https://example.invalid/harborbeacon/install.sh        # IMPORTANT: where the installation file is
    command: echo "[HARBOR] simulated install for linux x86_64" # IMPORTANT: how to run the installation file
    version: 2.0.0                                              # Important: for version control
    os: linux                                                   # Important: for compatibility verification
    architecture: x86_64                                        # Important: for compatibility verification
    runtime: python>=3.12                                       # important: for compatibility vericication

  - type: url
    url: https://example.invalid/harborbeacon/install.ps1
    command: echo "[HARBOR] simulated install for windows x86_64"
    version: 2.0.0
    os: windows
    architecture: x86_64
    runtime: python>=3.12

  - type: url
    url: https://example.invalid/harborbeacon/install.sh
    command: echo "[HARBOR] simulated install for macos arm64"
    version: 2.0.0
    os: macos
    architecture: arm64
    runtime: python>=3.12

If you specify the path or the url good, you can organize HarborSpecs in a lots of ways (For real, ANY way is valid, the only important thing is the HarborMap.yaml having all the nescessary infos)

.harbinstall

In 1.2.1 we now have the amazing .harbinstall: an file that helps the installation using subprocess.

To be able to run you need:

• 1: Create the installation file just like an .sh/.bat (Remebers it runs LINE by LINE)
• 2: Add one of the index hrb:> and HARB-IMG commands if you want!:

shell-mode  : run commands with the shell or subprocess list [Starts on 'True']
output      : capture the output [Starts on 'False']
err-break   : determinates if the HARB-IMG needs to stop or not if an error occurs [Starts on 'False']
usr-log     : shows the logs of HARB-IMG for the user [Starts on 'True']

Note: if you not write an .harbinstall on the root dir, Harbo will push an empty one on the container Info folder

Security Note

Encrypted .bcb exports use AES-GCM through the cryptography package. Use them for packaging and controlled sharing, not as a replacement for a full audited production security process.

Project Structure

.
├── ContainerStuff
│   ├── access.py
│   ├── compatibility.py
│   ├── dirtrain.py
│   ├── header.py
│   ├── install.py
│   ├── Obsidian
│   │   └── BaseSystem
│   │       ├── crypto.py
│   │       ├── hasher.py
│   │       └── main.py
│   ├── runinstall.py
│   ├── stack.py
│   ├── wrapper.py
│   └── WrapperStuff
│       ├── containerflux.py
│       ├── hashflux.py
│       └── verifyflux.py
├── Dumpster
│   ├── main-cli.py
│   └── README.md
├── HarborSpecs
│   ├── any
│   │   ├── v1.1
│   │   │   └── HarborBeacon-Any-Any-[HARBOR].harb
│   │   └── v1.2
│   │       └── HarborBeacon-Any-Any-[HARBOR].harb
│   ├── HarborMap.yaml
│   ├── linux
│   │   ├── v1.0
│   │   │   └── HarborBeacon-x86_64-linux-[HARBOR].harb
│   │   ├── v1.1
│   │   │   └── HarborBeacon-arm64-linux-[HARBOR].harb
│   │   └── v1.2
│   │       └── HarborBeacon-x86_64-arm64-linux-[HARBOR].harb
│   ├── mac
│   │   └── v1.2
│   │       └── HarborBeacon-arm64-macos-[HARBOR].harb
│   └── windows
│       └── v1.1
│           └── HarborBeacon-x86_64-windows-[HARBOR].harb
├── imgs
│   ├── Harbor2.png
│   ├── HarborBanner.png
│   └── Harbor.png
├── main.py
├── pyproject.toml
├── README.md
├── README.pt-BR.md
├── requirements.txt
└── UPDATES.md

License

MIT License.

Built and maintained by ByKurebo.