Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gorules.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
SettingValue
Initial delay3 seconds
Period10 seconds

​
Hot reloading

The Agent automatically detects rule changes and reloads without downtime:
  1. Agent polls storage at POLL_INTERVAL (default: 5000ms)
  2. Detects new or modified rule files
  3. Loads new version in background
  4. Atomically swaps to new version
  5. 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.