Puppet's Services: Puppet Agent on Windows Systems

This version is out of date. For current versions, see Puppet packages and versions.

Puppet agent is the application that manages configurations on nodes. It requires a Puppet master server to fetch configuration catalogs from. (For more info, see Overview of Puppet’s Architecture.)

For details about invoking the Puppet agent command, see the puppet agent man page.

Supported Platforms

This page describes how Puppet agent behaves on Windows systems. For information about Linux, OS X, and other Unix-like operating systems, see Puppet Agent on *nix Systems.

Not all operating systems can manage the same resources with Puppet; some resource types are OS-specific, and others may have OS-specific features. See the [resource type reference][] for details.

Puppet Agent’s Run Environment

Puppet agent runs as a specific user (defaulting to LocalSystem) and initiates outbound connections on port 8140.


By default, Puppet agent runs as the LocalSystem user. This lets it manage the configuration of the entire system, but prevents it from accessing files on UNC shares.

Puppet can also run as a different user. You can change the user in the Service Control Manager (SCM). To start the SCM, choose “Run…” from the Start menu and type Services.msc.

You can also specify a different user when installing Puppet. To do this, install via the command line and specify the required MSI properties (PUPPET_AGENT_ACCOUNT_USER, PUPPET_AGENT_ACCOUNT_PASSWORD, and PUPPET_AGENT_ACCOUNT_DOMAIN).

Puppet agent’s user can be a local or domain user. If this user isn’t already a local administrator, the Puppet installer will add it to the Administrators group. The installer will also grant Logon as Service to the user.


By default, Puppet’s HTTPS traffic uses port 8140. Your OS and firewall must allow Puppet agent to initiate outbound connections on this port.

If you want to use a non-default port, you’ll have to change the masterport setting on all agent nodes, and ensure that you’ve changed your Puppet master’s port as well.


When running as a service, Puppet agent logs messages to the Windows Event Log. You can view its logs by browsing the Event Viewer. (Control Panel → System and Security → Administrative Tools → Event Viewer)

When running in the foreground with the --verbose, --debug, or --test options, Puppet agent logs directly to the terminal.

When started with the --logdest <FILE> option, Puppet agent logs to the file specified by <FILE>.


In addition to local logging, Puppet agent will submit a report to the Puppet master after each run. (This can be disabled by setting report = false in puppet.conf.)

In Puppet Enterprise, you can browse these reports in the PE console’s node pages, and you can analyze correlated events with the PE event inspector.

Managing Systems With Puppet Agent

In a normal Puppet site, every node should periodically do configuration runs, to revert unwanted changes and to pick up recent updates.

On Windows nodes, there are two main ways to do this:

  • Run Puppet agent as a service. The easiest method. The Puppet agent service will do configuration runs at a set interval, which can be configured.
  • Only run Puppet agent on demand. To trigger runs on groups of systems, you can use Puppet Enterprise’s built-in orchestration features.

Since the Windows version of the Puppet agent service is much simpler than the *nix version, there’s no real performance to be gained by running Puppet as a scheduled task. All users who want scheduled configuration runs should run the Windows service.

Running Puppet Agent as a Service

By default, the Puppet installer will configure Puppet agent to run as a Windows service and will automatically start it. No further action is needed. Puppet agent will do configuration runs at a set interval.

Configuring the Run Interval

The Puppet agent service defaults to doing a configuration run every 30 minutes. You can configure this with the runinterval setting in puppet.conf:

# C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf
  runinterval = 2h

If you don’t need an aggressive schedule of configuration runs, a longer run interval will let your Puppet master server(s) handle many more agent nodes.

Once the run interval has been changed, the service will stick to the prior schedule for the next run and then switch to the new run interval for subsequent runs.

Configuring the Service Start Up Type

The Puppet agent service defaults to starting automatically. If you’d rather start it manually or disable it, you can configure this during installation. To do this, install via the command line and specify the PUPPET_AGENT_STARTUP_MODE MSI property.

You can also configure this after installation with the Service Control Manager (SCM). To start the SCM, choose “Run…” from the Start menu and type Services.msc.

You can also configure agent service with the sc.exe command. To prevent the service from starting on boot:

C:\>sc config puppet start= demand
[SC] ChangeServiceConfig SUCCESS

(Note that the space after start= is mandatory! Also note that this must be run in cmd.exe; this command won’t work from PowerShell.)

To restart the service:

C:\>sc stop puppet
C:\>sc start puppet

To change the arguments used when triggering a Puppet agent run (this example changes the level of detail that gets written to the Event Log):

C:\>sc start puppet --debug --logdest eventlog

Running Puppet Agent On Demand

Some sites prefer to only run Puppet agent on demand; others use scheduled runs, but occasionally need to do an on-demand run.

Puppet agent runs can be started locally (while logged in to the target system), or remotely via Puppet Enterprise’s orchestration tools.

While Logged in to the Target System

On Windows, you can start a configuration run with the “Run Puppet Agent” Start menu item. This will show the status of the run in a command prompt window.

You must be logged in as an administrator to do this. On Windows 7/2008 and later, Windows will ask for User Account Control confirmation when you start a configuration run:

UAC dialog

Running Other Puppet Commands

If you want to run other Puppet-related commands, you must start a command prompt with administrative privileges. You can do this with either the standard cmd.exe program, or the “Start Command Prompt with Puppet” Start menu item added by the Puppet installer.

  • On Windows 2003, make sure you are logged in as an administrator before starting the command prompt.
  • On Windows 7 or 2008, you must right-click the start menu item and choose “Run as administrator:”

    the right click menu, with run as administrator highlighted

    This will ask for UAC confirmation:

    UAC dialog


To run Puppet agent remotely on any number of systems, you should use Puppet Enterprise’s orchestration tools. For info, see the Puppet Enterprise manual page on triggering Puppet runs.

Open source Puppet users can install MCollective and the puppet agent plugin to get similar capabilities, but Puppet Labs doesn’t provide standalone MCollective packages for Windows.

Puppet agent on Windows doesn’t support the deprecated Puppet kick command.

Disabling and Re-enabling Puppet Runs

You can prevent Puppet agent from doing any Puppet runs by starting a command prompt with elevated privileges and running puppet agent --disable "<MESSAGE>". You can re-enable it with puppet agent --enable.

If Puppet agent attempts to do a configuration run while disabled — either a scheduled run or a manually triggered one — it will log a message like:

Notice: Skipping run of Puppet configuration client; administratively disabled
(Reason: 'Investigating a problem 5/23/14 -NF'); Use 'puppet agent --enable' to re-enable.

Configuring Puppet Agent

Puppet agent should be configured with puppet.conf, using the [agent] and/or [main] section. For notes on which settings are most relevant to Puppet agent, see the short list of important settings.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.