> ## 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.
# Agent overview
> High-performance REST API for rule evaluation with hot reloading.
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.
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](/developers/deployment/embedded))
* You're in a single-service architecture (embedded may be simpler)
## Architecture
```mermaid theme={null}
flowchart TB
svcA["Service A"] --> agent
svcB["Service B"] --> agent
svcC["Service C"] --> agent
agent["GoRules Agent
(REST API)"]
storage["Rules Storage
(S3, GCS, Azure, Local)"]
agent <--> storage
```
## 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.
```dockerfile theme={null}
FROM gorules/agent:latest
COPY ./rules /data
ENV PROVIDER__TYPE=Filesystem
ENV PROVIDER__ROOT_DIR=/data
EXPOSE 8080
CMD ["./app"]
```
Build and run:
```bash theme={null}
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.
```shell theme={null}
PROVIDER__TYPE=S3
PROVIDER__BUCKET=my-rules-bucket
PROVIDER__PREFIX=staging # Optional bucket prefix
AWS_ACCESS_KEY_ID= # Optional with IAM
AWS_SECRET_ACCESS_KEY= # Optional with IAM
```
### Azure Blob Storage
```shell theme={null}
PROVIDER__TYPE=AzureStorage
PROVIDER__CONNECTION_STRING=
PROVIDER__CONTAINER=
PROVIDER__PREFIX=staging # Optional storage prefix
```
### Google Cloud Storage
```shell theme={null}
PROVIDER__TYPE=GCS
PROVIDER__BUCKET=
PROVIDER__BASE64_CONTENTS= # Optional with workload identity
PROVIDER__PREFIX=staging # Optional bucket prefix
```
### MinIO and S3-compatible storage
```shell theme={null}
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=
AWS_SECRET_ACCESS_KEY=
```
### Local filesystem
```shell theme={null}
PROVIDER__TYPE=Filesystem
PROVIDER__ROOT_DIR=./data # Default: data
```
### Zip file
```shell theme={null}
PROVIDER__TYPE=Zip
PROVIDER__ROOT_DIR=./data # Default: data
```
### Additional options
```shell theme={null}
POLL_INTERVAL=5000 # Polling interval in ms (min: 1000, default: 5000)
CORS_PERMISSIVE=true # Enable permissive CORS (default: false)
RELEASE_ZIP_PASSWORD= # Optional password for encrypted releases
```
### HTTPS configuration
```shell theme={null}
HTTP_SSL__CERT=
HTTP_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:
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:
```shell theme={null}
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](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) for all available options.
### Logging
Structured JSON logs:
```json theme={null}
{
"timestamp": "2025-01-15T10:30:00Z",
"level": "info",
"message": "Decision evaluated",
"decision": "pricing",
"duration_ms": 0.23
}
```
## API reference
See the [API reference](/api-reference/introduction) for endpoint documentation.