Pace Setup

Set up and run pace

Install and launch a pace dashboard. Two paths: Bun for development, Docker for production.

Prerequisites

• Bun path: Bun v1.3+ installed
• Docker path: Docker and Docker Compose installed

Bun (development)

# Clone and install
git clone https://github.com/av/pace.git
cd pace
bun install

# Create config from the example
cp config.example.yaml config.yaml
# Edit config.yaml -- see skills/pace-config/SKILL.md for how to build one from scratch

# Start the dev server
bun run dev

The server starts at http://localhost:7453 by default.

CLI flags and commands

For the authoritative, version-accurate help text run:

pace --help

Commands overview:

Key options: -c/--config <path> (default ./config.yaml), -p/--port <number> (default 7453), -P/--preset <name> (use a bundled preset), -C/--chdir <dir> (change working directory for config and data loads).

Environment variables PACE_CONFIG (config file path), PORT (server port), and PACE_DB_PATH (SQLite database path, default data/pace.db) provide overrides; CLI flags take precedence over environment variables.

Server behavior is also configurable via an optional server: block in config.yaml: server.base_path (URL prefix for reverse-proxy deployments, e.g. /pace — works whether or not the proxy strips the prefix) and server.retention_days (prune items older than N days; default 30, 0 disables). See the "Server Configuration" section of the README for details and nginx examples.

Global install

cd pace
bun install && npm link
# Now `pace` is available globally
pace --config ~/my-config.yaml

The CLI always resolves paths relative to the project root (where package.json lives), so data/, node_modules/, and default config paths work regardless of shell cwd.

Docker (production)

Using Docker Compose

# Copy and edit config
cp config.example.yaml config.yaml

# Uncomment the config volume mount in docker-compose.yml (under x-data-volume):
#   # - ./config.yaml:/app/config.yaml:ro   # uncomment to use a custom config

docker compose up -d

Using Docker directly

docker build -t pace .
docker run -d \
  -p 7453:7453 \
  -v ./config.yaml:/app/config.yaml:ro \
  -v pace-data:/app/data \
  pace

Using the prebuilt image

The docker run -d invocation (including -p and volume mounts) is identical to the one under "Using Docker directly" above; simply replace the final image argument pace with ghcr.io/av/pace:latest (no docker build step is required).

The /app/data volume persists the SQLite database across container restarts.

The Docker image also contains the bundled agent skills. To inspect them without running the server:

docker run --rm ghcr.io/av/pace pace skill

Themed example configs

List the available presets directly:

pace presets list
# academic-papers
# daily-brief
# ml-ai
# product-launches
# release-tracker
# tech-news
# video-podcast

Launch with a preset:

# Bun:
pace --preset tech-news

# Docker:
docker run -d -p 7453:7453 -v pace-data:/app/data ghcr.io/av/pace:latest --preset tech-news

Copy a preset to config.yaml and customise it, then restart with your edited file (see skills/pace-config/SKILL.md for detailed editing guidance).

Beyond feeds: widgets, bookmarks, and counters

Layouts can include more than just content-feed panels. Three widget types let you embed static content directly into the layout tree without an adapter:

• Image widget - logos, banners, status badges (image: key)
• Text widget - notes, changelogs, instructions in plain, markdown, or html (text: key)
• Iframe widget - embedded external pages like Grafana dashboards (iframe: key)

Two special adapters complement these:

• Bookmarks - curated link lists defined in config (no network fetch)
• Counter - fetches a JSON endpoint and extracts a numeric value; pair with display: counter on the panel for stat-card rendering

See skills/pace-config/SKILL.md for full config reference and examples.

Verifying it works

1. Open http://localhost:7453 -- the dashboard should render with panel headers.
2. Content appears after the first adapter refresh cycle (within refresh_interval minutes, default 15).
3. To trigger an immediate refresh for a panel, POST to /refresh/<panel-id>.

curl -X POST http://localhost:7453/refresh/hackernews

4. For automated health checks (Docker, Kubernetes, load balancers), GET /health:

curl http://localhost:7453/health

Expected response: {"status":"ok"}

5. For machine-readable panel data (scripts, widgets, monitors), GET /api/panels (all panels with item counts) or /api/panels/<panel-id> (one panel's items as JSON; optional ?limit=N, 1-500):

curl http://localhost:7453/api/panels
curl http://localhost:7453/api/panels/hackernews?limit=5

Append .rss to the panel segment for the same items as an RSS 2.0 feed (for feed readers):

curl http://localhost:7453/api/panels/hackernews.rss

Common issues