Flags

TIP

Flags go after the subcommand: yolobox run --flag cmd or yolobox claude --flag, not yolobox --flag run cmd.

Runtime & image

Flag	Description
--runtime <name>	Use docker, podman, or container
--image <name>	Override the base image
--packages <list>	Comma-separated apt packages for a derived custom image
--customize-file <path>	Dockerfile fragment for a derived custom image
--rebuild-image	Force rebuild of the derived custom image

Filesystem, config, and identity

Flag	Description
--mount <src:dst>	Extra mount, repeatable
--env <KEY=val>	Extra environment variable, repeatable
--setup	Run interactive setup before starting
--ssh-agent	Forward SSH agent socket
--readonly-project	Mount the project read-only and write outputs to /output
--claude-config	Copy host ~/.claude config into the container
--gemini-config	Copy host ~/.gemini config into the container
--git-config	Copy host ~/.gitconfig into the container
--gh-token	Forward GitHub CLI token from gh auth token
--copy-agent-instructions	Copy global instruction files into the container

Networking and behavior

Flag	Description
--no-network	Disable network access
--network <name>	Join a specific network
--pod <name>	Join an existing Podman pod
--no-yolo	Disable auto-confirmations
--scratch	Start with a fresh home and cache
--docker	Mount the Docker socket and join the shared yolobox-net network

Resources and low-level runtime control

Flag	Description
--cpus <num>	Limit CPUs, including fractional values like 3.5
--memory <limit>	Hard memory limit like 8g or 1024m
--shm-size <size>	Size of /dev/shm
--gpus <spec>	Pass GPUs, for example all or device=0
--device <src:dest>	Add host devices, repeatable
--cap-add <cap>	Add Linux capabilities, repeatable
--cap-drop <cap>	Drop Linux capabilities, repeatable
--runtime-arg <flag>	Pass raw runtime flags directly to Docker or Podman

SSH agent on macOS

On macOS, --ssh-agent depends on the VM forwarding the agent:

• Docker Desktop forwards it automatically
• Colima needs forwardAgent: true in ~/.colima/default/colima.yaml, then a restart

Networking

By default, yolobox uses the runtime's normal bridged network.

• use --network <name> when you need container-name DNS on a compose network
• use --no-network when you want complete network isolation

Docker access

The --docker flag mounts the host Docker socket into the container and joins a shared yolobox-net network. That lets the agent:

• run Docker commands
• build images
• start sibling containers
• communicate with services by container name on the shared network

The network name is available inside the container as $YOLOBOX_NETWORK.

WARNING

--docker cannot be combined with --no-network.

Derived image customization

These flags map to the same model described in Project-Level Customization:

yolobox run --packages default-jdk,maven mvn --version
yolobox run --customize-file .yolobox.Dockerfile bash
yolobox run --packages default-jdk --rebuild-image java --version

Use them when you want a one-off customization without writing config first.

Raw runtime passthrough

Anything not covered by a dedicated flag can still be forwarded with --runtime-arg:

yolobox run \
  --runtime-arg "--ulimit" \
  --runtime-arg "nofile=4096:8192" \
  --runtime-arg "--security-opt" \
  --runtime-arg "seccomp=unconfined" \
  claude

Docker and Podman accept these passthrough flags unchanged. Apple's container runtime ignores options it does not understand.