Environment Variables Reference

Complete reference for all environment variables used by Pixell components.

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

Pixell uses environment variables for configuration, secrets management, and runtime behavior. Variables are organized by component and functionality.

Core Pixell Variables

General Configuration

Variable	Description	Default	Required
PIXELL_ENV	Environment name (development, staging, production)	development	No
PIXELL_DEBUG	Enable debug mode	false	No
PIXELL_LOG_LEVEL	Log level (debug, info, warn, error)	info	No
PIXELL_VERBOSE	Enable verbose output	false	No
PIXELL_QUIET	Suppress output (except errors)	false	No
PIXELL_CONFIG	Path to configuration file	./config.yaml	No
PIXELL_DATA_DIR	Data directory path	./data	No
PIXELL_TEMP_DIR	Temporary directory path	./tmp	No

Security Variables

Variable	Description	Default	Required
PIXELL_SECRET_KEY	Master secret key	-	Yes
PIXELL_JWT_SECRET	JWT signing secret	-	Yes
PIXELL_API_KEY	API authentication key	-	No
PIXELL_CSRF_SECRET	CSRF protection secret	-	No
PIXELL_ENCRYPTION_KEY	Data encryption key	-	No
PIXELL_SESSION_SECRET	Session secret key	-	No

PAR (Pixell Agent Runtime) Variables

Runtime Configuration

Variable	Description	Default	Required
PAR_HOST	Runtime bind host	0.0.0.0	No
PAR_PORT	Runtime bind port	8080	No
PAR_WORKERS	Number of worker processes	4	No
PAR_NAME	Runtime name	PAR Runtime	No
PAR_VERSION	Runtime version	1.0.0	No
PAR_DESCRIPTION	Runtime description	-	No

Agent Management

Variable	Description	Default	Required
PAR_AGENT_STARTUP_TIMEOUT	Agent startup timeout (seconds)	30	No
PAR_AGENT_SHUTDOWN_TIMEOUT	Agent shutdown timeout (seconds)	10	No
PAR_AGENT_HEALTH_INTERVAL	Health check interval (seconds)	30	No
PAR_AGENT_MAX_RESTARTS	Maximum restart attempts	3	No
PAR_AGENT_RESTART_DELAY	Restart delay (seconds)	5	No
PAR_AGENT_MAX_MEMORY	Maximum memory per agent	512MB	No
PAR_AGENT_MAX_CPU	Maximum CPU per agent	1.0	No
PAR_AGENT_MAX_DISK	Maximum disk per agent	1GB	No
PAR_AGENT_MAX_NETWORK	Maximum network per agent	100Mbps	No

API Gateway

Variable	Description	Default	Required
PAR_API_HOST	API gateway host	0.0.0.0	No
PAR_API_PORT	API gateway port	8080	No
PAR_API_DEFAULT_AGENT	Default agent for requests	main	No
PAR_API_FALLBACK_AGENT	Fallback agent	fallback	No
PAR_API_ROUTE_HEADER	Route by header name	X-Agent-ID	No
PAR_API_ROUTE_PATH	Enable path-based routing	true	No
PAR_API_LOAD_BALANCER	Load balancing algorithm	round_robin	No
PAR_API_STICKY_SESSIONS	Enable sticky sessions	false	No
PAR_API_RATE_LIMIT	Requests per minute	1000	No
PAR_API_BURST_SIZE	Burst size	100	No
PAR_API_AGENT_LIMIT	Per-agent rate limit	100	No
PAR_API_CACHE_TTL	Cache TTL (seconds)	300	No
PAR_API_CACHE_SIZE	Cache size	100MB	No

Agent-to-Agent Communication

Variable	Description	Default	Required
PAR_A2A_ENABLED	Enable A2A communication	true	No
PAR_A2A_PORT	A2A port	50051	No
PAR_A2A_MAX_MESSAGE_SIZE	Maximum message size	4MB	No
PAR_A2A_KEEPALIVE_TIME	Keepalive time (seconds)	30	No
PAR_A2A_KEEPALIVE_TIMEOUT	Keepalive timeout (seconds)	5	No
PAR_A2A_DISCOVERY_ENABLED	Enable service discovery	true	No
PAR_A2A_DISCOVERY_REGISTRY	Registry type	consul	No
PAR_A2A_DISCOVERY_URL	Registry URL	http://localhost:8500	No
PAR_A2A_DISCOVERY_TTL	Service TTL (seconds)	30	No
PAR_A2A_BROKER_ENABLED	Enable message broker	true	No
PAR_A2A_BROKER_TYPE	Broker type	redis	No
PAR_A2A_BROKER_URL	Broker URL	redis://localhost:6379	No

Database Configuration

Variable	Description	Default	Required
PAR_DATABASE_ENABLED	Enable database	true	No
PAR_DATABASE_TYPE	Database type	postgresql	No
PAR_DATABASE_URL	Database URL	-	Yes
PAR_DATABASE_POOL_SIZE	Connection pool size	10	No
PAR_DATABASE_MAX_OVERFLOW	Max overflow connections	20	No
PAR_DATABASE_POOL_TIMEOUT	Pool timeout (seconds)	30	No
PAR_DATABASE_POOL_RECYCLE	Pool recycle time (seconds)	3600	No

Cache Configuration

Variable	Description	Default	Required
PAR_CACHE_ENABLED	Enable caching	true	No
PAR_CACHE_TYPE	Cache type	redis	No
PAR_CACHE_URL	Cache URL	redis://localhost:6379	No
PAR_CACHE_TTL	Default TTL (seconds)	3600	No
PAR_CACHE_MAX_SIZE	Maximum cache size	1GB	No

Monitoring and Observability

Variable	Description	Default	Required
PAR_MONITORING_ENABLED	Enable monitoring	true	No
PAR_PROMETHEUS_ENABLED	Enable Prometheus metrics	true	No
PAR_PROMETHEUS_PORT	Prometheus port	9090	No
PAR_PROMETHEUS_PATH	Prometheus path	/metrics	No
PAR_PROMETHEUS_INTERVAL	Collection interval (seconds)	60	No
PAR_TRACING_ENABLED	Enable tracing	true	No
PAR_TRACING_TYPE	Tracing type	jaeger	No
PAR_TRACING_ENDPOINT	Tracing endpoint	http://localhost:14268/api/traces	No
PAR_TRACING_SAMPLE_RATE	Sample rate	0.1	No
PAR_LOGGING_ENABLED	Enable logging	true	No
PAR_LOGGING_LEVEL	Log level	info	No
PAR_LOGGING_FORMAT	Log format	json	No
PAR_LOGGING_FILE	Log file path	/var/log/par/runtime.log	No
PAR_LOGGING_MAX_SIZE	Max log file size	100MB	No
PAR_LOGGING_MAX_FILES	Max log files	5	No
PAR_ALERTING_ENABLED	Enable alerting	true	No
PAR_ALERTING_WEBHOOK_URL	Alert webhook URL	-	No

Security Configuration

Variable	Description	Default	Required
PAR_SECURITY_ENABLED	Enable security	true	No
PAR_AUTH_ENABLED	Enable authentication	true	No
PAR_AUTH_TYPE	Authentication type	jwt	No
PAR_AUTH_JWT_SECRET	JWT secret	-	Yes
PAR_AUTH_JWT_EXPIRY	JWT expiry (seconds)	3600	No
PAR_AUTH_REFRESH_EXPIRY	Refresh token expiry (seconds)	86400	No
PAR_AUTHORIZATION_ENABLED	Enable authorization	true	No
PAR_RBAC_ENABLED	Enable RBAC	true	No
PAR_API_SECURITY_ENABLED	Enable API security	true	No
PAR_RATE_LIMITING_ENABLED	Enable rate limiting	true	No
PAR_RATE_LIMITING_RPM	Requests per minute	1000	No
PAR_RATE_LIMITING_BURST	Burst size	100	No
PAR_CORS_ENABLED	Enable CORS	true	No
PAR_CORS_ORIGINS	CORS origins	*	No
PAR_CORS_METHODS	CORS methods	GET,POST,PUT,DELETE	No
PAR_CORS_HEADERS	CORS headers	*	No
PAR_CSRF_ENABLED	Enable CSRF protection	true	No
PAR_CSRF_SECRET	CSRF secret	-	No
PAR_TLS_ENABLED	Enable TLS	false	No
PAR_TLS_CERT_FILE	TLS certificate file	/etc/par/tls/cert.pem	No
PAR_TLS_KEY_FILE	TLS key file	/etc/par/tls/key.pem	No
PAR_FIREWALL_ENABLED	Enable firewall	true	No

Storage Configuration

Variable	Description	Default	Required
PAR_STORAGE_ENABLED	Enable storage	true	No
PAR_STORAGE_LOCAL_ENABLED	Enable local storage	true	No
PAR_STORAGE_LOCAL_PATH	Local storage path	/var/lib/par/storage	No
PAR_STORAGE_LOCAL_MAX_SIZE	Max storage size	10GB	No
PAR_STORAGE_LOCAL_CLEANUP_INTERVAL	Cleanup interval (seconds)	3600	No
PAR_STORAGE_OBJECT_ENABLED	Enable object storage	false	No
PAR_STORAGE_OBJECT_TYPE	Object storage type	s3	No
PAR_STORAGE_OBJECT_ENDPOINT	Object storage endpoint	-	No
PAR_STORAGE_OBJECT_BUCKET	Object storage bucket	-	No
PAR_STORAGE_OBJECT_ACCESS_KEY	Object storage access key	-	No
PAR_STORAGE_OBJECT_SECRET_KEY	Object storage secret key	-	No
PAR_STORAGE_OBJECT_REGION	Object storage region	-	No

PAK (Pixell Agent Kit) Variables

General Configuration

Variable	Description	Default	Required
PAK_CONFIG	Path to config file	./pixell.yaml	No
PAK_LOG_LEVEL	Log level	info	No
PAK_DEBUG	Debug mode	false	No
PAK_VERBOSE	Verbose output	false	No
PAK_QUIET	Quiet mode	false	No
PAK_RUNTIME	Default runtime URL	http://localhost:8080	No
PAK_TOKEN	Default auth token	-	No

Build Configuration

Variable	Description	Default	Required
PAK_BUILD_TARGET	Build target	production	No
PAK_BUILD_COMPRESS	Enable compression	false	No
PAK_BUILD_OPTIMIZE	Enable optimizations	false	No
PAK_BUILD_OUTPUT	Output directory	./dist	No
PAK_BUILD_CLEAN	Clean build directory	false	No

Development Configuration

Variable	Description	Default	Required
PAK_DEV_HOST	Development host	localhost	No
PAK_DEV_PORT	Development port	8080	No
PAK_DEV_RELOAD	Enable hot reloading	true	No
PAK_DEV_DEBUG	Enable debug mode	false	No
PAK_DEV_ENV_FILE	Environment file	.env	No

Testing Configuration

Variable	Description	Default	Required
PAK_TEST_COVERAGE	Generate coverage report	false	No
PAK_TEST_WATCH	Watch mode	false	No
PAK_TEST_VERBOSE	Verbose output	false	No
PAK_TEST_PARALLEL	Run tests in parallel	true	No
PAK_TEST_TIMEOUT	Test timeout (ms)	5000	No

Deployment Configuration

Variable	Description	Default	Required
PAK_DEPLOY_RUNTIME	Deployment runtime URL	http://localhost:8080	No
PAK_DEPLOY_TOKEN	Deployment token	-	No
PAK_DEPLOY_WAIT	Wait for deployment	true	No
PAK_DEPLOY_ROLLBACK	Rollback on failure	false	No
PAK_DEPLOY_PACKAGE	Package file path	./dist/*.apkg	No

Agent Variables

General Agent Configuration

Variable	Description	Default	Required
AGENT_ID	Agent identifier	-	Yes
AGENT_NAME	Agent name	-	Yes
AGENT_VERSION	Agent version	1.0.0	No
AGENT_DESCRIPTION	Agent description	-	No
AGENT_AUTHOR	Agent author	-	No
AGENT_EMAIL	Agent author email	-	No

Agent API Configuration

Variable	Description	Default	Required
AGENT_API_HOST	API host	0.0.0.0	No
AGENT_API_PORT	API port	8080	No
AGENT_API_CORS_ORIGINS	CORS origins	*	No
AGENT_API_CORS_METHODS	CORS methods	GET,POST,PUT,DELETE	No
AGENT_API_CORS_HEADERS	CORS headers	*	No
AGENT_API_RATE_LIMIT	Rate limit (requests/minute)	1000	No
AGENT_API_BURST_SIZE	Burst size	100	No

Agent A2A Configuration

Variable	Description	Default	Required
AGENT_A2A_ENABLED	Enable A2A communication	true	No
AGENT_A2A_PORT	A2A port	50051	No
AGENT_A2A_MAX_MESSAGE_SIZE	Max message size	4MB	No
AGENT_A2A_KEEPALIVE_TIME	Keepalive time (seconds)	30	No
AGENT_A2A_KEEPALIVE_TIMEOUT	Keepalive timeout (seconds)	5	No

Agent UI Configuration

Variable	Description	Default	Required
AGENT_UI_ENABLED	Enable UI	true	No
AGENT_UI_PATH	UI path	/ui	No
AGENT_UI_STATIC_DIR	Static directory	static	No
AGENT_UI_TITLE	UI title	Agent Name	No
AGENT_UI_DESCRIPTION	UI description	Agent Description	No

Agent Logging Configuration

Variable	Description	Default	Required
AGENT_LOG_LEVEL	Log level	info	No
AGENT_LOG_FORMAT	Log format	json	No
AGENT_LOG_FILE	Log file path	-	No
AGENT_LOG_MAX_SIZE	Max log file size	100MB	No
AGENT_LOG_MAX_FILES	Max log files	5	No

Agent Security Configuration

Variable	Description	Default	Required
AGENT_SECURITY_ENABLED	Enable security	true	No
AGENT_AUTH_ENABLED	Enable authentication	true	No
AGENT_AUTH_TYPE	Authentication type	jwt	No
AGENT_AUTH_JWT_SECRET	JWT secret	-	Yes
AGENT_AUTH_JWT_EXPIRY	JWT expiry (seconds)	3600	No
AGENT_AUTH_REFRESH_EXPIRY	Refresh token expiry (seconds)	86400	No
AGENT_API_KEY	API key	-	No
AGENT_CSRF_SECRET	CSRF secret	-	No

External Service Variables

Database Services

Variable	Description	Default	Required
DATABASE_URL	Database connection URL	-	Yes
POSTGRES_URL	PostgreSQL URL	-	No
MYSQL_URL	MySQL URL	-	No
SQLITE_URL	SQLite URL	-	No
DATABASE_POOL_SIZE	Connection pool size	10	No
DATABASE_MAX_OVERFLOW	Max overflow connections	20	No
DATABASE_POOL_TIMEOUT	Pool timeout (seconds)	30	No
DATABASE_POOL_RECYCLE	Pool recycle time (seconds)	3600	No

Cache Services

Variable	Description	Default	Required
REDIS_URL	Redis connection URL	redis://localhost:6379	No
REDIS_HOST	Redis host	localhost	No
REDIS_PORT	Redis port	6379	No
REDIS_PASSWORD	Redis password	-	No
REDIS_DB	Redis database	0	No
REDIS_TTL	Default TTL (seconds)	3600	No
REDIS_MAX_SIZE	Max cache size	1GB	No

Message Broker Services

Variable	Description	Default	Required
BROKER_URL	Message broker URL	-	No
RABBITMQ_URL	RabbitMQ URL	-	No
KAFKA_URL	Kafka URL	-	No
NATS_URL	NATS URL	-	No
BROKER_TYPE	Broker type	redis	No
BROKER_CHANNELS	Message channels	agent.events,agent.requests,agent.responses	No

Service Discovery Services

Variable	Description	Default	Required
DISCOVERY_URL	Service discovery URL	-	No
CONSUL_URL	Consul URL	http://localhost:8500	No
ETCD_URL	etcd URL	-	No
DISCOVERY_TYPE	Discovery type	consul	No
DISCOVERY_TTL	Service TTL (seconds)	30	No
DISCOVERY_HEALTH_INTERVAL	Health check interval (seconds)	10	No

Monitoring Services

Variable	Description	Default	Required
PROMETHEUS_URL	Prometheus URL	http://localhost:9090	No
GRAFANA_URL	Grafana URL	http://localhost:3000	No
JAEGER_URL	Jaeger URL	http://localhost:14268	No
ZIPKIN_URL	Zipkin URL	http://localhost:9411	No
ELASTICSEARCH_URL	Elasticsearch URL	http://localhost:9200	No
KIBANA_URL	Kibana URL	http://localhost:5601	No

Cloud Services

Variable	Description	Default	Required
AWS_ACCESS_KEY_ID	AWS access key	-	No
AWS_SECRET_ACCESS_KEY	AWS secret key	-	No
AWS_REGION	AWS region	us-east-1	No
AWS_S3_BUCKET	S3 bucket	-	No
AWS_S3_ENDPOINT	S3 endpoint	-	No
GCP_PROJECT_ID	GCP project ID	-	No
GCP_CREDENTIALS	GCP credentials	-	No
AZURE_ACCOUNT_NAME	Azure account name	-	No
AZURE_ACCOUNT_KEY	Azure account key	-	No

Environment-Specific Variables

Development Environment

# Development environment variables
PIXELL_ENV=development
PIXELL_DEBUG=true
PIXELL_LOG_LEVEL=debug
PIXELL_VERBOSE=true

PAR_HOST=localhost
PAR_PORT=8080
PAR_WORKERS=1

PAK_DEV_RELOAD=true
PAK_DEV_DEBUG=true

AGENT_LOG_LEVEL=debug
AGENT_LOG_FORMAT=text

Staging Environment

# Staging environment variables
PIXELL_ENV=staging
PIXELL_DEBUG=false
PIXELL_LOG_LEVEL=info
PIXELL_VERBOSE=false

PAR_HOST=0.0.0.0
PAR_PORT=8080
PAR_WORKERS=2

PAK_BUILD_TARGET=staging
PAK_BUILD_COMPRESS=true

AGENT_LOG_LEVEL=info
AGENT_LOG_FORMAT=json

Production Environment

# Production environment variables
PIXELL_ENV=production
PIXELL_DEBUG=false
PIXELL_LOG_LEVEL=warn
PIXELL_VERBOSE=false

PAR_HOST=0.0.0.0
PAR_PORT=8080
PAR_WORKERS=4

PAK_BUILD_TARGET=production
PAK_BUILD_COMPRESS=true
PAK_BUILD_OPTIMIZE=true

AGENT_LOG_LEVEL=warn
AGENT_LOG_FORMAT=json
AGENT_SECURITY_ENABLED=true
AGENT_AUTH_ENABLED=true

Variable Substitution

Pixell supports variable substitution in configuration files:

# config.yaml
runtime:
  host: "${PAR_HOST}"
  port: "${PAR_PORT}"
  workers: "${PAR_WORKERS}"

database:
  url: "${DATABASE_URL}"
  pool_size: "${DATABASE_POOL_SIZE}"

cache:
  url: "${REDIS_URL}"
  ttl: "${REDIS_TTL}"

Environment File Examples

.env.development

# Development environment
PIXELL_ENV=development
PIXELL_DEBUG=true
PIXELL_LOG_LEVEL=debug

PAR_HOST=localhost
PAR_PORT=8080
PAR_WORKERS=1

DATABASE_URL=postgresql://user:pass@localhost:5432/pixell_dev
REDIS_URL=redis://localhost:6379

AGENT_ID=my-agent
AGENT_NAME=My Agent
AGENT_VERSION=1.0.0

.env.production

# Production environment
PIXELL_ENV=production
PIXELL_DEBUG=false
PIXELL_LOG_LEVEL=warn

PAR_HOST=0.0.0.0
PAR_PORT=8080
PAR_WORKERS=4

DATABASE_URL=postgresql://user:pass@db.example.com:5432/pixell_prod
REDIS_URL=redis://redis.example.com:6379

AGENT_ID=my-agent
AGENT_NAME=My Agent
AGENT_VERSION=1.0.0
AGENT_SECURITY_ENABLED=true
AGENT_AUTH_ENABLED=true

Variable Validation

Pixell validates environment variables on startup:

# Validate environment variables
pixell validate-env

# Validate with specific environment
pixell validate-env --env production

# Show missing variables
pixell validate-env --show-missing

Security Best Practices

1. Secret Management

# Use environment variables for secrets
export PIXELL_SECRET_KEY="$(openssl rand -base64 32)"
export PIXELL_JWT_SECRET="$(openssl rand -base64 32)"
export PIXELL_API_KEY="$(openssl rand -base64 32)"

2. Environment Isolation

# Use different values for different environments
# Development
export PIXELL_ENV=development
export DATABASE_URL="postgresql://localhost:5432/pixell_dev"

# Production
export PIXELL_ENV=production
export DATABASE_URL="postgresql://prod-db:5432/pixell_prod"

3. Variable Encryption

# Encrypt sensitive variables
export PIXELL_SECRET_KEY="$(echo 'my-secret' | base64)"
export PIXELL_JWT_SECRET="$(echo 'jwt-secret' | base64)"

Troubleshooting

Common Issues

1. Missing Required Variables

Problem: Required environment variables are not set Solutions:

• Check variable names and values
• Use pixell validate-env to identify missing variables
• Set default values in configuration
• Use environment files

2. Invalid Variable Values

Problem: Environment variables have invalid values Solutions:

• Check variable types (string, number, boolean)
• Verify numeric ranges
• Check URL formats
• Validate enum values

3. Variable Substitution Issues

Problem: Variable substitution not working Solutions:

• Check variable syntax: ${VARIABLE_NAME}
• Verify variables are exported
• Check for typos in variable names
• Use quotes around values with spaces

Debugging Environment Variables

# Show all environment variables
pixell env show

# Show variables for specific component
pixell env show --component par

# Show variables with values
pixell env show --values

# Show missing variables
pixell env show --missing

Next Steps

After setting up environment variables:

1. PAR Configuration Reference - Configure PAR runtime
2. APKG Schema Reference - Understand agent package format
3. PAK CLI Reference - Use PAK to build and deploy agents
4. Full Deployment Guide - Complete deployment

---

Ready to configure your environment? Check out PAR Configuration Reference to configure your runtime!