Peerimeter
Peerimeter control plane

Host the API.
Keep control of your config.

Peerimeter Service is a small Go HTTP API for storing and exchanging network and node configuration with Peerimeter agents. Run it from source for a quick start, or deploy the multi-architecture container with Docker Compose.

Simple setup: run from source

This starts the service in the foreground on the local machine. It is useful for a small single-host installation or for trying the API.

  1. Install the Go version listed in the repository’s .go-version, then clone the repository.
git clone https://github.com/peerimeter/peerimeter-service.git
cd peerimeter-service
go build -trimpath -o peerimeter-service ./cmd/peerimeter-service
  1. Set a unique key, the persistent JSON file path, and the public HTTPS URL agents will use. The data directory is created when the service first saves configuration.
install -d -m 700 "$HOME/.local/share/peerimeter"
export PEERIMETER_API_KEY="$(openssl rand -hex 32)"
export PEERIMETER_DATA_FILE="$HOME/.local/share/peerimeter/config.json"
export PEERIMETER_PUBLIC_API_URL="https://service.example.com"
./peerimeter-service > service.log 2>&1 &
SERVICE_PID=$!
trap 'kill "$SERVICE_PID"' EXIT
SERVICE_READY=0
for attempt in $(seq 1 30); do
  if curl --max-time 1 --fail --silent http://127.0.0.1:8080/healthz >/dev/null; then
    SERVICE_READY=1
    break
  fi
  sleep 1
done
if [ "$SERVICE_READY" -eq 1 ]; then
  curl --max-time 2 --fail http://127.0.0.1:8080/healthz
  curl --max-time 5 --fail -H "Authorization: Bearer $PEERIMETER_API_KEY" \
    http://127.0.0.1:8080/api/v1/join-bundle
else
  echo "Service did not become ready; see service.log" >&2
  cat service.log
fi
The example starts the service in the background so the same shell retains the API key for the local checks. Keep the key available to the service across restarts and provide the same key to agents through their join bundle. For a persistent deployment, store these values in your service manager’s protected environment file. Keep the default listen address on loopback when a local HTTPS reverse proxy forwards to the service.

Check the service

The commands above check the local source setup over loopback HTTP. Once an HTTPS reverse proxy is configured, verify its public URL with these additional checks:

curl --fail https://service.example.com/healthz
curl --fail -H "Authorization: Bearer $PEERIMETER_API_KEY" \
  https://service.example.com/api/v1/join-bundle

Agents can use config pull and config push to exchange network and node config files. This is explicit, one-shot transfer; the service does not automatically reconcile agent runtime state.

Docker Compose setup

The published image targets Linux amd64 and arm64 and runs as the unprivileged app user (UID/GID 1000). Select a versioned image tag from the service’s GitHub releases.

  1. Create a deployment directory, persistent data directory, and environment file.
mkdir -p peerimeter-service/data
cd peerimeter-service
sudo install -d -o 1000 -g 1000 data
umask 077
cat > .env <<'EOF'
SERVICE_IMAGE_TAG=replace-with-a-release-tag
PEERIMETER_API_KEY=replace-with-a-unique-random-secret
PEERIMETER_PUBLIC_API_URL=https://service.example.com
EOF
chmod 600 .env

Generate a key with openssl rand -hex 32 and replace the example value. Choose an image tag published for a service release. The ownership command assumes rootful Docker. With rootless Docker, assign the data directory to the host IDs mapped to container UID/GID 1000: add 999 to the first subordinate UID in /etc/subuid and the first subordinate GID in /etc/subgid for your user. With Docker’s userns-remap, add 1000 to the first subordinate UID and GID values configured for the remapped user.

  1. Save this as compose.yaml alongside the environment file.
services:
  peerimeter-service:
    image: ghcr.io/peerimeter/peerimeter-service:${SERVICE_IMAGE_TAG:?Set a released SERVICE_IMAGE_TAG in .env}
    restart: unless-stopped
    env_file: .env
    environment:
      PEERIMETER_DATA_FILE: /var/lib/peerimeter/config.json
      PEERIMETER_LISTEN_ADDR: 0.0.0.0
      PORT: "8080"
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data:/var/lib/peerimeter
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
  1. Pull and start the service. Configure your HTTPS reverse proxy to forward to 127.0.0.1:8080.
docker compose pull
docker compose up -d
docker compose logs -f peerimeter-service
Persistent dataBack up ./data/config.json. The file contains the network and node configurations managed by the service.
Network exposureThe published port is bound to host loopback. Do not expose the service directly to the internet without HTTPS and an access boundary you trust.

What the initial service provides

HTTP APIAuthenticated pull and push endpoints for network and node JSON configuration.
Single-file storageWrites are serialized in memory and replace the JSON data file atomically within one process.
Shared credentialThe join bundle carries the API URL and the service-wide static API key.
Single instancePostgreSQL, MQTT coordination, user accounts, per-agent authorization, and multi-instance locking are not included.

Read the service README for the API contract, or visit the Peerimeter project site.