Bolt is agentless orchestration for the tasks you run by hand

Agentless by design: SSH and WinRM from your workstation

Bolt is described as an open source orchestration tool that automates the manual work it takes to maintain your infrastructure, on an as-needed basis or as part of a greater orchestration workflow. The project description spells out the deployment model clearly. Bolt can be installed on your local workstation and connects directly to remote targets with SSH or WinRM, so you are not required to install any agent software. That single decision shapes everything else about the tool. There is no daemon to deploy, no agent version to keep in step with the control side, and nothing listening on the target beyond the remote access you already operate. The work it is aimed at is concrete: patching and updating systems, troubleshooting servers, deploying applications, and stopping or restarting services. The audience is the sysadmin or platform engineer who today opens a terminal, runs the same command against a list of hosts one at a time, and wishes the procedure were saved, parameterised and repeatable.

Plans as the unit of work, and the languages you already have

The second design decision is that a plan is the artefact you keep. The README asks you to run simple plans to rid yourself of the headaches of orchestrating complex workflows, and to create and share Bolt plans so you can expand across your application stack. Sharing matters here, because a plan is how knowledge of a procedure moves from one engineer's terminal to a team's repository. The other decision is that Bolt does not impose a scripting language on you. The README says you can get going with your existing scripts and plans, including YAML, PowerShell, Bash, Python or Ruby, or reuse content from the Puppet Forge. So a team with existing Bash tooling does not rewrite it in a Bolt-specific dialect, and a Windows shop can work in PowerShell while a Linux shop works in Bash, using the same orchestration layer. The Puppet Forge angle also means an existing module catalogue is available as task content rather than something to port. What Bolt adds over a shell loop is the targeting, the ordering, the error handling and the ability to hand the same plan to someone else.

The repository is a Ruby gem with a Puppet-shaped interior

The file listing shows a Ruby project with the conventions of a gem and the layout of a Puppet repository. bolt.gemspec, Gemfile, Rakefile and exe/ are the packaging skeleton, and lib/, ext/ and libexec/ hold the implementation. Alongside them sit Puppet-specific pieces: modules/ and bolt-modules/ for bundled and project modules, a Puppetfile, and a pwsh_module/ directory for the PowerShell side of the tool, which is how the Windows path is supported given that PowerShell is a first class scripting target. spec/ and bolt_spec_spec/ hold the test suites, acceptance/ holds higher level tests, and the Rakefile ties them together. There is also a Vagrantfile for local development, a Dockerfile.bolt-server and docker-compose-bolt-server.yml for a server mode, and schemas/ for structured definitions. Documentation is split across documentation/, guides/ and developer-docs/, with dev-resources/ and scripts/ for development tasks, and CODEOWNERS, CODE_OF_CONDUCT.md, CONTRIBUTING.md and a .rubocop.yml plus .rubocop_todo.yml for project governance and linting. That is a large surface for a tool that installs on one workstation.

Platform coverage is asserted by CI, and Windows is a first class target

The README states that Bolt can be installed on Linux, Windows and macOS, and points to documentation/bolt_installing.md for complete installation details, with alternate installation methods and running from source covered in the contributing guidelines. The badges at the top of the README show how that claim is kept honest. There is a Modules workflow, a Linux workflow and a Windows workflow, each with its own status badge, so the three supported platform lines are built continuously rather than asserted in prose. The presence of a separate Windows badge, and of the pwsh_module/ directory in the tree, tells you the Windows support is not a wrapper around SSH. The transport is WinRM, and the scripting language there is PowerShell, which means a Windows target needs WinRM configured and reachable rather than an SSH daemon. The version badge links to CHANGELOG.md rather than to a release page, which matches the fact that this repository publishes no GitHub releases. That is the normal shape for a project distributed as a gem, and it means you track the changelog, not tags.

A first run means reading the docs the README points to

The README is a summary by design, and it says so. For a step-by-step introduction to basic functionality it points to the getting started guide, and it points to the Bolt website for more information and documentation, with the installation details in the repository at documentation/bolt_installing.md. The order of operations the README describes is straightforward. Install Bolt on your workstation, decide what the target set is, write a plan that runs your existing scripts or Forge content, and share the plan so the team can reuse it. Beyond that the README is genuinely silent on the details a first-time user needs, and it is worth being precise about which. The README does not document the inventory or target syntax, the plan file format, how credentials and secrets are provided, how results and failures are surfaced, or how a task behaves when it is not idempotent. Those live in the linked documentation, and the puppet.com docs site is where to look. A team that cannot read those pages will not get much out of the repository itself, since the code and the guides are the substance here rather than the README.

The limitation: no agent means no enforced state and no convergence

The agentless model is Bolt's best feature and its boundary at the same time. Without an agent there is no scheduled run, no continuous enforcement of a desired state, and no report of drift on a machine nobody has touched. Bolt is a tool for acting now, on targets you name, and if the machine changes afterwards, the tool does not notice. That is fine for a patch run, a restart, a one-off deployment or a troubleshooting session, and it is not fine if your requirement is that every host is in a known state at all times. The second limitation follows from the first. Access is the SSH or WinRM credential of the person running Bolt, so an automation that runs unattended needs those credentials in a form the tool can use, and the README does not discuss credential handling. The third is documentation depth. The README itself is a summary that defers to external guides, and this repository publishes no GitHub releases, so the CHANGELOG.md is the version history and there is no per-release announcement trail to search when something changes between versions.

Bolt versus a shell loop and versus a configuration management system

There are two realistic alternatives, and Bolt sits between them. The first is what most teams do today, a shell or Ansible-like loop over a host list, with each task typed by hand. The difference in approach is that Bolt turns the procedure into a plan with explicit targeting, so the same operation can be run against one host, a group, or a set of groups, and the plan is reviewable in a repository instead of living in shell history. The second alternative is a declarative configuration management tool such as Puppet, the ecosystem Bolt ships inside. The difference there is philosophical. A configuration management tool describes a desired state and converges nodes towards it continuously, running on a schedule and reporting when a node does not match. Bolt executes tasks on demand, whatever the current state, and leaves the result as it is. If your operational model is desired-state convergence, Bolt is the wrong instrument and adding it only adds a second tool alongside the one you already run. If your operational model is bursts of ad hoc work that you want repeatable, Bolt is cheaper and simpler than a convergence engine because there is no agent and no catalog to maintain.

Editorial conclusion

Bolt fits the gap between a one-off SSH session and a full configuration management system, especially for patch runs, ad hoc troubleshooting and repeatable multi-host procedures that a team wants to save and share as plans. It does not fit a requirement for continuous convergence or enforced state. Before adopting it, check the connection requirements for your environment, since no agent is installed and access is via SSH or WinRM, and confirm the platform coverage you need against the Linux and Windows CI workflows, noting the last push was on 2026-09-11 with no tagged GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. puppetlabs/bolt on GitHub
5. README