Skip to content
bulker
Docs

Tutorial

How bulker works (30-second version)

Section titled “How bulker works (30-second version)”

A crate is a list of command-name-to-container-image mappings, defined in a YAML manifest. When you activate a crate, bulker creates a symlink (a “shimlink”) for each command pointing to the bulker binary, and adds them to your PATH. When you run a shimlink, bulker reads argv[0] to identify the command and launches the matching container behind the scenes. You never type docker run — you just type the command name.

Activate a crate

Section titled “Activate a crate”

This tutorial assumes you’ve installed bulker and that Docker or Apptainer is available on your system.

Note: The first time you run a containerized command, your container engine must be running. Start Docker Desktop (macOS/Windows) or confirm the Docker daemon is active (docker info) before proceeding. On HPC systems, Apptainer is available without a daemon.

With bulker, there’s no separate load/install step — activate directly:

bulker activate demo

This fetches the demo manifest from the registry (if not already cached), creates shimlinks for each command, and puts them on your PATH. Your prompt updates to show the active crate.

Run commands

Section titled “Run commands”

Commands from the crate work as if natively installed. The first time you run a command, Docker pulls the image automatically:

cowsay Hello world!
 ______________
< Hello world! >
 --------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

The fortune command is also in the demo crate, so you can pipe between containers:

fortune | cowsay
 _________________________________________
/ You are deeply attached to your friends \
\ and acquaintances.                      /
 -----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Each command runs in its own container — there’s no single container with both fortune and cowsay.

Deactivate

Section titled “Deactivate”
bulker deactivate

This restores your original PATH.

One-off commands with exec

Section titled “One-off commands with exec”

For scripts and non-interactive use, exec runs a single command without modifying your shell:

bulker exec demo -- fortune
bulker exec demo -- cowsay "Hello from exec"

Exercise: try it yourself

Section titled “Exercise: try it yourself”
  1. Activate the demo crate and run fortune by itself. What happens?
  2. Deactivate, then run the same command using bulker exec demo -- fortune. Compare the experience.
  3. Combine both commands in a single pipeline using exec mode: bulker exec demo -- sh -c 'fortune | cowsay'. Why does this require sh -c?
Hint for question 3

Without sh -c, the pipe (|) is interpreted by your host shell, which tries to pipe the output of one bulker exec call into another command. Wrapping the pipeline in sh -c '...' runs the entire pipeline inside a single container shell invocation. In interactive mode (bulker activate), piping works naturally because both shimlinks are on your PATH.

Key points

Section titled “Key points”
  • bulker activate <crate> puts containerized commands on your PATH. bulker deactivate removes them.
  • bulker exec <crate> -- <cmd> runs a single command without changing your shell — useful in scripts.
  • Each command runs in its own container. Pipes between commands work naturally in an activated crate.
  • You never type docker run. Bulker handles container orchestration behind shimlinks.

Next steps

Section titled “Next steps”