Skip to main content
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:
ServerStatusLast Seen
test-server-1AppliedJust now
test-server-2AppliedJust 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

  1. Go to Servers → Create Server
  2. Enter a server ID (e.g., web-01) and name
  3. Select an environment
  4. Click Create
  5. Go to the server’s Tokens tab and create a token
  6. 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

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