Configuration

Config file location

Bulker looks for the config file in this order:

1. -c flag on any command
2. $BULKERCFG environment variable
3. ~/.config/bulker/bulker_config.yaml
4. No file found — use built-in defaults with auto-detected engine, then cache to ~/.config/bulker/bulker_config.yaml

Bulker works with no config file. On first use it auto-detects your container engine, builds a config from defaults, and writes it to disk. If the write fails (read-only filesystem, CI container), it continues with in-memory defaults.

Full config file

bulker:
  container_engine: docker          # "docker" or "apptainer"
  engine_path: /usr/bin/docker      # absolute path (auto-detected)
  default_namespace: bulker         # used when namespace is omitted
  registry_url: http://hub.bulker.io/  # default manifest registry

  # Shell settings
  shell_path: ${SHELL}
  shell_rc: $HOME/.bashrc
  shell_prompt: "(bulker:%s) "   # optional: customize prompt when crate is active

  # Global defaults (applied to all containers)
  volumes:
    - $HOME
  envvars:
    - DISPLAY

  # Platform defaults (set automatically)
  host_network: true                # Linux: true, macOS: false
  system_volumes: true              # Linux: true, macOS: false

  # Apptainer-specific
  apptainer_image_folder: ~/.local/share/apptainer/images

  # Per-image extra arguments (advanced, optional)
  # tool_args:
  #   quay-io-biocontainers:
  #     samtools:
  #       default:
  #         extra_flag: "--flag-value"

Managing config from the CLI

# View full config
bulker config show

# Get a specific value
bulker config get container_engine

# Set a value
bulker config set container_engine=apptainer

# Set list values (comma-separated)
bulker config set volumes=$HOME,/data/shared,/scratch
bulker config set envvars=DISPLAY,LANG,MY_VAR

# Add a single entry to a list
bulker config add volumes=/data/new_mount

# Remove a single entry from a list
bulker config remove volumes=/data/old_mount

Config keys

Key	Type	Default	Description
container_engine	string	auto-detected	docker or apptainer
engine_path	string	auto-detected	Absolute path to the container engine binary (e.g., /usr/bin/docker). Auto-detected on first use. Ensures the engine works in strict mode without PATH.
default_namespace	string	bulker	Namespace used when omitted from crate path
registry_url	string	http://hub.bulker.io/	Default manifest registry URL
shell_path	string	${SHELL}	Shell to use for activation
shell_rc	string	$HOME/.bashrc	Shell RC file for init-shell
volumes	list	[$HOME]	Directories mounted into every container
envvars	list	[DISPLAY]	Environment variable allowlist for --strict-env mode. In normal mode, all host env vars are passed automatically.
host_network	bool	platform-dependent	Add --network=host to Docker commands
system_volumes	bool	platform-dependent	Mount system files (/etc/passwd, /tmp/.X11-unix, etc.)
apptainer_image_folder	string	~/.local/share/apptainer/images	Where .sif files are stored
shell_prompt	string	none	Shell prompt format string when a crate is active. Equivalent to setting BULKERPROMPT. Use %s as a placeholder for the crate name (e.g., "[bulker: %s] ").
rcfile	string	start.sh	RC file sourced at shell startup during activation
rcfile_strict	string	start_strict.sh	RC file sourced in strict mode activation
tool_args	map	none	Per-image extra arguments, keyed by Docker image namespace, image name, and tag. Supports a default tag as fallback. Used internally by shimlink dispatch to supply image-specific flags.

Config-level volumes and envvars apply to every container command. To customize these per-command, see the Volumes and Environment Variables guide.

Platform differences

Setting	Linux	macOS
host_network	true	false
system_volumes	true	false

On macOS, --network=host is not supported by Docker Desktop, and system volume paths like /etc/passwd don’t exist. Bulker sets the appropriate defaults per platform.

Shell prompt customization

When a crate is active, the shell prompt shows the crate name. The format can be set in two ways:

• shell_prompt config key — persisted in the config file, applied to all sessions.
• BULKERPROMPT env var — overrides the config value for the current session.

Use %s as the placeholder for the crate name:

# In config file
bulker config set shell_prompt="[bulker: %s] "

# Or as an env var for one session
export BULKERPROMPT="[bulker: %s] "

Manifest cache

Fetched manifests are cached in ~/.config/bulker/manifests/. The filesystem cache is the source of truth — there is no crates map in the config file. Use bulker crate list to see cached crates and bulker crate clean to remove them.