Quickstart

This guide gets you from zero to a working Pullbase setup with agents reporting status. By the end, you’ll have:

A running Pullbase server with database
An admin account
Two demo agents reporting their status

Time estimate: 5 minutes

Prerequisites

Docker 24.0+ with the Compose plugin (docker compose)
Git to clone the repository
A terminal (macOS, Linux, or WSL)

This quickstart is for evaluation only. It uses Docker to run demo agents for testing purposes.For production:

Deploy the central server using Docker or bare-metal
Install agents natively on your Linux servers using the install script — never run production agents in containers

Step 1: Clone and start Pullbase

git clone https://github.com/pullbase/pullbase.git
cd pullbase
docker compose up -d

This starts:

PostgreSQL database
Pullbase server (API + dashboard)
Two demo agents (test-server-1, test-server-2)

Wait for the stack to be healthy (about 60 seconds):

docker compose ps

You should see all services with status healthy or running.

Step 2: Verify the server is running

curl http://localhost:8080/api/v1/healthz

Expected output:

{"status":"healthy","service":"pullbase-server"}

Step 3: Bootstrap your admin account

Pullbase generates a one-time bootstrap secret on first start. Retrieve it and create your admin:

# Get the bootstrap secret
docker compose exec central-server cat /app/secrets/bootstrap.secret

# Create admin (replace YOUR_SECRET with the value above)
docker compose exec central-server pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret "YOUR_SECRET" \
  --username admin \
  --password 'SecurePassword123!'

You should see:

Admin bootstrap completed successfully.
Username: admin
Access token (store securely):
eyJhbGciOiJIUzI1NiIs...

Save the access token! You’ll need it for CLI commands. The bootstrap secret is invalidated after use.

Step 4: Open the dashboard

Visit http://localhost:8080 in your browser and sign in with:

Username: admin
Password: SecurePassword123! (or whatever you chose)

You should see the Pullbase dashboard with:

A sidebar showing “Environments” and “Servers”
The demo environment and servers from the seeded data

Step 5: Watch agents come online

Navigate to Servers in the sidebar. Within 60 seconds, you should see:

Server	Status	Last Seen
test-server-1	Applied	Just now
test-server-2	Applied	Just now

The agents are pulling configuration from the demo environment and reporting their status. Congratulations! You have a working Pullbase installation.

Next: Add your own server

Now that you’ve seen Pullbase working, here’s how to add a real server.

Option A: Using the UI

Go to Servers → Create Server
Enter a server ID (e.g., web-01) and name
Select an environment
Click Create
Go to the server’s Tokens tab and create a token
Copy the install command and run it on your target server

Option B: Using the CLI

# Set your server URL and token
export PULLBASE_URL=http://localhost:8080
export PULLBASE_TOKEN=<your-access-token-from-step-3>

# Create a server
docker compose exec central-server pullbasectl servers create \
  --server-url $PULLBASE_URL \
  --admin-token $PULLBASE_TOKEN \
  --id web-01 \
  --name "Web Server 01" \
  --environment-id 1

# Create an agent token
docker compose exec central-server pullbasectl tokens create \
  --server-url $PULLBASE_URL \
  --admin-token $PULLBASE_TOKEN \
  --server-id web-01 \
  --description "initial token"

The token output includes an install command you can run on your target server.

Install the agent on your server

On your target Linux server (VM, bare-metal, or cloud instance):

curl -fsSL "http://YOUR_PULLBASE_HOST:8080/api/v1/servers/web-01/install-script?token=YOUR_TOKEN" | sudo bash

For production, always use HTTPS. See Security Hardening for TLS setup.

What’s next?

Create environments

Group servers and link them to Git repositories

Write config.yaml

Define packages, services, and files to manage

Production deployment

Deploy Pullbase on real infrastructure with TLS

CLI Guide

Master the CLI for automation and workflows

Troubleshooting

docker compose up fails

Ensure Docker is running: docker info
Check if port 8080 is available: lsof -i :8080
Check if port 5432 is available: lsof -i :5432
View logs: docker compose logs -f

Bootstrap secret not found

The secret file is created on first boot. Wait 30 seconds after docker compose up and try again:

docker compose exec central-server cat /app/secrets/bootstrap.secret

Agents not showing up

Check agent logs: docker compose logs test-server-1
Agents report every 60 seconds — wait and refresh
Verify the central-server is healthy: curl http://localhost:8080/api/v1/healthz

Cannot access localhost:8080

Ensure the central-server is running: docker compose ps
Check for errors: docker compose logs central-server
Try the healthcheck: docker compose exec central-server wget -qO- http://localhost:8080/api/v1/healthz

Clean up

To stop and remove all containers and data:

docker compose down -v

This removes:

All containers
The PostgreSQL data volume
Generated certificates

Foundations

Setup

Operations

Examples

Prerequisites

Step 1: Clone and start Pullbase

Step 2: Verify the server is running

Step 3: Bootstrap your admin account

Step 4: Open the dashboard

Step 5: Watch agents come online

Next: Add your own server

Option A: Using the UI

Option B: Using the CLI

Install the agent on your server

What’s next?

Create environments

Write config.yaml

Production deployment

CLI Guide

Troubleshooting

Clean up

​Prerequisites

​Step 1: Clone and start Pullbase

​Step 2: Verify the server is running

​Step 3: Bootstrap your admin account

​Step 4: Open the dashboard

​Step 5: Watch agents come online

​Next: Add your own server

​Option A: Using the UI

​Option B: Using the CLI

​Install the agent on your server

​What’s next?

Create environments

Write config.yaml

Production deployment

CLI Guide

​Troubleshooting

​Clean up

Prerequisites

Step 1: Clone and start Pullbase

Step 2: Verify the server is running

Step 3: Bootstrap your admin account

Step 4: Open the dashboard

Step 5: Watch agents come online

Next: Add your own server

Option A: Using the UI

Option B: Using the CLI

Install the agent on your server

What’s next?

Troubleshooting

Clean up