Install the Direct Agent Runner
The runner is a single self-contained program. It needs no .NET installation. Install it with Homebrew on macOS or Linux, or download the file for your system.
Prerequisites
Section titled “Prerequisites”- Docker, running. On macOS install Docker Desktop. On Linux
install Docker Engine and make sure your user can run
dockerwithoutsudo. - Outbound HTTPS access to your Direct address.
Downloads
Section titled “Downloads”Check github.com/Cratis/DirectPublic/releases for available
versions. The macOS and Linux archive names have the following form; replace <version> with the release
version. A checksums.txt file supplies the SHA-256 checksums.
| System | Processor | File |
|---|---|---|
| macOS | Apple silicon | direct-runner-<version>-osx-arm64.tar.gz |
| macOS | Intel | direct-runner-<version>-osx-x64.tar.gz |
| Linux | x64 | direct-runner-<version>-linux-x64.tar.gz |
| Linux | arm64 | direct-runner-<version>-linux-arm64.tar.gz |
The archive holds one file: direct-runner.
With Homebrew
Section titled “With Homebrew”brew tap cratis/cratisbrew install direct-runnerUpdate later with brew upgrade direct-runner.
From the download
Section titled “From the download”Set VERSION to the version listed on the release page, without the leading v:
VERSION='replace-with-release-version'curl -fLO "https://github.com/Cratis/DirectPublic/releases/download/v$VERSION/direct-runner-$VERSION-osx-arm64.tar.gz"tar -xzf "direct-runner-$VERSION-osx-arm64.tar.gz"sudo install -m 755 direct-runner /usr/local/bin/direct-runnerUse osx-x64 on an Intel Mac. If you downloaded the file with a browser and macOS refuses to open it, remove
the quarantine flag: xattr -d com.apple.quarantine /usr/local/bin/direct-runner.
Start the runner at login
Section titled “Start the runner at login”Choose one way to start the runner; do not register it with both service managers.
If you installed from the download, put the executable in its permanent location first, then run as your
normal user, without sudo:
direct-runner installRunning install again updates and restarts a registration it created. It refuses to overwrite one it did
not create. Enrollment is separate; see Enroll the runner with a code.
This creates a LaunchAgent that starts at login and restarts the runner if it stops. Its log is
~/Library/Logs/direct-runner.log.
If you installed with Homebrew, let it manage the runner as a background service instead:
brew services start direct-runnerThe service restarts the runner if it stops and writes its log to $(brew --prefix)/var/log/direct-runner.log.
Stop it with brew services stop direct-runner. direct-runner install refuses to register a second service
when Homebrew manages the runner.
With Homebrew
Section titled “With Homebrew”Homebrew on Linux installs the same formula:
brew tap cratis/cratisbrew install direct-runnerFrom the download
Section titled “From the download”Set VERSION to the version listed on the release page, without the leading v:
VERSION='replace-with-release-version'ARCH=x64 # or arm64curl -fLO "https://github.com/Cratis/DirectPublic/releases/download/v$VERSION/direct-runner-$VERSION-linux-$ARCH.tar.gz"curl -fLO "https://github.com/Cratis/DirectPublic/releases/download/v$VERSION/checksums.txt"sha256sum --check --ignore-missing checksums.txttar -xzf "direct-runner-$VERSION-linux-$ARCH.tar.gz"sudo install -m 755 direct-runner /usr/local/bin/direct-runnerThe sha256sum line prints OK for the file you downloaded.
Start the runner at login
Section titled “Start the runner at login”If you installed from the download, run:
direct-runner installloginctl enable-linger "$USER" # keep it running when you are not logged inRun install as your normal user, without sudo. It writes and enables
~/.config/systemd/user/direct-runner.service, starts it and restarts it if it stops. enable-linger lets the
user service keep running after logout; your system may require administrator approval. Follow its log with
journalctl --user -u direct-runner -f.
If you installed with Homebrew, use brew services start direct-runner instead. Use only one service manager.
As an alternative to install, create the unit yourself at ~/.config/systemd/user/direct-runner.service.
direct-runner install will not overwrite a unit it did not write:
[Unit]Description=Direct Agent RunnerAfter=network-online.target docker.service
[Service]ExecStart=/usr/local/bin/direct-runnerRestart=alwaysRestartSec=5
[Install]WantedBy=default.targetThen enable it:
systemctl --user daemon-reloadsystemctl --user enable --now direct-runnerFollow its log with journalctl --user -u direct-runner -f.
Switch from a unit you wrote
Section titled “Switch from a unit you wrote”direct-runner install refuses to change a unit it did not write, and says the file was not written by
direct-runner install. To let install manage the runner
instead, disable and remove your unit first, then run install:
systemctl --user disable --now direct-runnerrm ~/.config/systemd/user/direct-runner.servicesystemctl --user daemon-reloaddirect-runner installWhat install refuses
Section titled “What install refuses”direct-runner install stops without changing anything when:
- it runs as root or through
sudo. Run it as the user who should run the runner. - the executable was installed with Homebrew, or Homebrew already manages the service. Use
brew services. - the service file exists and
installdid not write it. See Switch from a unit you wrote. - the code given with
--enrollis not a valid enrollment code. Copy it again. --enrollis given but the machine already has a runner identity. Remove the runner in Direct and disconnect the machine first.- another runner already answers on the local page port.
Enroll the runner with a code
Section titled “Enroll the runner with a code”To start the runner already enrolled, pass a code created under Settings → Runners → Add runner:
direct-runner --enroll ABCD-EFGH-2345-6789-JKMN-PQRSThe code above is made up; replace it with your code. Stop any existing daemon before running
this foreground command. For a downloaded runner’s login service, use direct-runner install --enroll <code>
instead, replacing <code> with that code. Do not use install for a Homebrew-managed runner.
Only install writes a newly supplied code to runner.json. A foreground run’s argument or environment code
is not written there. A code already in the file is removed after successful enrollment or permanent refusal;
transient failures are retried. See Enroll without a browser.
Before running work, approve each worker image locally by its exact repository and SHA-256 digest. Use
--allow-image <repository@sha256:digest> on a foreground run or on install, replacing the placeholder with
a real, approved digest reference. Repeat the option for multiple images; a supplied list replaces the saved
list. An empty list refuses every worker. Enrollment and a connection alone do not guarantee work eligibility.
Verify the installation
Section titled “Verify the installation”Start the runner, then run direct-runner open as the same user. Open the one-time address it prints within
a minute. The page is at http://127.0.0.1:7190 by default, but opening that address directly does not
authenticate you. Continue with Get started to enroll it.
Check the runner
Section titled “Check the runner”direct-runner statusThis shows whether the login service is installed and running, and whether the runner is connected to Direct.
It also reports whether new work is paused and how many worker images are allowed when the daemon answers.
It does not print an enrollment code or an approval link. Use direct-runner open for authenticated page access.
List the commands
Section titled “List the commands”direct-runner helpThis lists the runner’s commands: install, uninstall, status, open, pause, resume and help.
--help and -h do the same. Run direct-runner without a command to start the runner itself. An unknown
command prints the usage and exits with code 2.
Update the runner
Section titled “Update the runner”Install the new version over the old one and restart the runner. The runner keeps its identity and settings in ~/.cratis/direct, so it stays connected as the same runner. See Where the runner keeps its files.
Uninstall the runner
Section titled “Uninstall the runner”- In Direct, open Settings → Runners and remove the runner to revoke its authority for new work. If you also want to erase local credentials, select Disconnect this machine on the authenticated local page before stopping the daemon. Disconnecting locally does not remove the runner’s listing in Direct.
- Stop and remove the login service with
direct-runner uninstall, or usebrew services stop direct-runnerif Homebrew manages it. Then remove the program (brew uninstall direct-runner, or delete the file).direct-runner uninstallkeeps the identity and settings and credentials in~/.cratis/direct(or the macOS Keychain). For a hand-written systemd unit, disable it withsystemctl --user disable --now direct-runnerand remove the unit yourself;uninstallonly removes a service it wrote. - After disconnecting, optionally delete the remaining state folder
~/.cratis/directto remove settings. Deleting the folder alone does not remove credentials from the macOS Keychain. See Where the runner keeps its files.