honeycombDocs
Honeycomb 0.6.1 and IAM 5 are live

The services have switched to IAM 5. Installer publication and the latest popup improvements are being verified. Read the migration guide →

Publish an app / HONEYCOMB

Package format

The honeycomb.yaml schema, target layout, and archive safety rules.

One archive, six native targets#

A Honeycomb release is a gzip-compressed tar archive with honeycomb.yaml at its root and platform files below targets/. Do not wrap these in an extra parent directory.

my-app/
  honeycomb.yaml
  targets/
    linux-x86_64/my-app
    linux-aarch64/my-app
    windows-x86_64/my-app.exe
    windows-aarch64/my-app.exe
    macos-x86_64/my-app
    macos-aarch64/my-app

Complete manifest#

format_version: 1
# app_id: my-app  # Optional
version: 1.0.0
bin:
  my-app: main
targets:
  linux-x86_64:
    root: targets/linux-x86_64
    executables:
      main: my-app
  linux-aarch64:
    root: targets/linux-aarch64
    executables:
      main: my-app
  windows-x86_64:
    root: targets/windows-x86_64
    executables:
      main: my-app.exe
  windows-aarch64:
    root: targets/windows-aarch64
    executables:
      main: my-app.exe
  macos-x86_64:
    root: targets/macos-x86_64
    executables:
      main: my-app
  macos-aarch64:
    root: targets/macos-aarch64
    executables:
      main: my-app

Download this manifest. Replace the command and payload names with your own.

Field reference#

Field Meaning
format_version Must be 1.
app_id Optional permanent app identity. If present, it must match the application selected for upload or installation. If omitted, the selected application and its release record provide the identity.
version Semantic release version, for example 1.0.0.
bin Public command name → logical executable identifier. At least one command is required.
targets Target ID → root directory and executable mappings.
targets.<id>.root Safe relative directory below targets/; target roots cannot overlap.
targets.<id>.executables Logical executable identifier → path relative to that target root.
targets.<id>.install_script Optional. Path relative to that target root of a script run once after honeycomb install completes on that target. See Install script.

For example, bin: { my-app: main } exposes my-app on PATH and resolves main separately for each platform. Multiple commands may map to logical executables. Unknown manifest fields are rejected.

Supported targets#

Required: linux-x86_64, linux-aarch64, windows-x86_64, windows-aarch64, macos-x86_64, macos-aarch64.

Optional: linux-i686, linux-armv7hf, windows-i686. Other target identifiers are rejected. These are Honeycomb target names, not Rust target triples.

Limits and validation#

Limit Value
Compressed archive 512 MiB
Total expanded files 2 GiB
Archive entries 50,000
Manifest size 1 MiB

Links (symbolic or hard), special files, traversal, absolute paths, duplicate/case-colliding paths, and unexpected top-level entries are rejected. Use portable file names; Windows reserved names and unsafe characters are forbidden. Non-Windows executables must have an executable permission bit when validated on Unix.

chmod +x my-app/targets/linux-*/my-app my-app/targets/macos-*/my-app
honeycomb validate my-app
honeycomb pack my-app --output my-app-1.0.0.tar.gz

Package runtime assets inside the appropriate target root. Do not include credentials or source working trees. The installer selects a target, validates and stages its payload, activates owned commands, records the installation, and then runs that target's install script if the manifest declares one.

Without --output, the archive is named <app-handle>-<version>.tar.gz when app_id is set. Otherwise Honeycomb uses the alphabetically first command in bin, for example my-app-1.0.0.tar.gz. The archive bytes are preserved during upload.

Install script#

Each target can declare an install_script, a path relative to its root. Honeycomb runs it once honeycomb install has completed on that platform, so every command is already active and recorded when it starts.

targets:
  linux-x86_64:
    root: targets/linux-x86_64
    executables:
      main: my-app
    install_script: setup.sh
  windows-x86_64:
    root: targets/windows-x86_64
    executables:
      main: my-app.exe
    install_script: setup.ps1
Platform How it runs
Linux, macOS Executed directly. Needs a shebang such as #!/bin/sh and the executable bit.
Windows Chosen by extension: .cmd and .bat run through cmd.exe, .ps1 through powershell.exe -ExecutionPolicy Bypass, .exe directly. Other extensions are rejected.

The script runs in the installed package directory with these environment variables:

Variable Value
HONEYCOMB_APP_ID The installed application.
HONEYCOMB_APP_VERSION The installed release version.
HONEYCOMB_RELEASE_CHANNEL prod or dev.
HONEYCOMB_PACKAGE_DIR The installed package directory.
HONEYCOMB_BIN_DIR Honeycomb's command directory for this context.

Its output goes to stderr, so --json output on stdout stays parseable. It can prompt only when a person is at a terminal; otherwise its stdin is empty, so an unattended install cannot hang waiting for an answer.

The script runs when honeycomb install installs a release. It does not run on honeycomb update, on automatic updates, or when the requested release is already installed. Write it so a second run is harmless: reinstalling after an uninstall, or switching channels with honeycomb install, runs it again.

If the script exits non-zero, the installation is kept and honeycomb install exits with status 1, naming the script and its exit code. honeycomb install <app> --skip-install-script installs without running it. Both appear in the JSON result as install_script.status: succeeded, failed or skipped.