Host Commands

Host commands let you include native host binaries in a crate alongside containerized commands. Unlike regular commands (which run inside containers), host_commands are resolved from the host system at activation time.

Why host commands exist

Some tools don’t belong in containers:

• Shell utilities needed by scripts or the user (id, which, ls)
• Scripting languages that orchestrate containers (python3, perl)
• Version control and build tools (git, make)

Note

The container engine (Docker/Apptainer) does not need to be listed as a host command. Bulker auto-detects its absolute path and invokes it directly, even in strict mode. See Strict Environments for details.

In normal (non-strict) mode, these are already on your PATH, so host commands don’t create any shimlink directory entries. In strict mode, the PATH is replaced entirely — host commands create symlinks in the shimlink directory that point directly to the resolved host binary path.

Adding host commands to a manifest

List host binary names under host_commands:

manifest:
  name: my-pipeline
  host_commands:
    - python3
    - perl
    - git
  commands:
    - command: samtools
      docker_image: quay.io/biocontainers/samtools:1.9--h91753b0_8

Each name is resolved to an absolute path via which at activation time. In strict mode, a symlink is created in the shimlink directory pointing directly to the resolved host binary. In non-strict mode, no shimlink entry is created — the command is found naturally on the preserved PATH.

How they differ from regular commands

	Regular commands	Host commands
Runs in	Container	Host
Shimlink entry	Symlink to bulker binary (busybox dispatch)	Symlink to resolved host binary (strict mode only) / No entry (non-strict)
Needs Docker image	Yes	No
Needed in normal mode	Yes	Optional (already on PATH)
Needed in strict mode	Yes	Yes (only way to access host binaries)

Virtual environment compatibility

Host commands work correctly with Python virtual environments and other environment managers. In strict mode, the symlinks point directly to the resolved host binary, so argv[0] resolves to the real binary path. CPython’s venv detection sees the correct path and activates the virtual environment properly. This works regardless of the order in which the venv and bulker crate are activated.

Pre-built base crates

Rather than listing host commands in every manifest, import a base crate that provides them:

manifest:
  name: my-pipeline
  imports:
    - bulker/alpine
  commands:
    - command: samtools
      docker_image: quay.io/biocontainers/samtools:1.9--h91753b0_8

See Import Crates for the complete list of available base crates.

When to use host commands vs containers

Use host commands when the tool:

• Is a system utility needed by other tools or the user (e.g., id, which, ls)
• Orchestrates other commands and needs to see the shimlink directory
• Is a scripting language or build tool that shouldn’t run in a container

Use regular (containerized) commands when the tool:

• Has specific version requirements
• Should be reproducible across machines
• Has complex dependencies you don’t want to install on the host