Skip to main content
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

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:
ParameterDescription
versionSpecific agent version (e.g., v1.0.0). Defaults to latest.
ca_certBase64-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:
1

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
2

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
3

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
4

Enable and start

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

​
Environment variables

VariableRequiredDefaultDescription
SERVER_IDYes-Must match the server ID registered in Pullbase
CENTRAL_SERVER_URLYes-Base URL of the Pullbase API (e.g., https://pullbase.example.com)
AGENT_TOKENYes-Token provided when the server is created. Rotate regularly.
CACERT_PATHNo-Path to CA bundle that trusts the Pullbase certificate
SKIP_TLS_VERIFYNofalseSet to true only for development with self-signed certificates
AGENT_DRY_RUNNofalseWhen 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 ManagerDistributionDetection
APKAlpine LinuxChecks for apk command
APTDebian, UbuntuChecks for apt-get command
DNFRHEL 8+, Fedora, Rocky LinuxChecks for dnf command
YUMRHEL 7, CentOS 7Checks 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 ManagerInit SystemDetection
systemdMost modern distributionsChecks for systemctl and /run/systemd/system
supervisorDocker, custom setupsChecks for supervisorctl
OpenRCAlpine Linux, GentooChecks for rc-service
Override detection by setting system.serviceManager in config.yaml: 
system:
  serviceManager: supervisor
  containerized: true

​
Reconciliation cycle

1

Fetch configuration

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

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.
3

Clone or update repository

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

Apply desired state

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

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

  • 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
  • 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
  • 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)
  • 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
  • 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
  • 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