Runner as a Windows Service

On Windows, the runner can install itself as a native Windows service managed by the Service Control Manager (SCM). Running as a service means the runner starts automatically at boot, runs in the background without a logged-in user, and is automatically restarted by Windows if it crashes.

This page covers installing, configuring, and managing the runner as a Windows service using the built-in service commands.

The service commands are only available on Windows builds of the runner. On Linux and macOS, manage the runner with systemd or launchd instead.

Prerequisites

Before installing the service, make sure you have:

• The act_runner binary on the Windows machine where jobs will run.

• An elevated (Administrator) terminal. Creating, starting, stopping, and removing services all require administrator rights.

• A registered runner. Run act_runner register before installing the service so a .runner registration file exists in the working directory. See Getting Started for how to obtain a registration token and register a runner.

The installer checks for the .runner file at install time and refuses to proceed if it is missing. You can skip these checks with --no-config-check, but the service will fail to start without a valid registration.

The service Commands

All service management is done through the service subcommand:

Command	Description
act_runner service install	Create the service in SCM. Requires admin.
act_runner service start	Start the installed service.
act_runner service stop	Stop the service, draining any in-flight jobs first.
act_runner service status	Print the current SCM status of the service.
act_runner service uninstall	Stop and remove the service.

Installing the Service

1

Register the runner

From the directory where you want the runner to live, register it with your Copia instance. This creates the .runner file the service needs.

.\act_runner.exe register `
  --no-interactive `
  --instance https://app.copia.io `
  --token <your_registration_token> `
  --name <runner_name>
  --labels '<your_labels_here>'

2

Install the service

In an elevated terminal, run:

.\act_runner.exe service install

This creates the service in SCM, registers a Windows event-log source, and grants the service account read/write access to the working directory. By default the service is named CopiaActRunner, shows as Copia Act Runner in services.msc, starts automatically at boot, and runs under an auto-managed virtual service account.

See Install Options below to customize the name, account, start type, and more.

3

Start the service

.\act_runner.exe service start

The command blocks until the service reports Running (or times out). The runner will now pick up jobs and survive reboots.

4

Verify

.\act_runner.exe service status

A healthy, running service prints something like:

name=CopiaActRunner state=Running pid=12345 checkpoint=0 waitHint=0ms exitCode=0 serviceExit=0

The runner should also appear as online in your organization or repository Runners settings on Copia.

Install Options

The service install command accepts the following flags:

Flag	Default	Description
--name	CopiaActRunner	Service name (the SCM key, virtual-account name, and event-log source). Letters, digits, -, and _ only.
--display-name	Copia Act Runner	Friendly name shown in services.msc.
--description	Runs Copia Actions workflows.	Service description.
--config	(none)	Absolute path to a config.yaml. If omitted, the runner uses built-in defaults plus the .runner file in the working directory.
--working-directory	directory of the binary	Absolute path the service runs from. The .runner file and logs live here.
--user	virtual	The Windows account the service runs as. See Service Accounts.
--password	(none)	Password for a real local/domain account. Prefer the ACT_RUNNER_SVC_PASSWORD environment variable.
--start-type	automatic	One of automatic, automatic-delayed, manual, disabled.
--restart-on-failure	true	Configure SCM recovery actions to auto-restart the runner if it crashes.
--overwrite	false	Stop and replace an existing service of the same name.
--no-config-check	false	Skip the install-time existence checks for the config and .runner files.

The working directory and the binary must be on a local drive. Installation is rejected for UNC/network paths (\\server\share\…) because service accounts cannot reliably authenticate to network shares.

Running multiple runners on one machine

Each Windows service needs a unique name. To run more than one runner on the same host, give each its own --name and --working-directory:

.\act_runner.exe service install --name CopiaActRunner-1 --working-directory C:\copia\runner1
.\act_runner.exe service install --name CopiaActRunner-2 --working-directory C:\copia\runner2

Pass the matching --name to start, stop, status, and uninstall for each.

Service Accounts

The --user flag selects which Windows identity the service runs as:

--user value	Account type	Notes
(omitted) or virtual	Virtual account (default)	SCM auto-creates an NT SERVICE\<name> account with no password and a per-service SID. The installer automatically grants it read/write on the working directory. Recommended.
LocalSystem	Built-in LocalSystem	The most privileged local account. No password.
NetworkService	Built-in NetworkService	Presents the machine account on the network. No password.
.\name, DOMAIN\name, name@domain	Real local or domain user	Requires a password.
DOMAIN\name$, name$@domain	Group Managed Service Account (gMSA)	The trailing $ marks a gMSA. Must be domain-qualified. No password.

For real local/domain accounts, supply the password via the ACT_RUNNER_SVC_PASSWORD environment variable rather than the --password flag, which would otherwise be visible in shell history and process listings:

$env:ACT_RUNNER_SVC_PASSWORD = "<password>"
.\act_runner.exe service install --user "DOMAIN\copia-runner"

Managing the Service

# Start / stop
.\act_runner.exe service start
.\act_runner.exe service stop

# Check status
.\act_runner.exe service status

You can also manage the service from the standard Windows tooling — services.msc, sc.exe, or Start-Service / Stop-Service in PowerShell — using the service name (default CopiaActRunner).

Graceful stop and job draining

service stop triggers a graceful shutdown: the runner stops accepting new jobs and waits for any in-flight job to finish before the service reports Stopped. Windows is kept informed throughout so it does not kill the process prematurely. The drain is bounded by the runner's configured ShutdownTimeout. The same draining happens automatically on a system shutdown.

Automatic restart

When installed with --restart-on-failure (the default), SCM is configured to automatically restart the runner if it exits unexpectedly, with escalating delays of 5 seconds, 15 seconds, and 60 seconds between successive failures.

Logs and Troubleshooting

The service writes logs to two places:

• act_runner.log in the working directory. Because SCM discards the runner's standard output, this file is the primary log. All normal runner output goes here.

• The Windows Application event log, under the service name as the source. Errors and key lifecycle events (started, stopping, stopped, fatal) are mirrored here. View them in Event Viewer → Windows Logs → Application.

If the service fails so early that the log file cannot be opened, the runner writes a one-line breadcrumb to act_runner.startup-error.log next to the binary.

Common issues:

• "service already exists" — A service with that name is already installed. Pass --overwrite to replace it, or choose a different --name.

• "runner registration file ... not found" — Run act_runner register in the working directory first, or pass --no-config-check if you are registering separately.

• Access denied / "admin required" — Run the command from an elevated (Administrator) terminal.

• Service starts then stops immediately — Check act_runner.log and the Application event log. A missing or invalid .runner registration is the most common cause.

Uninstalling

In an elevated terminal:

.\act_runner.exe service uninstall

This stops the service (if running), removes it from SCM, and deregisters its event-log source. Add --name <name> if you installed under a non-default name. The working directory and its logs are left in place.

Note for Self-Hosted customers: replace https://app.copia.io with your instance URL in all commands above.