Up and running with qURL™ in minutes.

brew install layervai/tap/qurl
qurl version

# Download the latest Linux .deb for your architecture:
# https://github.com/layervai/qurl-integrations/releases/latest
# Save it as qurl.deb, then run these commands in that folder.
sudo dpkg -i ./qurl.deb
qurl version

# Download the latest Linux .rpm for your architecture:
# https://github.com/layervai/qurl-integrations/releases/latest
# Save it as qurl.rpm, then run these commands in that folder.
sudo rpm -U ./qurl.rpm
qurl version

# Download the archive for your OS and architecture from
# https://github.com/layervai/qurl-integrations/releases/latest
# darwin | linux | windows  ×  amd64 | arm64
# Extract it and put the qurl binary on your PATH.
qurl version

# Local publishing works on Windows, macOS, and Linux.

# 1 — Write the route config. The local port lives here, not in an env var.
cat > qurl-proxy-prod-dashboard.yaml <<'YAML'
routes:
  - type: http
    local_ip: 127.0.0.1
    local_port: 8080
YAML

# 2 — Create the state and secret directories. The runtime runs as UID/GID
#     65532, so it must own BOTH — it writes its identity into the state dir and
#     reads the token out of the secret dir. A root-owned 0700 dir the runtime
#     cannot traverse is the most common reason first start fails.
CONNECTOR_ID='prod-dashboard'
APP_CONTAINER='web'
SECRET_DIR="/run/secrets/qurl-connector/${CONNECTOR_ID}"
STATE_DIR="/var/lib/layerv/qurl-connector/${CONNECTOR_ID}/agent"
sudo install -d -m 0700 -o 65532 -g 65532 "$SECRET_DIR"
sudo install -d -m 0700 -o 65532 -g 65532 "$STATE_DIR"

# 3 — Stage the enrollment token in Bash. Run this line on its own.
#     Do not paste the whole block: queued terminal input can become the token.
read -rs -p 'Enrollment token: ' TOKEN < /dev/tty; printf '%s' "$TOKEN" | sudo tee "$SECRET_DIR/api_key" > /dev/null; sudo chown 65532:65532 "$SECRET_DIR/api_key"; sudo chmod 0400 "$SECRET_DIR/api_key"; unset TOKEN

# 4 — Run it. Replace vX.Y.Z with the immutable tag from your setup output.
docker run -d \
  --name "qurl-connector-${CONNECTOR_ID}" \
  --network "container:${APP_CONTAINER}" \
  --restart=on-failure:5 \
  -v "$STATE_DIR:/var/lib/layerv/agent" \
  -v "$SECRET_DIR:$SECRET_DIR:ro" \
  -v "$PWD/qurl-proxy-${CONNECTOR_ID}.yaml:/work/qurl-proxy.yaml:ro" \
  -e QURL_API_KEY_FILE="$SECRET_DIR/api_key" \
  -e QURL_CONNECTOR_ID="$CONNECTOR_ID" \
  ghcr.io/layervai/qurl-connector:vX.Y.Z

# qurl-proxy-prod-dashboard.yaml — mounted read-only below.
routes:
  - type: http
    local_ip: 127.0.0.1
    local_port: 8080

# Add to your Compose project. Replace vX.Y.Z with the immutable tag from
# your setup output. Before starting, create the host secret directory with
# mode 0700 and owner 65532:65532, then stage api_key with mode 0400 and the same owner.
services:
  qurl-connector-prod-dashboard:
    image: ghcr.io/layervai/qurl-connector:vX.Y.Z
    network_mode: "service:web"
    restart: on-failure
    environment:
      QURL_CONNECTOR_ID: "prod-dashboard"
      QURL_API_KEY_FILE: "/run/secrets/qurl-connector/prod-dashboard/api_key"
    volumes:
      - qurl-agent-prod-dashboard:/var/lib/layerv/agent
      - ./qurl-proxy-prod-dashboard.yaml:/work/qurl-proxy.yaml:ro
      - /run/secrets/qurl-connector/prod-dashboard:/run/secrets/qurl-connector/prod-dashboard:ro

volumes:
  qurl-agent-prod-dashboard:

# qurl-proxy.yaml — ship as a mounted file at /work/qurl-proxy.yaml.
routes:
  - type: http
    local_ip: 127.0.0.1
    local_port: 8080

# Add to the SAME task definition as the app container (awsvpc networking, so
# 127.0.0.1 reaches siblings). Mount EFS-backed state — one volume per running
# task, never shared. Replace vX.Y.Z with the immutable tag from your setup
# output. ECS injects QURL_API_KEY from its native task secrets.
{
  "name": "qurl-connector-prod-dashboard",
  "image": "ghcr.io/layervai/qurl-connector:vX.Y.Z",
  "environment": [
    { "name": "QURL_CONNECTOR_ID", "value": "prod-dashboard" }
  ],
  "secrets": [
    { "name": "QURL_API_KEY", "valueFrom": "<secrets-manager-arn>" }
  ],
  "mountPoints": [
    { "sourceVolume": "qurl-agent-state", "containerPath": "/var/lib/layerv/agent" },
    { "sourceVolume": "qurl-route-config", "containerPath": "/work", "readOnly": true }
  ]
}

# ConfigMap key qurl-proxy.yaml — mounted at /work below.
routes:
  - type: http
    local_ip: 127.0.0.1
    local_port: 8080

# Sidecar in the SAME Pod as the app container. One PVC per replica; for
# several replicas use a StatefulSet with volumeClaimTemplates. Replace vX.Y.Z
# with the immutable tag from your setup output.
containers:
  - name: qurl-connector-prod-dashboard
    image: ghcr.io/layervai/qurl-connector:vX.Y.Z
    env:
      - name: QURL_CONNECTOR_ID
        value: "prod-dashboard"
      - name: QURL_API_KEY_FILE
        value: /run/secrets/qurl-connector/api_key
    volumeMounts:
      - name: qurl-agent-state
        mountPath: /var/lib/layerv/agent
      - name: qurl-route-config
        mountPath: /work
        readOnly: true
      - name: qurl-enrollment-token
        mountPath: /run/secrets/qurl-connector
        readOnly: true
volumes:
  - name: qurl-agent-state
    persistentVolumeClaim:
      claimName: qurl-agent-prod-dashboard
  - name: qurl-route-config
    configMap:
      name: qurl-proxy-prod-dashboard
  - name: qurl-enrollment-token
    secret:
      secretName: qurl-enrollment-prod-dashboard
      items:
        - key: api_key
          path: api_key

# Follow the logs until they show a successful connection (Ctrl-C to stop).
docker logs -f qurl-connector-prod-dashboard

# Remove the enrollment token.
sudo rm -f /run/secrets/qurl-connector/prod-dashboard/api_key

# Keep the state directory. It holds the connector identity:
# /var/lib/layerv/qurl-connector/prod-dashboard/agent

# Follow the logs until they show a successful connection (Ctrl-C to stop).
docker compose logs -f qurl-connector-prod-dashboard

# Remove the enrollment token staged on the host.
sudo rm -f /run/secrets/qurl-connector/prod-dashboard/api_key

# Keep the named volume qurl-agent-prod-dashboard. It holds the connector identity.

# Follow the task's logs until they show a successful connection (Ctrl-C to stop).
# <log-group> is the connector container's awslogs-group in the task definition.
aws logs tail <log-group> --follow

# Remove the QURL_API_KEY entry from the task definition's "secrets" and
# deploy it, then delete the enrollment secret. Secrets Manager keeps it in
# a recovery window (30 days by default) before it is gone for good.
aws secretsmanager delete-secret --secret-id <secrets-manager-arn>

# Keep the EFS volume mounted at /var/lib/layerv/agent. It holds the
# connector identity.

# Follow the logs until they show a successful connection (Ctrl-C to stop).
kubectl logs -f <pod-name> -c qurl-connector-prod-dashboard

# Remove the qurl-enrollment-token volume and its mount from the Pod spec
# and roll it out, then delete the enrollment Secret.
kubectl delete secret qurl-enrollment-prod-dashboard

# Keep the PVC qurl-agent-prod-dashboard. It holds the connector identity.