> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get Pullbase running and see your first servers come online in under 5 minutes.

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)

<Warning>
  **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](/deployment-bare-metal)
  * Install **agents natively** on your Linux servers using the [install script](/agent-operations#one-liner-install-script-recommended) — never run production agents in containers
</Warning>

## Step 1: Clone and start Pullbase

```bash theme={null}
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)

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

  ```bash theme={null}
  docker compose ps
  ```

  You should see all services with status `healthy` or `running`.
</Check>

## Step 2: Verify the server is running

```bash theme={null}
curl http://localhost:8080/api/v1/healthz
```

Expected output:

```json theme={null}
{"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:

```bash theme={null}
# 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!'
```

<Check>
  You should see:

  ```
  Admin bootstrap completed successfully.
  Username: admin
  Access token (store securely):
  eyJhbGciOiJIUzI1NiIs...
  ```
</Check>

<Warning>
  Save the access token! You'll need it for CLI commands. The bootstrap secret is invalidated after use.
</Warning>

## Step 4: Open the dashboard

Visit **[http://localhost:8080](http://localhost:8080)** in your browser and sign in with:

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

<Check>
  You should see the Pullbase dashboard with:

  * A sidebar showing "Environments" and "Servers"
  * The demo environment and servers from the seeded data
</Check>

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

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

```bash theme={null}
# 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):

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

<Warning>
  For production, always use HTTPS. See [Security Hardening](/security-hardening) for TLS setup.
</Warning>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Create environments" icon="layer-group" href="/environments-and-servers">
    Group servers and link them to Git repositories
  </Card>

  <Card title="Write config.yaml" icon="file-code" href="/configuration-repository">
    Define packages, services, and files to manage
  </Card>

  <Card title="Production deployment" icon="server" href="/deployment-bare-metal">
    Deploy Pullbase on real infrastructure with TLS
  </Card>

  <Card title="CLI Guide" icon="terminal" href="/guides/pullbasectl">
    Master the CLI for automation and workflows
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="Bootstrap secret not found">
    The secret file is created on first boot. Wait 30 seconds after `docker compose up` and try again:

    ```bash theme={null}
    docker compose exec central-server cat /app/secrets/bootstrap.secret
    ```
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

## Clean up

To stop and remove all containers and data:

```bash theme={null}
docker compose down -v
```

This removes:

* All containers
* The PostgreSQL data volume
* Generated certificates