Write a Manifest

A manifest is a YAML file listing commands you want to run and the containers that provide them.

Workflow

1. Create the manifest file

Create a YAML file with a manifest key containing a name, version, and commands list. Save it as a .yaml file anywhere on disk — for example, ~/my-manifest.yaml. The name field should include a namespace (e.g., myorg/my-tools). If you omit the namespace, bulker uses default_namespace from your config.

manifest:
  name: my-tools
  version: 1.0.0
  commands:
  - command: cowsay
    docker_image: nsheff/cowsay
    docker_command: cowsay
  - command: fortune
    docker_image: nsheff/fortune
    docker_command: fortune

Each entry in commands defines one executable that bulker will wrap in a container.

2. Install the manifest as a crate

Use bulker crate install with the path to your file:

bulker crate install ~/my-manifest.yaml

This caches the manifest locally. You do not need a registry or network access for locally authored manifests.

3. Activate the crate

Activate the crate using the local file path:

bulker activate ~/my-manifest.yaml

Or, after installing, activate by its cached registry path. The cached path comes from the manifest’s name field — since name: my-tools has no namespace, it defaults to the default_namespace from your config (usually bulker):

bulker activate bulker/my-tools

To control the cached identity explicitly, use --name:

bulker crate install --name myorg/my-tools:1.0.0 ~/my-manifest.yaml
bulker activate myorg/my-tools:1.0.0

This creates shimlinks for each command in the manifest and puts them on your PATH for the current shell session. See Shell Integration if you have not yet configured your shell.

4. Verify the commands are available

Confirm the crate is active and its commands are accessible:

echo $BULKERCRATE
cowsay "It works"

$BULKERCRATE should contain bulker/my-tools:default. Each command listed in the manifest should now run via its container image.

You can also inspect the crate to see all its commands:

bulker crate inspect bulker/my-tools

Field reference

For a complete reference of all available command fields, see Manifest Format.

Below are the most common fields used in basic manifests:

command

The executable name — what the user types to run the command (e.g., cowsay).

docker_image

The full Docker image reference. Include a tag for a specific version, for example nsheff/cowsay:1.2.

docker_command

The command to run inside the container. Defaults to the command value. Use this when the container’s internal command name differs from the user-facing name.

docker_args

Additional flags passed to docker run. Bulker auto-detects TTY and always keeps stdin open, so you generally don’t need -i or -t here. For Apptainer, use apptainer_args instead.

Manifests and Apptainer

The examples above are Docker-centric, but manifests work with either Docker or Apptainer. Bulker manifests point at Docker images. When using Apptainer, bulker converts these into Apptainer images automatically — the manifest stays the same.

The docker_args field is only used with Docker. There is an analogous apptainer_args field if you need Apptainer-specific flags. Similarly, apptainer_command lets you override the command for Apptainer if needed, though this is rarely necessary.

All example manifests work identically with either Docker or Apptainer. Bulker considers the Docker image the ground truth, and Apptainer builds from that image.

Templates

Bulker uses Tera templates for generating container run commands. The default templates handle most use cases. For container user and network settings, see Container User and Network Settings.

Examples

Check out these examples at hub.bulker.io:

Demos:

• demo manifest — Cowsay and fortune example
• pi manifest — Example of the pi command

Real-life manifests:

• personal manifest — Everyday computing tools
• peppro pipeline manifest — Pipeline manifest for PEPPRO