Agent overview

The GoRules Agent is a standalone Rust microservice that evaluates decisions via REST API. It pulls releases from object storage, automatically reloads when changes occur, and requires no UI.

Docker Image

Available on Docker Hub: gorules/agent

When to use the Agent

Choose Agent when:

Multiple services need to evaluate the same rules
You want to update rules without redeploying applications
You need REST API access to rule evaluation
You want centralized metrics and observability

Consider alternatives when:

You need sub-millisecond latency (use embedded SDK)
You’re in a single-service architecture (embedded may be simpler)

Architecture

Custom Docker image

Build a self-contained image with your rules baked in. This is useful for static rules that don’t change frequently, or for deployments where you want versioned rule images.

FROM gorules/agent:latest

COPY ./rules /data

ENV PROVIDER__TYPE=Filesystem
ENV PROVIDER__ROOT_DIR=/data

EXPOSE 8080
CMD ["./app"]

Build and run:

docker build -t my-rules-api .
docker run -p 8080:8080 my-rules-api

This creates a portable REST API with your rules embedded. Deploy it anywhere containers run.

Environment variables

AWS S3

If your deployment supports IAM roles, credentials are optional.

PROVIDER__TYPE=S3
PROVIDER__BUCKET=my-rules-bucket
PROVIDER__PREFIX=staging              # Optional bucket prefix
AWS_ACCESS_KEY_ID=<access-key>        # Optional with IAM
AWS_SECRET_ACCESS_KEY=<secret-key>    # Optional with IAM

Azure Blob Storage

PROVIDER__TYPE=AzureStorage
PROVIDER__CONNECTION_STRING=<connection-string>
PROVIDER__CONTAINER=<container-name>
PROVIDER__PREFIX=staging              # Optional storage prefix

Google Cloud Storage

PROVIDER__TYPE=GCS
PROVIDER__BUCKET=<bucket-name>
PROVIDER__BASE64_CONTENTS=<base64-credential-contents>  # Optional with workload identity
PROVIDER__PREFIX=staging              # Optional bucket prefix

MinIO and S3-compatible storage

PROVIDER__TYPE=S3
PROVIDER__BUCKET=my-bucket
PROVIDER__FORCE_PATH_STYLE=true
PROVIDER__ENDPOINT=http://localhost:9000
PROVIDER__PREFIX=folder/              # Optional
AWS_ACCESS_KEY_ID=<access-key>
AWS_SECRET_ACCESS_KEY=<secret-key>

Local filesystem

PROVIDER__TYPE=Filesystem
PROVIDER__ROOT_DIR=./data             # Default: data

Zip file

PROVIDER__TYPE=Zip
PROVIDER__ROOT_DIR=./data             # Default: data

Additional options

POLL_INTERVAL=5000                    # Polling interval in ms (min: 1000, default: 5000)
CORS_PERMISSIVE=true                  # Enable permissive CORS (default: false)
RELEASE_ZIP_PASSWORD=<password>       # Optional password for encrypted releases

HTTPS configuration

HTTP_SSL__CERT=<base64-ssl-certificate>
HTTP_SSL__KEY=<base64-ssl-key>

Health probes

Path: /api/health Port: 8080 Recommended probe configuration:

Setting	Value
Initial delay	3 seconds
Period	10 seconds

Hot reloading

The Agent automatically detects rule changes and reloads without downtime:

Agent polls storage at POLL_INTERVAL (default: 5000ms)
Detects new or modified rule files
Loads new version in background
Atomically swaps to new version
Requests in-flight complete with old version

No requests are dropped during reload.

Observability

OpenTelemetry

Enable OpenTelemetry with OTEL_ENABLED=true. When enabled, standard OTEL environment variables are supported:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=gorules-agent
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

See the OpenTelemetry documentation for all available options.

Logging

Structured JSON logs:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "info",
  "message": "Decision evaluated",
  "decision": "pricing",
  "duration_ms": 0.23
}

API reference

See the API reference for endpoint documentation.

Overview

AI & Tools

Deployment

Platform Guides

SDKs

Big Data

JDM

Docker Image

When to use the Agent

Architecture

Custom Docker image

Environment variables

AWS S3

Azure Blob Storage

Google Cloud Storage

MinIO and S3-compatible storage

Local filesystem

Zip file

Additional options

HTTPS configuration

Health probes

Hot reloading

Observability

OpenTelemetry

Logging

API reference

Docker Image

​When to use the Agent

​Architecture

​Custom Docker image

​Environment variables

​AWS S3

​Azure Blob Storage

​Google Cloud Storage

​MinIO and S3-compatible storage

​Local filesystem

​Zip file

​Additional options

​HTTPS configuration

​Health probes

​Hot reloading

​Observability

​OpenTelemetry

​Logging

​API reference

When to use the Agent

Architecture

Custom Docker image

Environment variables

AWS S3

Azure Blob Storage

Google Cloud Storage

MinIO and S3-compatible storage

Local filesystem

Zip file

Additional options

HTTPS configuration

Health probes

Hot reloading

Observability

OpenTelemetry

Logging

API reference