PAR Configuration Reference

Complete reference for the PAR (Pixell Agent Runtime) configuration file (config.yaml).

Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global

Overview

The PAR configuration file defines how the runtime manages agents, handles requests, and provides services. It's a YAML file that controls all aspects of the runtime behavior.

Configuration Structure

# PAR Configuration File (config.yaml)
runtime:
  name: "My PAR Runtime"
  version: "1.0.0"
  description: "Production PAR Runtime"
  
  # Runtime settings
  host: "0.0.0.0"
  port: 8080
  workers: 4
  
  # Security settings
  security:
    enabled: true
    auth_type: "jwt"
    jwt_secret: "${JWT_SECRET}"
    api_key: "${API_KEY}"
    cors_origins: ["*"]
  
  # Logging configuration
  logging:
    level: "info"
    format: "json"
    file: "/var/log/par/runtime.log"
    max_size: "100MB"
    max_files: 5
  
  # Health check settings
  health:
    enabled: true
    path: "/health"
    interval: 30
    timeout: 5
  
  # Metrics settings
  metrics:
    enabled: true
    path: "/metrics"
    port: 9090
    collect_interval: 60

# Agent management
agents:
  # Agent lifecycle settings
  lifecycle:
    startup_timeout: 30
    shutdown_timeout: 10
    health_check_interval: 30
    max_restart_attempts: 3
    restart_delay: 5
  
  # Agent resource limits
  resources:
    max_memory: "512MB"
    max_cpu: "1.0"
    max_disk: "1GB"
    max_network: "100Mbps"
  
  # Agent isolation settings
  isolation:
    enabled: true
    sandbox: true
    network_policy: "restricted"
    filesystem_policy: "readonly"

# API Gateway configuration
api_gateway:
  enabled: true
  host: "0.0.0.0"
  port: 8080
  
  # Routing configuration
  routing:
    default_agent: "main"
    fallback_agent: "fallback"
    route_by_header: "X-Agent-ID"
    route_by_path: true
  
  # Load balancing
  load_balancer:
    algorithm: "round_robin"
    health_check: true
    sticky_sessions: false
  
  # Rate limiting
  rate_limiting:
    enabled: true
    requests_per_minute: 1000
    burst_size: 100
    per_agent_limit: 100
  
  # Caching
  cache:
    enabled: true
    ttl: 300
    max_size: "100MB"
    strategy: "lru"

# Agent-to-Agent communication
a2a:
  enabled: true
  port: 50051
  
  # gRPC settings
  grpc:
    max_message_size: "4MB"
    keepalive_time: 30
    keepalive_timeout: 5
    keepalive_permit_without_calls: true
  
  # Service discovery
  discovery:
    enabled: true
    registry: "consul"
    registry_url: "http://localhost:8500"
    ttl: 30
    health_check_interval: 10
  
  # Message broker
  broker:
    enabled: true
    type: "redis"
    url: "redis://localhost:6379"
    channels:
      - "agent.events"
      - "agent.requests"
      - "agent.responses"

# Database configuration
database:
  enabled: true
  type: "postgresql"
  url: "${DATABASE_URL}"
  pool_size: 10
  max_overflow: 20
  pool_timeout: 30
  pool_recycle: 3600
  
  # Alternative: SQLite
  # type: "sqlite"
  # path: "/var/lib/par/runtime.db"

# Cache configuration
cache:
  enabled: true
  type: "redis"
  url: "redis://localhost:6379"
  ttl: 3600
  max_size: "1GB"
  
  # Alternative: In-memory
  # type: "memory"
  # max_size: "100MB"

# Monitoring and observability
monitoring:
  # Prometheus metrics
  prometheus:
    enabled: true
    port: 9090
    path: "/metrics"
    collect_interval: 60
  
  # Tracing
  tracing:
    enabled: true
    type: "jaeger"
    endpoint: "http://localhost:14268/api/traces"
    sample_rate: 0.1
  
  # Logging
  logging:
    enabled: true
    level: "info"
    format: "json"
    outputs:
      - type: "file"
        path: "/var/log/par/runtime.log"
        max_size: "100MB"
        max_files: 5
      - type: "syslog"
        host: "localhost"
        port: 514
        facility: "local0"
  
  # Alerting
  alerting:
    enabled: true
    webhook_url: "${ALERT_WEBHOOK_URL}"
    rules:
      - name: "high_error_rate"
        condition: "error_rate > 0.05"
        duration: "5m"
        severity: "warning"
      - name: "agent_down"
        condition: "agent_status == 'down'"
        duration: "1m"
        severity: "critical"

# Security configuration
security:
  # Authentication
  auth:
    enabled: true
    type: "jwt"
    jwt_secret: "${JWT_SECRET}"
    jwt_expiry: 3600
    refresh_token_expiry: 86400
  
  # Authorization
  authorization:
    enabled: true
    rbac:
      enabled: true
      roles:
        - name: "admin"
          permissions: ["*"]
        - name: "user"
          permissions: ["read", "write"]
        - name: "viewer"
          permissions: ["read"]
  
  # API Security
  api_security:
    enabled: true
    rate_limiting:
      enabled: true
      requests_per_minute: 1000
      burst_size: 100
    cors:
      enabled: true
      origins: ["*"]
      methods: ["GET", "POST", "PUT", "DELETE"]
      headers: ["*"]
    csrf:
      enabled: true
      secret: "${CSRF_SECRET}"
  
  # Network Security
  network:
    tls:
      enabled: false
      cert_file: "/etc/par/tls/cert.pem"
      key_file: "/etc/par/tls/key.pem"
    firewall:
      enabled: true
      rules:
        - action: "allow"
          source: "0.0.0.0/0"
          port: 8080
        - action: "deny"
          source: "10.0.0.0/8"
          port: 50051

# Storage configuration
storage:
  # Local storage
  local:
    enabled: true
    path: "/var/lib/par/storage"
    max_size: "10GB"
    cleanup_interval: 3600
  
  # Object storage
  object_storage:
    enabled: false
    type: "s3"
    endpoint: "https://s3.amazonaws.com"
    bucket: "par-storage"
    access_key: "${AWS_ACCESS_KEY}"
    secret_key: "${AWS_SECRET_KEY}"
    region: "us-east-1"

# Development settings
development:
  enabled: false
  hot_reload: true
  debug: false
  profiling: false
  mock_services: false

# Environment-specific overrides
environments:
  development:
    runtime:
      host: "localhost"
      port: 8080
      workers: 1
    logging:
      level: "debug"
    monitoring:
      prometheus:
        enabled: false
  
  staging:
    runtime:
      host: "0.0.0.0"
      port: 8080
      workers: 2
    logging:
      level: "info"
    monitoring:
      prometheus:
        enabled: true
  
  production:
    runtime:
      host: "0.0.0.0"
      port: 8080
      workers: 4
    logging:
      level: "warn"
    monitoring:
      prometheus:
        enabled: true
    security:
      auth:
        enabled: true

Configuration Sections

Runtime Configuration

Controls the core runtime behavior:

runtime:
  name: "My PAR Runtime"           # Runtime name
  version: "1.0.0"                # Runtime version
  description: "Production PAR"    # Runtime description
  
  host: "0.0.0.0"                 # Bind host
  port: 8080                      # Bind port
  workers: 4                      # Number of worker processes
  
  security:
    enabled: true                 # Enable security features
    auth_type: "jwt"              # Authentication type
    jwt_secret: "${JWT_SECRET}"   # JWT secret key
    api_key: "${API_KEY}"         # API key for authentication
    cors_origins: ["*"]           # CORS allowed origins
  
  logging:
    level: "info"                 # Log level
    format: "json"                # Log format
    file: "/var/log/par/runtime.log"  # Log file path
    max_size: "100MB"             # Max log file size
    max_files: 5                  # Max number of log files
  
  health:
    enabled: true                 # Enable health checks
    path: "/health"               # Health check endpoint
    interval: 30                  # Health check interval (seconds)
    timeout: 5                    # Health check timeout (seconds)
  
  metrics:
    enabled: true                 # Enable metrics collection
    path: "/metrics"              # Metrics endpoint
    port: 9090                    # Metrics server port
    collect_interval: 60          # Metrics collection interval

Agent Management

Controls how agents are managed:

agents:
  lifecycle:
    startup_timeout: 30           # Agent startup timeout (seconds)
    shutdown_timeout: 10          # Agent shutdown timeout (seconds)
    health_check_interval: 30     # Health check interval (seconds)
    max_restart_attempts: 3       # Max restart attempts
    restart_delay: 5              # Delay between restarts (seconds)
  
  resources:
    max_memory: "512MB"           # Max memory per agent
    max_cpu: "1.0"                # Max CPU per agent
    max_disk: "1GB"               # Max disk per agent
    max_network: "100Mbps"        # Max network per agent
  
  isolation:
    enabled: true                 # Enable agent isolation
    sandbox: true                 # Enable sandboxing
    network_policy: "restricted"  # Network policy
    filesystem_policy: "readonly" # Filesystem policy

API Gateway

Controls the API gateway behavior:

api_gateway:
  enabled: true                   # Enable API gateway
  host: "0.0.0.0"                # Gateway host
  port: 8080                      # Gateway port
  
  routing:
    default_agent: "main"         # Default agent for requests
    fallback_agent: "fallback"    # Fallback agent
    route_by_header: "X-Agent-ID" # Route by header
    route_by_path: true           # Route by path
  
  load_balancer:
    algorithm: "round_robin"      # Load balancing algorithm
    health_check: true            # Enable health checks
    sticky_sessions: false        # Enable sticky sessions
  
  rate_limiting:
    enabled: true                 # Enable rate limiting
    requests_per_minute: 1000     # Requests per minute
    burst_size: 100               # Burst size
    per_agent_limit: 100          # Per-agent limit
  
  cache:
    enabled: true                 # Enable caching
    ttl: 300                      # Cache TTL (seconds)
    max_size: "100MB"             # Max cache size
    strategy: "lru"               # Cache strategy

Agent-to-Agent Communication

Controls A2A communication:

a2a:
  enabled: true                   # Enable A2A communication
  port: 50051                     # A2A port
  
  grpc:
    max_message_size: "4MB"       # Max message size
    keepalive_time: 30            # Keepalive time (seconds)
    keepalive_timeout: 5          # Keepalive timeout (seconds)
    keepalive_permit_without_calls: true
  
  discovery:
    enabled: true                 # Enable service discovery
    registry: "consul"            # Registry type
    registry_url: "http://localhost:8500"  # Registry URL
    ttl: 30                       # Service TTL (seconds)
    health_check_interval: 10     # Health check interval
  
  broker:
    enabled: true                 # Enable message broker
    type: "redis"                 # Broker type
    url: "redis://localhost:6379"  # Broker URL
    channels:                     # Message channels
      - "agent.events"
      - "agent.requests"
      - "agent.responses"

Database Configuration

Controls database connections:

database:
  enabled: true                   # Enable database
  type: "postgresql"              # Database type
  url: "${DATABASE_URL}"          # Database URL
  pool_size: 10                   # Connection pool size
  max_overflow: 20                # Max overflow connections
  pool_timeout: 30               # Pool timeout (seconds)
  pool_recycle: 3600              # Pool recycle time (seconds)

Cache Configuration

Controls caching behavior:

cache:
  enabled: true                   # Enable caching
  type: "redis"                   # Cache type
  url: "redis://localhost:6379"   # Cache URL
  ttl: 3600                       # Default TTL (seconds)
  max_size: "1GB"                 # Max cache size

Monitoring Configuration

Controls monitoring and observability:

monitoring:
  prometheus:
    enabled: true                 # Enable Prometheus metrics
    port: 9090                    # Metrics port
    path: "/metrics"              # Metrics path
    collect_interval: 60          # Collection interval
  
  tracing:
    enabled: true                 # Enable tracing
    type: "jaeger"                 # Tracing type
    endpoint: "http://localhost:14268/api/traces"  # Tracing endpoint
    sample_rate: 0.1              # Sample rate
  
  logging:
    enabled: true                 # Enable logging
    level: "info"                 # Log level
    format: "json"                # Log format
    outputs:                      # Log outputs
      - type: "file"
        path: "/var/log/par/runtime.log"
        max_size: "100MB"
        max_files: 5
      - type: "syslog"
        host: "localhost"
        port: 514
        facility: "local0"
  
  alerting:
    enabled: true                 # Enable alerting
    webhook_url: "${ALERT_WEBHOOK_URL}"  # Alert webhook
    rules:                        # Alert rules
      - name: "high_error_rate"
        condition: "error_rate > 0.05"
        duration: "5m"
        severity: "warning"
      - name: "agent_down"
        condition: "agent_status == 'down'"
        duration: "1m"
        severity: "critical"

Security Configuration

Controls security features:

security:
  auth:
    enabled: true                 # Enable authentication
    type: "jwt"                   # Authentication type
    jwt_secret: "${JWT_SECRET}"   # JWT secret
    jwt_expiry: 3600              # JWT expiry (seconds)
    refresh_token_expiry: 86400   # Refresh token expiry
  
  authorization:
    enabled: true                 # Enable authorization
    rbac:
      enabled: true               # Enable RBAC
      roles:                      # Role definitions
        - name: "admin"
          permissions: ["*"]
        - name: "user"
          permissions: ["read", "write"]
        - name: "viewer"
          permissions: ["read"]
  
  api_security:
    enabled: true                 # Enable API security
    rate_limiting:
      enabled: true               # Enable rate limiting
      requests_per_minute: 1000   # Requests per minute
      burst_size: 100             # Burst size
    cors:
      enabled: true               # Enable CORS
      origins: ["*"]              # Allowed origins
      methods: ["GET", "POST", "PUT", "DELETE"]  # Allowed methods
      headers: ["*"]              # Allowed headers
    csrf:
      enabled: true               # Enable CSRF protection
      secret: "${CSRF_SECRET}"    # CSRF secret
  
  network:
    tls:
      enabled: false              # Enable TLS
      cert_file: "/etc/par/tls/cert.pem"  # Certificate file
      key_file: "/etc/par/tls/key.pem"    # Key file
    firewall:
      enabled: true               # Enable firewall
      rules:                      # Firewall rules
        - action: "allow"
          source: "0.0.0.0/0"
          port: 8080
        - action: "deny"
          source: "10.0.0.0/8"
          port: 50051

Storage Configuration

Controls storage behavior:

storage:
  local:
    enabled: true                 # Enable local storage
    path: "/var/lib/par/storage"   # Storage path
    max_size: "10GB"              # Max storage size
    cleanup_interval: 3600        # Cleanup interval (seconds)
  
  object_storage:
    enabled: false                # Enable object storage
    type: "s3"                    # Storage type
    endpoint: "https://s3.amazonaws.com"  # Storage endpoint
    bucket: "par-storage"         # Storage bucket
    access_key: "${AWS_ACCESS_KEY}"  # Access key
    secret_key: "${AWS_SECRET_KEY}"  # Secret key
    region: "us-east-1"           # Storage region

Environment Variables

PAR supports environment variable substitution in configuration:

Variable	Description	Default
PAR_CONFIG	Path to config file	./config.yaml
PAR_ENV	Environment name	development
PAR_LOG_LEVEL	Log level	info
PAR_DEBUG	Debug mode	false
PAR_HOST	Runtime host	0.0.0.0
PAR_PORT	Runtime port	8080
PAR_WORKERS	Number of workers	4
JWT_SECRET	JWT secret key	-
API_KEY	API key	-
DATABASE_URL	Database URL	-
REDIS_URL	Redis URL	-
ALERT_WEBHOOK_URL	Alert webhook URL	-

Configuration Validation

PAR validates the configuration file on startup:

# Validate configuration
par validate config.yaml

# Validate with specific environment
par validate config.yaml --env production

# Validate with custom schema
par validate config.yaml --schema custom-schema.json

Configuration Examples

Development Configuration

runtime:
  name: "Development PAR"
  host: "localhost"
  port: 8080
  workers: 1

logging:
  level: "debug"
  format: "text"

monitoring:
  prometheus:
    enabled: false

development:
  enabled: true
  hot_reload: true
  debug: true

Production Configuration

runtime:
  name: "Production PAR"
  host: "0.0.0.0"
  port: 8080
  workers: 4

logging:
  level: "warn"
  format: "json"
  file: "/var/log/par/runtime.log"

monitoring:
  prometheus:
    enabled: true
  tracing:
    enabled: true
  alerting:
    enabled: true

security:
  auth:
    enabled: true
  authorization:
    enabled: true
  api_security:
    enabled: true

High Availability Configuration

runtime:
  name: "HA PAR"
  host: "0.0.0.0"
  port: 8080
  workers: 8

agents:
  lifecycle:
    max_restart_attempts: 5
    restart_delay: 10

api_gateway:
  load_balancer:
    algorithm: "least_connections"
    health_check: true
    sticky_sessions: true

a2a:
  discovery:
    enabled: true
    registry: "consul"
  broker:
    enabled: true
    type: "redis"

monitoring:
  prometheus:
    enabled: true
  tracing:
    enabled: true
  alerting:
    enabled: true
    rules:
      - name: "agent_failure"
        condition: "agent_status == 'down'"
        duration: "30s"
        severity: "critical"

Troubleshooting

Common Configuration Issues

1. Invalid YAML Syntax

Problem: Configuration file has invalid YAML syntax Solutions:

• Use YAML validator: par validate config.yaml
• Check indentation (use spaces, not tabs)
• Verify quotes around strings
• Check for missing colons

2. Missing Required Fields

Problem: Required configuration fields are missing Solutions:

• Check configuration schema
• Use par validate to identify missing fields
• Review default values
• Check environment variable substitution

3. Invalid Values

Problem: Configuration values are invalid Solutions:

• Check value types (string, number, boolean)
• Verify enum values
• Check numeric ranges
• Validate URLs and paths

Configuration Debugging

Enable debug mode for detailed configuration information:

# Run with debug logging
par start --debug

# Validate with verbose output
par validate config.yaml --verbose

# Show effective configuration
par config show --env production

Next Steps

After configuring PAR:

1. Environment Variables - Set up environment variables
2. APKG Schema - Understand agent package format
3. PAK CLI Reference - Use PAK to build and deploy agents
4. Full Deployment Guide - Complete deployment

---

Ready to configure PAR? Check out Environment Variables to set up your environment!