Overview
FastSkill’s behavior is controlled through configuration objects that define how the service operates. This guide covers all available configuration options and their impact on performance and functionality.
Configuration can be set programmatically, through environment variables, or via configuration files. Programmatic configuration takes precedence over environment variables, which take precedence over defaults.
Basic Configuration
Python Configuration
from fastskill import ServiceConfig, ExecutionConfig, CacheConfig
from pathlib import Path
# Complete configuration example
config = ServiceConfig(
# Storage Configuration
skill_storage_path=Path("./skills"),
# Execution Configuration
execution=ExecutionConfig(
default_timeout=30, # Seconds
max_memory_mb=512, # Memory limit per skill
max_cpu_percent=50, # CPU usage limit
enable_networking=False, # Allow network access
allowed_paths=[Path("./data")] # Additional allowed paths
),
# Cache Configuration
cache=CacheConfig(
metadata_cache_size=1000, # Number of skills to cache
content_cache_size=100, # Number of full skills to cache
cache_ttl_seconds=3600, # Cache expiration time
enable_persistence=True # Persist cache to disk
),
# Service Configuration
enable_hot_reload=True, # Watch for file changes
watch_paths=[Path("./skills"), Path("./custom-skills")],
enable_audit_logging=True, # Log all operations
log_level="INFO", # Logging level
max_concurrent_executions=10, # Concurrent skill limit
# Performance Configuration
enable_metrics=True, # Collect performance metrics
metrics_retention_hours=24, # How long to keep metrics
enable_health_checks=True # Enable health check endpoints
)
Rust Configuration
use fastskill::{ServiceConfig, ExecutionConfig, CacheConfig};
use std::{path::PathBuf, time::Duration};
let config = ServiceConfig {
skill_storage_path: PathBuf::from("./skills"),
execution: ExecutionConfig {
default_timeout: Duration::from_secs(30),
max_memory_mb: 512,
max_cpu_percent: 50,
enable_networking: false,
allowed_paths: vec![PathBuf::from("./data")],
..Default::default()
},
cache: CacheConfig {
metadata_cache_size: 1000,
content_cache_size: 100,
cache_ttl: Duration::from_secs(3600),
enable_persistence: true,
..Default::default()
},
enable_hot_reload: true,
watch_paths: vec![
PathBuf::from("./skills"),
PathBuf::from("./custom-skills")
],
enable_audit_logging: true,
log_level: LogLevel::Info,
max_concurrent_executions: 10,
enable_metrics: true,
metrics_retention: Duration::from_secs(24 * 3600),
enable_health_checks: true,
..Default::default()
};
Configuration Options
Storage Configuration
The directory where FastSkill looks for skill files and stores skill data. This is the primary location for skill discovery and management.
Optional secondary storage location for backups and redundancy. If not specified, no backups are created.
Execution Configuration
execution.default_timeout
Default timeout in seconds for skill execution. Individual skills can override this value.
Maximum memory (in MB) that a single skill execution can use. Helps prevent memory exhaustion attacks.
execution.max_cpu_percent
Maximum CPU usage percentage allowed for skill execution. Useful for preventing resource starvation.
execution.enable_networking
Whether skills are allowed to make network requests. Set to false for enhanced security.
List of additional filesystem paths that skills are allowed to access beyond their own directories.
Level of sandboxing for skill execution. Options: none (no sandboxing), basic (resource limits only), strict (full isolation).
Cache Configuration
cache.metadata_cache_size
Maximum number of skill metadata entries to keep in memory cache. Higher values improve performance but use more memory.
Maximum number of full skill content entries to cache. Content is larger than metadata, so use smaller values here.
Time-to-live for cache entries in seconds. Set to 0 to disable expiration.
Whether to persist cache to disk for faster startup times. Useful for production deployments.
Directory for persistent cache storage. If not specified, uses system temp directory.
Service Configuration
Whether to watch for changes in skill files and automatically reload them. Useful during development.
List of directories to watch for skill changes. Only used when hot reload is enabled.
Whether to log all skill operations for security and debugging purposes.
Minimum log level to output. DEBUG and TRACE are useful for troubleshooting but impact performance.
max_concurrent_executions
Maximum number of skill executions that can run simultaneously. Helps prevent resource exhaustion.
Whether to collect performance metrics for monitoring and optimization.
How long to retain performance metrics in hours. Older metrics are automatically cleaned up.
Whether to enable health check endpoints for monitoring systems.
health_check_interval_seconds
Interval between health checks in seconds. Only used when health checks are enabled.
Environment Variables
You can also configure FastSkill using environment variables:
| Variable | Description | Default |
|---|
FASTSKILL_LOG_LEVEL | Set logging level | INFO |
FASTSKILL_STORAGE_PATH | Override skill storage path | ./skills |
FASTSKILL_CONFIG_FILE | Path to JSON configuration file | None |
FASTSKILL_EXECUTION_TIMEOUT | Default execution timeout (seconds) | 30 |
FASTSKILL_MAX_MEMORY_MB | Maximum memory per execution (MB) | 512 |
FASTSKILL_ENABLE_HOT_RELOAD | Enable hot reloading | false |
FASTSKILL_CACHE_SIZE | Metadata cache size | 1000 |
FASTSKILL_ENABLE_METRICS | Enable performance metrics | true |
Configuration Files
For complex deployments, use JSON configuration files:
{
"skill_storage_path": "./skills",
"execution": {
"default_timeout": 30,
"max_memory_mb": 512,
"max_cpu_percent": 50,
"enable_networking": false,
"allowed_paths": ["./data"],
"sandbox_level": "basic"
},
"cache": {
"metadata_cache_size": 1000,
"content_cache_size": 100,
"cache_ttl_seconds": 3600,
"enable_persistence": true,
"cache_directory": "./cache"
},
"enable_hot_reload": true,
"watch_paths": ["./skills", "./custom-skills"],
"enable_audit_logging": true,
"log_level": "INFO",
"max_concurrent_executions": 10,
"enable_metrics": true,
"metrics_retention_hours": 24,
"enable_health_checks": true,
"health_check_interval_seconds": 30
}
import json
from fastskill import ServiceConfig
# Load from file
with open('config.json') as f:
config_dict = json.load(f)
config = ServiceConfig.from_dict(config_dict)
use fastskill::ServiceConfig;
use std::fs;
let config_content = fs::read_to_string("config.json")?;
let config: ServiceConfig = serde_json::from_str(&config_content)?;
For High Throughput
# Optimize for many concurrent requests
config = ServiceConfig(
max_concurrent_executions=50,
cache=CacheConfig(
metadata_cache_size=5000,
content_cache_size=500,
cache_ttl_seconds=7200 # 2 hours
),
execution=ExecutionConfig(
default_timeout=10, # Faster timeout
max_memory_mb=256 # Lower memory per execution
)
)
For Memory Constrained Environments
# Minimize memory usage
config = ServiceConfig(
cache=CacheConfig(
metadata_cache_size=100,
content_cache_size=10,
enable_persistence=False
),
execution=ExecutionConfig(
max_memory_mb=128,
max_cpu_percent=25
),
enable_metrics=False # Disable metrics collection
)
For Development
# Optimize for development workflow
config = ServiceConfig(
enable_hot_reload=True,
watch_paths=[Path("./skills"), Path("./custom-skills")],
log_level="DEBUG",
enable_audit_logging=True,
cache=CacheConfig(
cache_ttl_seconds=60 # Short cache for fresh data
)
)
Security Configuration
High Security Mode
# Maximum security configuration
config = ServiceConfig(
execution=ExecutionConfig(
enable_networking=False,
sandbox_level="strict",
allowed_paths=[], # No extra paths
max_memory_mb=256,
max_cpu_percent=25
),
enable_audit_logging=True,
log_level="INFO"
)
Development Security
# Balanced security for development
config = ServiceConfig(
execution=ExecutionConfig(
enable_networking=True, # Allow network for testing
sandbox_level="basic",
allowed_paths=[Path("./test-data")],
max_memory_mb=1024, # Higher limits for testing
max_cpu_percent=75
),
enable_audit_logging=True,
log_level="DEBUG"
)
Validation and Testing
Always validate your configuration before deploying:
Validate configuration
from fastskill import ServiceConfig
config = ServiceConfig(...) # Your configuration
# Validate the configuration
try:
config.validate()
print("✅ Configuration is valid")
except ValueError as e:
print(f"❌ Configuration error: {e}")
Test with minimal setup
# Test configuration with a minimal service
config.enable_hot_reload = False # Disable for testing
config.log_level = "ERROR" # Reduce noise
service = FastSkillService(config)
await service.initialize()
# Quick functionality test
skills = await service.list_skills()
print(f"Service running with {len(skills)} skills")
await service.shutdown()
Best Practices
Start with defaults
Begin with default configuration and adjust based on your specific needs and performance observations.
Monitor and adjust
Use the metrics system to monitor performance and adjust configuration based on real usage patterns.
Test configuration changes
Always test configuration changes in a staging environment before deploying to production.
Document your configuration
Keep documentation of your configuration choices and the reasons behind them for future reference.
Use configuration files
For production deployments, prefer configuration files over environment variables for better visibility and version control.
Invalid configuration can cause service startup failures or unexpected behavior. Always validate your configuration and test thoroughly before deployment.
