HUG Server

The hug server is a standalone Node.js service that stores active reviews, serves the review UI, hosts real-time chat via WebSocket, and captures human verdicts. It requires PostgreSQL for storage.

The hug server is a necessary component to run teams that have Human Gates in their workflows.

The server is stateless at the process level — all review state lives in the database. Any server instance can serve any request. Multiple cliq instances can point to the same hug server.

---

Prerequisites

• Node.js 18+ (for npm) or Docker
• PostgreSQL 13+ — the schema is auto-created on first startup

---

Installation

Docker (recommended)

docker run -d --name hug-server \
  -p 3100:3100 \
  -e DATABASE_URL=postgres://user:pass@host:5432/hug \
  -e HUG_BEARER_TOKEN=your-secret-token \
  ghcr.io/elanamir/hug-server:latest

npm

npx @cliqhub/hug-server \
  --database-url postgres://user:pass@host:5432/hug \
  --bearer-token your-secret-token \
  --port 3100

Local development with Docker Postgres

If you don’t have a Postgres instance handy:

docker run -d --name hug-pg \
  -p 5433:5432 \
  -e POSTGRES_PASSWORD=hug \
  -e POSTGRES_DB=hug \
  postgres:16-alpine

npx @cliqhub/hug-server \
  --database-url postgres://postgres:hug@localhost:5433/hug \
  --bearer-token my-dev-token

Docker Compose

For production or when running alongside the cliq server:

services:
  hug-server:
    image: ghcr.io/elanamir/hug-server:latest
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      DATABASE_URL: postgres://user:pass@host:5432/hug
      HUG_BEARER_TOKEN: your-secret-token

---

CLI Reference

Flag	Env var	Default	Description
--database-url	DATABASE_URL	(required)	PostgreSQL connection string
--port	PORT	3100	HTTP port
--bearer-token	HUG_BEARER_TOKEN	(none)	Token for agent API authentication
--cors-origin	HUG_CORS_ORIGIN	(none)	CORS origin header (for cross-domain UIs)
--retention-days	HUG_RETENTION_DAYS	30	Days to keep completed/expired reviews before purging

Health check

curl http://localhost:3100/health
# {"status":"ok","service":"hug-server"}

---

Connecting Cliq to the Server

Add the server URL and token to ~/.cliqrc/settings.json:

{
    "hug": {
        "server_url": "http://localhost:3100",
        "token": "my-dev-token"
    }
}

The token must match the --bearer-token you started the server with. See Settings & Troubleshooting for the full HUG settings reference.

---

Review Lifecycle

Reviews follow a lifecycle managed by the server:

1. pending — awaiting a human verdict
2. decided — verdict submitted, agent hasn’t acknowledged yet
3. completed — agent acknowledged; review remains accessible as a read-only archive
4. purged — automatically deleted after --retention-days (default 30)

During the retention period, anyone with the review link can still view the verdict, comment, artifacts, and chat transcript. After the retention period, a background job purges old records hourly.

The permanent audit trail lives in .cliq/reviews/ on the cliq instance — see Audit Trail.

---

Scaling

The server is stateless — scale horizontally behind a load balancer. Use sticky sessions at the load balancer for WebSocket connections, or add a pub/sub layer for cross-instance relay.