Skip to main content

OCI Labels Reference

Headjack uses OCI image labels to configure container runtime behavior. When building custom images, you can use these labels to control how Headjack runs your containers.

Overview​

Labels are key-value pairs embedded in container images. Headjack reads these labels at runtime to determine how to configure the container.

Labels are set in Dockerfiles using the LABEL instruction:

LABEL io.headjack.init="/lib/systemd/systemd"

Available Labels​

io.headjack.init​

Specifies the command to run as PID 1 inside the container.

PropertyValue
Keyio.headjack.init
Value typeString (command path)
Defaultsleep infinity

Description​

By default, Headjack runs sleep infinity as PID 1 to keep the container alive while sessions run in the background. This label overrides that default with a custom init command.

Example​

# Use systemd as init
LABEL io.headjack.init="/lib/systemd/systemd"

# Use a custom init script
LABEL io.headjack.init="/usr/local/bin/my-init.sh"

Usage in Official Images​

ImageValue
baseNot set (uses default sleep infinity)
systemd/lib/systemd/systemd
dindInherited from systemd

io.headjack.podman.flags​

Specifies additional flags to pass to Podman when running the container.

PropertyValue
Keyio.headjack.podman.flags
Value typeString (space-separated key=value pairs)
DefaultNone

Description​

This label allows images to specify Podman-specific runtime flags that are required for correct operation. Headjack parses the value and applies the flags when creating the container.

Format​

The value is a space-separated list of key=value pairs:

key1=value1 key2=value2

Supported Flags​

FlagDescription
systemd=alwaysEnable systemd container mode
systemd=trueEnable systemd container mode if systemd is detected

Example​

# Enable systemd mode
LABEL io.headjack.podman.flags="systemd=always"

# Multiple flags
LABEL io.headjack.podman.flags="systemd=always privileged=true"

Usage in Official Images​

ImageValue
baseNot set
systemdsystemd=always
dindInherited from systemd

io.headjack.apple.flags​

Reserved for Apple Containerization Framework-specific flags.

PropertyValue
Keyio.headjack.apple.flags
Value typeString (space-separated key=value pairs)
DefaultNone

Description​

This label is reserved for specifying flags specific to the Apple Containerization Framework. It follows the same format as io.headjack.podman.flags.

Example​

LABEL io.headjack.apple.flags="rosetta=true"

Usage in Official Images​

Not currently used in official images.

Building Custom Images​

When building custom images that extend the official Headjack images, labels are not automatically inherited. You must explicitly set any labels you need.

Extending the Base Image​

FROM ghcr.io/gilmanlab/headjack:base

# Add custom software
RUN apt-get update && apt-get install -y postgresql

# No labels needed - base image uses default init

Extending the Systemd Image​

FROM ghcr.io/gilmanlab/headjack:systemd

# Add custom systemd service
COPY myservice.service /etc/systemd/system/
RUN systemctl enable myservice

# Re-declare labels (not inherited)
LABEL io.headjack.init="/lib/systemd/systemd"
LABEL io.headjack.podman.flags="systemd=always"

Creating a Custom Init Image​

FROM ghcr.io/gilmanlab/headjack:base

# Add custom init script
COPY init.sh /usr/local/bin/init.sh
RUN chmod +x /usr/local/bin/init.sh

# Configure Headjack to use custom init
LABEL io.headjack.init="/usr/local/bin/init.sh"

Label Inspection​

You can inspect image labels using Docker or Podman:

# Using Docker
docker inspect ghcr.io/gilmanlab/headjack:systemd --format='{{json .Config.Labels}}' | jq

# Using Podman
podman inspect ghcr.io/gilmanlab/headjack:systemd --format='{{json .Config.Labels}}' | jq

Example output:

{
  "io.headjack.init": "/lib/systemd/systemd",
  "io.headjack.podman.flags": "systemd=always"
}

See Also​