Summary

Add a CLI flag for forwarding selected host environment variables into the VM, instead of requiring env_forward configuration in config.yaml or .broodbox.yaml.

Today, Brood Box supports env forwarding through agent config, for example:

agents:
  opencode:
    env_forward:
      - OPENAI_API_KEY
      - ANTHROPIC_API_KEY
      - OPENCODE_*

But there does not appear to be an equivalent one-off CLI option on bbox itself.

Problem

For ad hoc use, it is inconvenient to edit config just to pass a small set of environment variables into a single run. This is especially noticeable when testing different providers, switching tokens temporarily, or running short-lived experiments.

Proposed behavior

Add a repeatable CLI flag such as:

bbox opencode --env-forward OPENAI_API_KEY --env-forward ANTHROPIC_API_KEY
bbox opencode --env-forward 'OPENCODE_*'

Potential alternatives:

• --env
• --forward-env

Expected semantics

• Repeatable flag
• Same matching rules as config env_forward
  • exact variable names
  • simple glob patterns like PREFIX_*
• Merges with configured env_forward values rather than replacing them, unless there is a strong reason to make CLI authoritative
• Applies only to the current invocation
• Continues to rely on host env vars already being present in the shell

Nice to have

• Show forwarded env names in debug logs, but never values
• Document interaction with .broodbox.yaml and global config precedence
• Consider whether bbox --help should mention that .env files are still not forwarded automatically

Motivation

This would make bbox much easier to use for one-off runs without weakening the existing allowlist model for VM env injection.