Agent Operations

The Pullbase agent enforces desired state on each managed server. It runs as a native binary managed by systemd — the recommended approach for VMs and bare-metal hosts.

Deployment methods

One-liner install script (recommended)

The fastest way to deploy an agent is using the install script endpoint. After registering a server in Pullbase, run:

curl -fsSL "https://pullbase.example.com/api/v1/servers/web-01/install-script?token=pbt_xxx" | sudo bash

The script:

Downloads the agent binary from GitHub releases
Creates a dedicated pullbase service user with security restrictions
Configures /etc/pullbase/agent.env with your server URL and token
Installs a hardened systemd service
Starts the agent immediately

Generate the install command from the UI: navigate to Servers → [your server] → Install to get a ready-to-run curl command with the token pre-filled.

Optional parameters:

Parameter	Description
`version`	Specific agent version (e.g., `v1.0.0`). Defaults to latest.
`ca_cert`	Base64-encoded CA certificate for custom TLS.

# Install specific version with custom CA
curl -fsSL "https://pullbase.example.com/api/v1/servers/web-01/install-script?token=pbt_xxx&version=v1.2.0&ca_cert=$(base64 -w0 ca.crt)" | sudo bash

Manual systemd setup

If you prefer manual control or need to customize the installation:

Download the agent binary

curl -fsSL -o pullbase-agent "https://github.com/pullbase/pullbase/releases/latest/download/pullbase-agent-linux-amd64"
sudo install -m 0755 pullbase-agent /usr/local/bin/pullbase-agent

Create environment file

sudo mkdir -p /etc/pullbase
sudo tee /etc/pullbase/agent.env > /dev/null <<'EOF'
SERVER_ID=web-01
CENTRAL_SERVER_URL=https://pullbase.example.com
AGENT_TOKEN=pbt_your_token_here
CACERT_PATH=/etc/pullbase/ca.crt
SKIP_TLS_VERIFY=false
EOF
sudo chmod 600 /etc/pullbase/agent.env

Create systemd unit

/etc/systemd/system/pullbase-agent.service

[Unit]
Description=Pullbase Agent
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/pullbase/agent.env
ExecStart=/usr/local/bin/pullbase-agent
Restart=always
RestartSec=10
User=root

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/etc /var

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable --now pullbase-agent.service
sudo systemctl status pullbase-agent.service

Environment variables

Variable	Required	Default	Description
`SERVER_ID`	Yes	-	Must match the server ID registered in Pullbase
`CENTRAL_SERVER_URL`	Yes	-	Base URL of the Pullbase API (e.g., `https://pullbase.example.com`)
`AGENT_TOKEN`	Yes	-	Token provided when the server is created. Rotate regularly.
`CACERT_PATH`	No	-	Path to CA bundle that trusts the Pullbase certificate
`SKIP_TLS_VERIFY`	No	`false`	Set to `true` only for development with self-signed certificates
`AGENT_DRY_RUN`	No	`false`	When `true`, agent reports what would change without applying

The agent also supports legacy environment variable names with PULLBASE_ prefix: PULLBASE_SERVER_ID, PULLBASE_SERVER_URL, PULLBASE_AGENT_TOKEN, PULLBASE_CACERT_PATH.

Dry-run mode

Run the agent in dry-run mode to preview changes without applying them:

# Via environment variable
AGENT_DRY_RUN=true pullbase-agent

# Via command-line flag
pullbase-agent --dry-run

In dry-run mode, the agent:

Checks for configuration drift
Logs what packages, files, and services would change
Reports status to the server with “Dry-Run:” prefix
Does not apply any changes

This is ideal for testing new configurations or auditing drift before enabling auto-reconcile.

Supported package managers

The agent auto-detects the host’s package manager:

Package Manager	Distribution	Detection
APK	Alpine Linux	Checks for `apk` command
APT	Debian, Ubuntu	Checks for `apt-get` command
DNF	RHEL 8+, Fedora, Rocky Linux	Checks for `dnf` command
YUM	RHEL 7, CentOS 7	Checks for `yum` command (fallback)

Package states:

present: Install if not present
latest: Install or upgrade to latest available version
absent: Remove if installed

Supported service managers

The agent auto-detects the init system:

Service Manager	Init System	Detection
systemd	Most modern distributions	Checks for `systemctl` and `/run/systemd/system`
supervisor	Docker, custom setups	Checks for `supervisorctl`
OpenRC	Alpine Linux, Gentoo	Checks for `rc-service`

Override detection by setting system.serviceManager in config.yaml:

system:
  serviceManager: supervisor
  containerized: true

Reconciliation cycle

Fetch configuration

Agent authenticates with its token and calls GET /api/v1/agent/serverinfo to obtain Git metadata and the target commit hash.

Obtain Git credentials

If the environment uses a GitHub App, agent invokes GET /api/v1/agent/git-token to retrieve a short-lived installation token.

Clone or update repository

Repository is cloned into /etc/pullbase/repo. The agent checks out the target commit.

Apply desired state

Packages, services, and files from config.yaml are reconciled using the detected package and service managers.

Report status

Agent posts results (status, drift, error message) to PUT /api/v1/agent/status.

Drift detection and auto-reconciliation

The agent performs drift checks every 60 seconds and compares:

Package installation state
Service running/enabled state
File content (SHA256 hash) and permissions

When drift is detected and auto-reconcile is enabled for the server’s environment, the agent automatically applies the configuration to restore desired state.

Logging

View agent logs using journalctl:

# Follow logs in real-time
journalctl -u pullbase-agent -f

# Last 100 lines
journalctl -u pullbase-agent -n 100

# Since last boot
journalctl -u pullbase-agent -b

The agent logs reconciliation details including:

Package installation/removal operations
Service start/stop/enable/disable operations
File writes and permission changes
Drift detection results
Git clone/pull operations

Troubleshooting

401 Unauthorized

Token revoked or expired → create a new token and update /etc/pullbase/agent.env
Server ID mismatch → ensure SERVER_ID matches the registered server
Clock skew → ensure NTP is running; JWT validation is time-based

Git clone failures

Check network reachability to GitHub (proxy, firewall)
For private repos, confirm the GitHub App installation and permissions
Validate CACERT_PATH so TLS trust is correct

Package manager errors

Ensure the package manager is available and in PATH
Check that package repositories are configured and reachable
Verify the agent runs as root (required for package management)

Service manager not detected

Override auto-detection by setting system.serviceManager in config.yaml
Ensure the service manager commands (systemctl, supervisorctl, rc-service) are in PATH
For systemd, verify /run/systemd/system exists

File permission issues

Specify mode in config.yaml (e.g., "0644")
Confirm the agent runs as root (required to manage system files)
Check SELinux/AppArmor policies if files are created but inaccessible

Agent not reporting status

Check connectivity: curl -I https://pullbase.example.com/api/v1/healthz
Verify token is active in the Pullbase UI
Check agent logs for authentication errors

Upgrading the agent

To upgrade an agent to a newer version:

# Stop the agent
sudo systemctl stop pullbase-agent

# Download new version
curl -fsSL -o /tmp/pullbase-agent "https://github.com/pullbase/pullbase/releases/latest/download/pullbase-agent-linux-amd64"
sudo install -m 0755 /tmp/pullbase-agent /usr/local/bin/pullbase-agent

# Start the agent
sudo systemctl start pullbase-agent

# Verify version in logs
journalctl -u pullbase-agent -n 5

Or re-run the install script — it handles upgrades automatically.

Uninstalling the agent

sudo systemctl stop pullbase-agent
sudo systemctl disable pullbase-agent
sudo rm /etc/systemd/system/pullbase-agent.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/pullbase-agent
sudo rm -rf /etc/pullbase

Foundations

Setup

Operations

Examples

Deployment methods

One-liner install script (recommended)

Manual systemd setup

Environment variables

Dry-run mode

Supported package managers

Supported service managers

Reconciliation cycle

Drift detection and auto-reconciliation

Logging

Troubleshooting

Upgrading the agent

Uninstalling the agent

​Deployment methods

​One-liner install script (recommended)

​Manual systemd setup

​Environment variables

​Dry-run mode

​Supported package managers

​Supported service managers

​Reconciliation cycle

​Drift detection and auto-reconciliation

​Logging

​Troubleshooting

​Upgrading the agent

​Uninstalling the agent

Deployment methods

One-liner install script (recommended)

Manual systemd setup

Environment variables

Dry-run mode

Supported package managers

Supported service managers

Reconciliation cycle

Drift detection and auto-reconciliation

Logging

Troubleshooting

Upgrading the agent

Uninstalling the agent