Configuration

Configure the Pixell Agent Runtime (PAR) with advanced settings for environment variables, configuration files, runtime modes, security, and performance optimization.

Configuration Methods

PAR supports multiple configuration methods with the following precedence (highest to lowest):

1. Command-line arguments - Override all other settings
2. Environment variables - Override config files
3. Configuration files - Default settings
4. Built-in defaults - Fallback values

Environment Variables

Runtime Configuration

Variable	Description	Default	Example
RUNTIME_MODE	Runtime mode: three-surface or multi-agent	three-surface	multi-agent
PORT	Main server port	8080	3000
ADMIN_PORT	Admin server port	9090	3001
HOST	Server host	localhost	0.0.0.0

Agent Configuration

Variable	Description	Default	Example
AGENT_PACKAGE_PATH	Path to APKG file (Three-Surface mode)	Required	./my-agent.apkg
MAX_AGENTS	Maximum agents (Multi-Agent mode)	20	50
AGENT_STORAGE_PATH	Agent storage directory	./agents	/var/agents

Logging Configuration

Variable	Description	Default	Example
LOG_LEVEL	Logging level	INFO	DEBUG
LOG_FORMAT	Log format: json or text	text	json
LOG_FILE	Log file path	stdout	./logs/par.log
DEBUG	Enable debug mode	false	true

Security Configuration

Variable	Description	Default	Example
API_KEY	API authentication key	None	your-secret-key
CORS_ORIGINS	Allowed CORS origins	*	https://app.com,https://api.com
JWT_SECRET	JWT signing secret	Auto-generated	your-jwt-secret
SSL_CERT_PATH	SSL certificate path	None	/path/to/cert.pem
SSL_KEY_PATH	SSL private key path	None	/path/to/key.pem

Performance Configuration

Variable	Description	Default	Example
MAX_WORKERS	Maximum worker processes	4	8
TIMEOUT	Request timeout (seconds)	30	60
MEMORY_LIMIT	Memory limit per agent	1GB	2GB
KEEPALIVE_TIMEOUT	Keep-alive timeout	5	10

Configuration Files

YAML Configuration

Create a par-config.yaml file:

# par-config.yaml
runtime:
  mode: three-surface  # or multi-agent
  host: localhost
  port: 8080
  admin_port: 9090
  workers: 4
  timeout: 30

agent:
  package_path: ./my-agent-0.1.0.apkg
  max_agents: 20
  storage_path: ./agents
  memory_limit: 1GB

logging:
  level: INFO
  format: json
  file: ./logs/par.log
  max_size: 100MB
  backup_count: 5

security:
  api_key: your-secret-key
  cors_origins:
    - http://localhost:3000
    - https://yourdomain.com
  jwt_secret: your-jwt-secret
  ssl:
    cert_path: /path/to/cert.pem
    key_path: /path/to/key.pem

performance:
  max_workers: 4
  timeout: 30
  memory_limit: 2GB
  keepalive_timeout: 5
  max_connections: 1000

monitoring:
  metrics: true
  health_check_interval: 30
  status_endpoint: /health
  metrics_endpoint: /metrics

storage:
  type: local  # or s3, gcs
  path: ./data
  backup_interval: 3600
  retention_days: 30

JSON Configuration

Create a par-config.json file:

{
  "runtime": {
    "mode": "three-surface",
    "host": "localhost",
    "port": 8080,
    "admin_port": 9090,
    "workers": 4,
    "timeout": 30
  },
  "agent": {
    "package_path": "./my-agent-0.1.0.apkg",
    "max_agents": 20,
    "storage_path": "./agents",
    "memory_limit": "1GB"
  },
  "logging": {
    "level": "INFO",
    "format": "json",
    "file": "./logs/par.log"
  },
  "security": {
    "api_key": "your-secret-key",
    "cors_origins": ["http://localhost:3000", "https://yourdomain.com"]
  },
  "performance": {
    "max_workers": 4,
    "timeout": 30,
    "memory_limit": "2GB"
  }
}

Runtime Modes

Three-Surface Mode

Single agent with all communication surfaces:

runtime:
  mode: three-surface
  host: localhost
  port: 8080

agent:
  package_path: ./my-agent-0.1.0.apkg
  memory_limit: 1GB

Features:

• 🌐 REST API - HTTP endpoints for web integration
• 🔗 A2A gRPC - Agent-to-agent communication
• 🎨 Web UI - Interactive user interface

Multi-Agent Mode

Platform for managing multiple agents:

runtime:
  mode: multi-agent
  host: 0.0.0.0
  port: 8080
  admin_port: 9090

agent:
  max_agents: 50
  storage_path: /var/agents
  memory_limit: 2GB

Features:

• 📊 Management API - Deploy and manage agents
• 🔗 A2A gRPC - Inter-agent communication
• 📈 Admin Dashboard - Monitoring and analytics

Security Configuration

API Authentication

security:
  api_key: your-secret-key
  jwt_secret: your-jwt-secret
  token_expiry: 3600

Usage:

# With API key
curl -H "X-API-Key: your-secret-key" http://localhost:8080/health

# With JWT token
curl -H "Authorization: Bearer your-jwt-token" http://localhost:8080/agents

CORS Configuration

security:
  cors_origins:
    - http://localhost:3000
    - https://app.yourdomain.com
    - https://api.yourdomain.com
  cors_methods: [GET, POST, PUT, DELETE]
  cors_headers: [Content-Type, Authorization]

SSL/TLS Configuration

security:
  ssl:
    enabled: true
    cert_path: /path/to/cert.pem
    key_path: /path/to/key.pem
    ca_path: /path/to/ca.pem
    verify_client: false

Performance Tuning

Worker Configuration

performance:
  max_workers: 8
  worker_class: uvicorn.workers.UvicornWorker
  worker_connections: 1000
  timeout: 30
  keepalive_timeout: 5

Memory Management

performance:
  memory_limit: 4GB
  agent_memory_limit: 512MB
  gc_threshold: 1000
  max_connections: 2000

Caching Configuration

performance:
  cache:
    enabled: true
    type: redis
    host: localhost
    port: 6379
    ttl: 3600

Logging Configuration

Log Levels

logging:
  level: DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL
  format: json   # json or text
  file: ./logs/par.log
  max_size: 100MB
  backup_count: 5

Structured Logging

logging:
  format: json
  fields:
    - timestamp
    - level
    - message
    - agent_id
    - request_id
    - duration

Log Rotation

logging:
  rotation:
    enabled: true
    max_size: 100MB
    backup_count: 5
    compress: true

Monitoring Configuration

Health Checks

monitoring:
  health_check:
    enabled: true
    interval: 30
    timeout: 5
    endpoints:
      - /health
      - /agent/status
      - /platform/status

Metrics

monitoring:
  metrics:
    enabled: true
    endpoint: /metrics
    format: prometheus
    interval: 10

Alerting

monitoring:
  alerts:
    enabled: true
    webhook_url: https://hooks.slack.com/your-webhook
    conditions:
      - metric: cpu_usage
        threshold: 80
        duration: 300
      - metric: memory_usage
        threshold: 90
        duration: 60

Storage Configuration

Local Storage

storage:
  type: local
  path: ./data
  backup_interval: 3600
  retention_days: 30

Cloud Storage

storage:
  type: s3
  bucket: your-par-bucket
  region: us-west-2
  access_key: your-access-key
  secret_key: your-secret-key

Database Storage

storage:
  type: postgresql
  host: localhost
  port: 5432
  database: par_db
  username: par_user
  password: par_password

Environment-Specific Configuration

Development Environment

# par-config.dev.yaml
runtime:
  mode: three-surface
  host: localhost
  port: 8080

logging:
  level: DEBUG
  format: text

security:
  api_key: dev-key
  cors_origins: ["http://localhost:3000"]

performance:
  max_workers: 2
  timeout: 60

Staging Environment

# par-config.staging.yaml
runtime:
  mode: multi-agent
  host: 0.0.0.0
  port: 8080

logging:
  level: INFO
  format: json
  file: /var/log/par.log

security:
  api_key: staging-key
  cors_origins: ["https://staging.yourdomain.com"]

performance:
  max_workers: 4
  timeout: 30

Production Environment

# par-config.prod.yaml
runtime:
  mode: multi-agent
  host: 0.0.0.0
  port: 8080

logging:
  level: WARNING
  format: json
  file: /var/log/par.log

security:
  api_key: ${PAR_API_KEY}
  cors_origins: ["https://yourdomain.com"]
  ssl:
    enabled: true
    cert_path: /etc/ssl/certs/par.crt
    key_path: /etc/ssl/private/par.key

performance:
  max_workers: 8
  timeout: 30
  memory_limit: 4GB

Configuration Validation

Validate Configuration

# Validate config file
pixell-runtime --config par-config.yaml --validate

# Check specific settings
pixell-runtime --config par-config.yaml --check security

Configuration Testing

# Test configuration without starting server
pixell-runtime --config par-config.yaml --dry-run

# Test with specific environment
PAR_ENV=production pixell-runtime --config par-config.yaml --dry-run

Advanced Configuration

Custom Middleware

middleware:
  - name: cors
    config:
      origins: ["https://yourdomain.com"]
  - name: rate_limit
    config:
      requests_per_minute: 100
  - name: auth
    config:
      required: true
      header: X-API-Key

Plugin Configuration

plugins:
  - name: metrics
    config:
      enabled: true
      endpoint: /metrics
  - name: tracing
    config:
      enabled: true
      service_name: par-runtime

Custom Routes

routes:
  - path: /custom/health
    handler: custom_health_check
    methods: [GET]
  - path: /custom/metrics
    handler: custom_metrics
    methods: [GET]

Troubleshooting Configuration

Common Issues

1. Invalid Configuration

Error: Invalid configuration: missing required field 'runtime.mode'

Solution:

# Ensure required fields are present
runtime:
  mode: three-surface  # Required field
  port: 8080

2. Port Conflicts

Error: Port 8080 already in use

Solution:

# Use different port
runtime:
  port: 3000
  admin_port: 3001

3. Permission Issues

Error: Permission denied: Cannot access log file

Solution:

# Fix file permissions
chmod 644 par-config.yaml
chown par:par par-config.yaml

Configuration Debugging

# Debug configuration loading
pixell-runtime --config par-config.yaml --debug

# Show effective configuration
pixell-runtime --config par-config.yaml --show-config

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

Best Practices

1. Environment-Specific Configs

# Use different configs per environment
pixell-runtime --config par-config.dev.yaml    # Development
pixell-runtime --config par-config.staging.yaml # Staging
pixell-runtime --config par-config.prod.yaml    # Production

2. Secret Management

# Use environment variables for secrets
security:
  api_key: ${PAR_API_KEY}
  jwt_secret: ${PAR_JWT_SECRET}

3. Configuration Validation

# Always validate before deployment
pixell-runtime --config par-config.yaml --validate

4. Monitoring Configuration

# Enable monitoring in production
monitoring:
  metrics: true
  health_check: true
  alerts: true

Next Steps

After configuring PAR:

1. REST Endpoints - Explore the REST API
2. gRPC Interface - Use A2A communication
3. Deployment - Deploy to production

---

Ready to explore the API? Check out REST Endpoints to learn about the REST API!