AKIOS Logo AKIOS
EN | FR

Configuration Reference

Customize AKIOS to match your security and performance needs. This guide explains all configuration options with practical examples.

Configuration Files

AKIOS uses two files for configuration:

.env - Your API keys and secrets (NEVER commit to git)

AKIOS_LLM_PROVIDER=grok
GROK_API_KEY=your-key-here
AKIOS_LLM_MODEL=grok-3

config.yaml - Runtime settings (safe to commit)

sandbox_enabled: true
budget_limit_per_run: 1.0
pii_redaction_enabled: true

Configuration Priority

Settings are loaded in this order (highest wins):

  1. Environment variables - Override everything
  2. .env file - Your custom settings
  3. config.yaml - Project defaults
  4. Built-in defaults - Secure fallbacks

Quick Setup

Interactive setup wizard (recommended):

akios setup

The wizard guides you through:

  • Choosing AI provider
  • Adding API key
  • Setting budget limits
  • Testing configuration

Environment Variables (.env)

Store sensitive configuration in the .env file:

AI Provider Settings

# Choose your provider
AKIOS_LLM_PROVIDER=grok  # openai, anthropic, grok, mistral, gemini, bedrock

# Choose your model
AKIOS_LLM_MODEL=grok-3   # Provider-specific model name

# Add your API key
GROK_API_KEY=your-key-here

# AWS Bedrock settings (v1.0.13+)
AKIOS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
AKIOS_BEDROCK_REGION=us-east-1
# IAM credentials picked up automatically from AWS CLI / instance profile

Mode Settings

# Use real AI APIs (0) or mock responses (1)
AKIOS_MOCK_LLM=0

# Allow network access for HTTP agent
AKIOS_NETWORK_ACCESS_ALLOWED=1

Docker Settings

# Force pull latest image (Docker wrapper only)
AKIOS_FORCE_PULL=1

Common Configuration Tasks

Change AI Provider

# Edit .env file
AKIOS_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
AKIOS_LLM_MODEL=gpt-4o

Increase Budget Limit

# For one-time use
export AKIOS_BUDGET_LIMIT_PER_RUN=5.0
akios run workflow.yml

# Or edit config.yaml
# budget_limit_per_run: 5.0

Enable Network Access

# Edit config.yaml
network_access_allowed: true

Configuration Options (config.yaml)

Security Settings

sandbox_enabled: true

  • Enables process isolation
  • Kernel-hard on Linux, policy-based in Docker
  • Recommended: Always true

pii_redaction_enabled: true

  • Automatically removes sensitive data
  • Applied to inputs and outputs
  • Recommended: Always true

pii_redaction_outputs: true

  • Redacts PII in AI responses
  • Conservative patterns for generated content
  • Recommended: Always true

pii_redaction_aggressive: false

  • Enables stricter PII patterns with more false positives
  • Use when handling highly sensitive data (healthcare, finance)
  • Default: false
  • Recommended: Enable for regulated environments

context_keywords: []

  • Domain-specific keywords that suppress false-positive PII matches
  • Example: ["policy_number", "account_ref"] prevents these terms from being redacted as potential PII
  • Useful for insurance, banking, and other domains with structured identifiers
  • Default: [] (empty list)

redaction_strategy: "mask"

  • How to handle PII: mask, hash, or remove
  • mask replaces with [REDACTED]
  • Recommended: mask (preserves structure)

Resource Limits

cpu_limit: 0.8

  • Fraction of CPU available (0.1 - 1.0)
  • Prevents CPU exhaustion
  • Default: 0.8 (80% of CPU)

memory_limit_mb: 256

  • Maximum memory in megabytes
  • Prevents memory exhaustion
  • Default: 256MB

max_open_files: 100

  • Maximum file descriptors
  • Prevents file handle exhaustion
  • Default: 100 files

max_file_size_mb: 10

  • Maximum file size for writes
  • Prevents disk space abuse
  • Default: 10MB per file

network_access_allowed: false

  • Allow HTTP agent network calls
  • Default: false (deny by default)
  • Set to true for API integrations

allowed_domains: []

  • HTTPS whitelist for HTTP agent requests
  • LLM APIs (OpenAI, Anthropic, Grok, Mistral, Gemini) always pass through regardless
  • Controls only the HTTP agent for custom API calls
  • Default: [] (empty — only LLM APIs allowed)
network_access_allowed: true
allowed_domains:
  - "api.salesforce.com"
  - "api.mycompany.com"

Or via environment variable: AKIOS_ALLOWED_DOMAINS="api.salesforce.com,api.mycompany.com"

Subdomains must be added explicitly — they are not automatically allowed.

Cost Controls

cost_kill_enabled: true

  • Automatic termination on budget violations
  • Recommended: Always true

budget_limit_per_run: 1.0

  • Maximum cost in USD per workflow
  • Default: $1.00
  • Increase for complex workflows

max_tokens_per_call: 1000

  • Token limit per LLM API call
  • Default: 1000 tokens
  • Increase for longer generations

Audit Settings

audit_enabled: true

  • Enables cryptographic audit logging
  • Recommended: Always true (required for compliance)

audit_storage_path: "./audit/"

  • Directory for audit logs
  • Default: ./audit/

audit_export_format: "json"

  • Format for audit exports
  • Default: json

General Settings

environment: "development"

  • Runtime environment: development, testing, or production
  • Affects logging verbosity
  • Default: development

log_level: "INFO"

  • Logging detail: DEBUG, INFO, WARNING, ERROR
  • Default: INFO
  • Since v1.0.10, AKIOS uses Python's logging module with structured JSON output

Environment overrides

export AKIOS_CPU_LIMIT=0.5
export AKIOS_MEMORY_LIMIT_MB=128
export AKIOS_BUDGET_LIMIT_PER_RUN=0.5
export AKIOS_LOG_LEVEL=DEBUG

Example Configurations

Production (Maximum Security)

# Strict security for production workloads
sandbox_enabled: true
cpu_limit: 0.5
memory_limit_mb: 128
network_access_allowed: false
budget_limit_per_run: 1.0
log_level: "WARNING"
environment: "production"

Development (Relaxed)

# More permissive for development
sandbox_enabled: true
cpu_limit: 0.8
memory_limit_mb: 512
network_access_allowed: true
budget_limit_per_run: 5.0
log_level: "DEBUG"
environment: "development"

Testing (Balanced)

# Moderate settings for testing
sandbox_enabled: true
cpu_limit: 0.7
memory_limit_mb: 256
network_access_allowed: true
budget_limit_per_run: 2.0
log_level: "INFO"
environment: "testing"

Validation

Check your configuration:

akios status

Shows: Current settings, security level, any configuration issues

Reconfigure everything:

akios setup --force

Export JSON Schema (v1.0.9+):

AKIOS can auto-generate a JSON Schema from its Pydantic config model for use with external validators, IDE autocompletion, or CI pipelines:

akios config schema > akios-config-schema.json

Note: The list of allowed AI models (ALLOWED_MODELS) is managed via Pydantic settings, so model validation is automatic and schema-aware.

Security Best Practices

✓ Do:

  • Keep .env out of version control (add to .gitignore)
  • Set file permissions to 600 for .env
  • Use setup wizard for initial configuration
  • Validate configuration with akios status
  • Use environment-specific configs

× Don't:

  • Commit API keys to git
  • Disable security features in production
  • Use unlimited budgets
  • Share .env files
  • Modify configs during workflow execution

Troubleshooting Configuration

Configuration not working:

# Check what AKIOS sees
akios status --verbose

# Reset configuration
akios setup --force

Invalid provider/model:

  • OpenAI: gpt-3.5-turbo, gpt-4, gpt-4-turbo, gpt-4o, gpt-4o-mini
  • Anthropic: claude-3.5-haiku, claude-3.5-sonnet
  • Grok: grok-3
  • Mistral: mistral-small, mistral-medium, mistral-large
  • Gemini: gemini-1.0-pro, gemini-1.5-pro, gemini-1.5-flash
  • Bedrock: anthropic.claude-*, meta.llama*, amazon.titan-* (IAM auth, v1.0.13+)

API key issues:

# Run setup wizard to fix
akios setup --force

Security Level: Strong policy-based security Configuration Notes:

  • Consistent behavior across platforms
  • Container isolation instead of kernel sandboxing
  • Network controls via container policies
  • Memory and CPU limits via Docker

Choosing the Right Installation

Use Case Recommended Method Why
Maximum security, Linux production Pip Package Kernel-hard security features
Cross-platform development team Docker Consistent environment everywhere
Python ecosystem integration Pip Package Full Python compatibility

Platform-Specific Configuration

Linux (All Methods)

# Maximum security available
sandbox_enabled: true  # seccomp-bpf + cgroups
environment: "production"

macOS/Windows (Docker)

# Strong policy-based security
sandbox_enabled: true  # Container policies + allowlisting
environment: "production"
# Note: No kernel-hard seccomp-bpf available

Docker (All Platforms)

# Container-aware settings
sandbox_enabled: true
network_access_allowed: true  # For HTTP agent
# Docker handles resource isolation

Configuration Validation by Method

AKIOS validates configuration compatibility with your deployment method:

# Pip package - validates Linux kernel features
akios status  # Shows kernel-hard security status

# Docker - validates container environment
akios status  # Shows policy-based security status

Tip: Run akios status after installation to see your security capabilities and configuration status.

Related

ESC