chef/bento: the Packer templates behind the bento Vagrant boxes

Packer templates wrapped in a Ruby gem

chef/bento holds two different things: Packer templates written in HCL, and a Ruby gem that drives them. The templates sit in `packer_templates/`, the per-distribution variable files that feed them sit in `os_pkrvars/`, and `bento.gemspec` at the root builds a command named `bento` out of `bin/`. Not every template is published. A subset of the builds goes to the bento org on Vagrant Cloud, and those published boxes are the default ones kitchen-vagrant uses, which is how most people meet this project without ever cloning it. That arrangement also sets the shape of the work: a published box is the result of one Packer run. Replacing one means building it, testing it and uploading it again, a chain the README spells out in four subcommands.

Installing the gem and running the first build

The install path in the README has five steps and no package manager in them: set up a Ruby environment, clone the repository, move into it, build the gem and install it. `Gemfile`, `Rakefile`, `.rspec` and `spec/` at the root mark this as a gem with its own test suite.

gem build bento.gemspec
gem install bento-*.gem

Requirements are pinned in prose rather than enforced: Packer >= 1.7.0, Vagrant >= 2.4.0, and at least one virtualization provider installed on the machine. The first build then takes a single template path.

bento build os_pkrvars/debian/debian-13-x86_64.pkrvars.hcl

That path names an architecture as well as a distribution, so the same file shape covers an x86_64 box and an arm64 one. Nothing on the command line tells you which providers get built from it.

Fourteen flags and a filter a template name walks past

Under `bento build` sit fourteen options, and they divide cleanly. Four change the machine being built: `--cpus`, `--mem`, and the `--vars` and `--var_files` injections, where variables arrive as comma separated names equal to values, for example `boot_wait="2s"`. Four change what gets produced: `--metadata-only` writes just the metadata json, `--dry-run` creates no build at all and still produces that metadata file for reference, `--mirror` replaces the template's default mirror link, and `--on-error` chooses what happens when a build fails. The rest steer the run: `--debug` for logs, `--gui` to watch a VirtualBox console, which is false by default, and `--single` to turn off the parallel builds.

`bento list` prints what a bare `bento build` would build for the CPU architecture of the workstation, filtered by the `do_not_build:` section of the configuration file through regex. Two details sit badly here. The `--config` option is described as using a file other than the default `builds.yml`, which matches the `builds.yml` file at the repository root, while the `bento list` and `bento upload` sections name `build.yml`. And `--only` carries the default `parallels-iso.vm,virtualbox-iso.vm,vmware-iso.vm`, while the Packer examples further down build all possible providers simultaneously with no such flag. Name a template explicitly and the filter stops applying, even for entries listed under `do_not_build:`.

bento test merges one provider's verdict

`bento test` exists because a finished box is not proof of a working one. After a successful build you are supposed to have the vagrant box and a metadata file in `builds/build_complete`, and the test command takes those into a test-kitchen configuration.

bento test

Results land in two marker paths: `builds/testing_passed` on success and `builds/testing_failed` on failure. What matters is the second run. Each provider's result is merged into the metadata file rather than replacing it, so re-running one provider after a fix updates that entry and leaves every previously tested provider's entry intact.

Upload turns a metadata file into a publish command

Uploading is what turns a local build into a public box, and it is the thinnest part of the documentation. The account name and the OSs going public live in `build.yml`, so that file has to be edited before a first publish rather than configured once. The vagrant cli has to be configured and logged in as well.

bento upload

Only what passed testing is uploaded, from the `builds/testing_passed` directory. Each `<box_name>._metadata.json` file is read for its descriptions, version, provider and checksums, and those fields become the arguments of the generated `vagrant cloud publish` command, so the box bytes and the published metadata come from one build.

The alternative is to skip the gem and call Packer directly.

packer init -upgrade ./packer_templates
packer build -only=virtualbox-iso.vm -var-file=os_pkrvars/ubuntu/ubuntu-24.04-x86_64.pkrvars.hcl ./packer_templates

That route also produces a box in `builds/build_complete`, but it has no test-kitchen stage, no merge behaviour and no publish command generator, so anyone who wants the chain past the build has to write it.

Captions name one distribution, variable files name another

Three examples under the Packer heading carry captions that do not match the variable file on the line below them. The one headed as building an Ubuntu 22.04 box for the VirtualBox provider passes the 24.04 file.

packer build -only=virtualbox-iso.vm -var-file=os_pkrvars/ubuntu/ubuntu-24.04-x86_64.pkrvars.hcl ./packer_templates

The one headed as the latest Debian 12 boxes passes the 13 file, and the one headed as latest CentOS 7 boxes passes an AlmaLinux 10 file, which is a different distribution in the path itself.

packer build -except=parallels-iso.vm,vmware-iso.vm -var-file=os_pkrvars/almalinux/almalinux-10-x86_64.pkrvars.hcl ./packer_templates

A fourth gap sits further up, where the quick start adds `bento/ubuntu-18.04` as a box to Vagrant, three LTS generations behind the 24.04 files the same page builds. Nobody has to guess which line wins, because Packer reads the variable file and ignores the caption. Read the file, then read the distribution version inside it, before trusting the sentence above it.

Output lands wherever you ran the command from

The note at the top of the README is about something the commands do not: where the output ends up. The Packer build output directory is relative to the working directory the command runs in, so the advice is to run from the bento root, where output lands in bento/builds/build_complete/(build_name). Run the same command from somewhere else and a directory of that name appears there instead, next to a root that already carries a tracked `builds/` entry. That root also holds `amazonlinux-2023-x86_64-virtualbox-build.sh` and `amazonlinux-2023-aarch64-virtualbox-build.sh`, two architecture-specific scripts pinned to one hypervisor, sitting beside a CLI that runs builds in parallel unless `--single` says otherwise.

The Windows on KVM section adds a manual step: the paravirtualized driver ISO has to be downloaded by hand and placed in `builds/iso/`.

qemu and Hyper-V sit under an experimental footnote

The provider list is long and the caveat is short. VirtualBox, VMware Fusion, VMware Workstation, Parallels Desktop Pro, UTM, qemu and Hyper-V are all named as acceptable, but qemu and Hyper-V carry a footnote saying support for them is considered experimental and that the corresponding Vagrant Cloud images may or may not exist. Since the point of this repository is to publish boxes, a provider with no image on Vagrant Cloud is a build you can run and not ship. The arm64 path depends on host software too, with Vagrant 2.4.0+ needed for new cpu architecture support and VirtualBox 7.1.6+ for arm64.

The paperwork a template collection needs is present as well: `TESTING.md`, `SECURITY.md`, `AGENTS.md`, `CODE_OF_CONDUCT.md` and `CONTRIBUTING.md` at the root, alongside `.codespellrc` and `.shellcheckrc` for the two linters this repository runs on its own text and scripts. The last push was on 2026-11-02, and the code ships under Apache-2.0, a licence that asks redistributed copies to carry the notice and its text while placing no copyleft condition on whatever links against it.

Editorial conclusion

Adopt chef/bento when your pipeline publishes Vagrant boxes for kitchen-vagrant and you want templates, variable files and the publish step in one repository. Skip it when a stock box already on Vagrant Cloud will do, because every build is a full Packer run per provider. Before a first upload, check three things by hand: run the command from the repository root so output lands in `builds/build_complete`, read the variable file passed to `-var-file` against the caption above it, and put your real account name into `build.yml`.

Frequently asked questions

Official sources

1. chef/bento on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases