Install the VeriProof Edge Gateway

Release 1.0.0 is available from VeriProof’s private GitLab container registry for Linux AMD64. Docker Desktop on Windows 11 must use Linux containers.

Use the same ingest server URL as your application. VeriProof matches the image’s policy verification key to that server. You do not configure signing keys. A portal address cannot be used as the ingest server address.

Pull the image

Use the read-only registry username and token supplied for your deployment. They are separate from your application key. In PowerShell, enter the token at Docker’s password prompt:

docker login registry.gitlab.com --username YOUR_REGISTRY_USERNAME
$image = 'registry.gitlab.com/veriproofsdk/edge-runtime@sha256:52ce61953639e8f47fb9a9e2f9623934536a7ced87261f5937b15643d8fe2502'
docker pull --platform linux/amd64 $image

For Bash on a Linux host:

docker login registry.gitlab.com --username YOUR_REGISTRY_USERNAME
image='registry.gitlab.com/veriproofsdk/edge-runtime@sha256:52ce61953639e8f47fb9a9e2f9623934536a7ced87261f5937b15643d8fe2502'
docker pull --platform linux/amd64 "$image"

The digest selects the tested image even if registry tags change. The equivalent tag is registry.gitlab.com/veriproofsdk/edge-runtime:1.0.0.

Configure your application

Use the same application SDK key and ingest server URL already configured in your application. Save the complete key in a file named application inside gateway-secrets. Do not split the key into separate values. Restrict this directory to your Docker account and keep it outside source control.

Create gateway.env with these two settings:

EdgeRuntime__ServerUrl=https://YOUR_INGEST_SERVER
EdgeRuntime__ApplicationKeyFile=/run/secrets/application

Replace the URL placeholder with your application’s ingest base URL, without an API route. The double underscores are part of each environment variable’s name. VeriProof identifies the tenant, application, and environment from your key and supplies the applicable rules automatically.

The gateway keeps its application binding in the journal volume for offline restarts. Changing the key or server URL requires a connection to VeriProof to resolve the binding again. Policy signatures and leases still control which rules the gateway can use.

Run the gateway

PowerShell

Run these commands in the directory containing gateway.env and gateway-secrets:

$secretDirectory = (Resolve-Path ./gateway-secrets).Path
docker volume create veriproof-edge-journal
docker run --detach --name veriproof-edge `
  --platform linux/amd64 --restart unless-stopped --stop-timeout 20 `
  --env-file ./gateway.env --publish 127.0.0.1:7080:8080 `
  --read-only --cap-drop ALL --security-opt no-new-privileges `
  --cpus 2 --memory 512m --pids-limit 128 `
  --tmpfs /tmp:rw,noexec,nosuid,size=64m `
  --mount "type=bind,source=$secretDirectory/application,target=/run/secrets/application,readonly" `
  --mount type=volume,source=veriproof-edge-journal,target=/var/lib/veriproof/edge `
  $image
Invoke-RestMethod http://127.0.0.1:7080/health/ready

Linux shell

Use the same gateway.env and complete key file. With standard Docker Engine on Linux, grant the image’s user access to that file:

sudo chown 1654:1654 ./gateway-secrets/application
sudo chmod 0400 ./gateway-secrets/application
secret_directory="$(cd ./gateway-secrets && pwd)"
docker volume create veriproof-edge-journal
docker run --detach --name veriproof-edge \
  --platform linux/amd64 --restart unless-stopped --stop-timeout 20 \
  --env-file ./gateway.env --publish 127.0.0.1:7080:8080 \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  --cpus 2 --memory 512m --pids-limit 128 \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --mount "type=bind,source=$secret_directory/application,target=/run/secrets/application,readonly" \
  --mount type=volume,source=veriproof-edge-journal,target=/var/lib/veriproof/edge \
  "$image"
curl --fail http://127.0.0.1:7080/health/ready

For rootless Docker or user-namespace remapping, grant file access to the mapped host UID for container user 1654 instead. Do not make the key world-readable. Readiness succeeds after the gateway downloads and verifies your application’s policies. Keep your SDK’s existing application key and server URL; set its Edge endpoint to http://127.0.0.1:7080. The gateway selects the application’s effective rules, including assigned group rules. Each gateway serves one application and environment.

The address above serves an agent running on the same host. For containerized agents, download the Compose example and save it as compose.yaml. It keeps the gateway listener on loopback and shares that network namespace with the agent.

Copy compose.yaml beside gateway.env and gateway-secrets. Set AGENT_IMAGE to your application image in a Compose .env file. Keep your application’s existing key and server configuration in the agent service. Set its SDK Edge endpoint to http://127.0.0.1:8080.

Run docker compose up -d --wait. Compose starts the agent after gateway readiness succeeds. Use docker compose ps to check health. The gateway publishes no host port in this example. Connections outside this shared namespace require TLS and an explicit network access policy.

Use one Compose project per application replica so each owns a separate journal. Keep the host’s Docker storage encrypted. docker compose down retains the journal; do not add --volumes while evidence remains undelivered. After replacing the gateway, run docker compose up -d --force-recreate for both services so the agent joins the current network namespace. A health failure does not itself restart a container; inspect gateway logs and configuration before restarting the pair.

Keep the journal volume when restarting or updating. Never share it between running gateways. Undelivered evidence remains queued; acknowledged payloads are removed after the five-minute reconciliation period. Automatic maintenance reuses freed database space. The central VeriProof system retains the long-term record.

Journal payloads and attachment reservations share a 1 GiB limit by default. EdgeRuntime__MaximumTotalPayloadBytes configures that limit. Leave additional volume space for database indexes, WAL, and recovery metadata. At capacity, the gateway rejects new work and preserves accepted evidence.

If readiness does not succeed, check the ingest server address and application SDK key. Contact your VeriProof administrator if these match. Never delete the journal volume to resolve a connection error.

Choose which work runs locally

The gateway serves one application and environment. Group rules assigned to that application are included automatically; developers do not select rule bundles.

Ordinary policy evaluations and background session evidence can use the gateway. Previews, delegated identity, human review, and shared controls remain central. The SDK follows an explicit policy handoff when central evaluation is required. A connection failure does not silently resend the action elsewhere.

Set your SDK’s Edge endpoint to the gateway address. Keep its existing application key and central ingest URL. Core SDKs support VERIPROOF_EDGE_ENDPOINT; follow your language’s configuration instructions when constructing clients or exporters directly. Framework adapters use their underlying SDK configuration.

A local receipt means the gateway has retained evidence durably. Central delivery may still be pending. Use that distinction when deciding whether your next step needs a central session result.

Operate the gateway

Administrators manage the application’s gateway entitlement and registry access. Developers configure the connection. Policy authors continue publishing rules in VeriProof.

Use the application-level execution location in the customer portal to see reported gateway or server activity. This describes the application’s reported route, not a stamp on every session.

Keep a persistent volume with each gateway. Do not share a SQLite journal between running containers. When storage fills, new work is rejected while already accepted evidence remains protected. Monitor readiness and storage capacity, and let the gateway deliver queued evidence before removing a deployment.