AKIOS Logo AKIOS
EN | FR

Migration Guide

Upgrade to the latest AKIOS version from earlier releases. This guide covers the V1.0.12–V1.0.15 updates, the V1.0.11 update, and the original pre-V1.0 migration.

Upgrading to V1.0.15 (from V1.0.11)

V1.0.15 is a drop-in upgrade with no breaking CLI or workflow changes. Four releases shipped between v1.0.11 and v1.0.15:

# Pip
pip install --upgrade akios

# Docker — pull latest image
docker pull akiosai/akios:v1.0.15

# Verify
akios --version

What's New in V1.0.12–V1.0.15

v1.0.12 — JSON Output + Token Tracking:

  • --json-output CLI flag — machine-readable JSON output for CI/CD pipelines (all commands)
  • Token input/output tracking — per-call token counts returned in engine results
  • PII redaction metadata — redaction counts, categories, and positions in audit entries
  • Enriched engine return — structured result object with cost, tokens, PII stats

v1.0.13 — AWS Bedrock Provider:

  • AWS Bedrock support — Claude, Llama, and Titan models via IAM authentication (no API keys needed)
  • Environment variables: AKIOS_BEDROCK_MODEL_ID, AKIOS_BEDROCK_REGION
  • Optional dependency: pip install akios[bedrock] (installs boto3)
  • Works with existing policies, budgets, and audit — no workflow changes needed

v1.0.14 — 13 End-User Fixes:

  • Template degradation fix — complex templates no longer silently lose steps
  • Docker non-interactive fix — --non-interactive flag prevents TTY hangs in CI
  • seccomp venv guidance — clear error message when seccomp blocks virtualenv creation
  • cage down preserves input data — data/input/ is no longer deleted on teardown (use --wipe-all for full erasure)
  • Bedrock environment variables forwarded in Docker wrapper
  • protect scan --text flag — scan inline text without creating a file
  • Wrapper fallback to "latest" when version detection fails

v1.0.15 — SDK Integration Hardening (8 fixes):

  • Pydantic settings extra="ignore" — unknown env vars no longer crash startup
  • JSON error output — all error paths return valid JSON when --json-output is set
  • Error categories — errors include category field (config, auth, budget, workflow, agent, security)
  • Bedrock pricing — accurate token cost calculation for Bedrock models
  • Dockerfile .akios directory — config directory created in container image
  • JSON contract tests — CI validates all JSON output schemas
  • Bedrock throttle retry — automatic retry with backoff on AWS throttling (429)

Migration Notes

cage down behavior change (v1.0.14): akios cage down no longer deletes data/input/. If you relied on full erasure including input data, use akios cage down --wipe-all.

Bedrock users (v1.0.13+): Install the Bedrock extras:

pip install akios[bedrock]

Then configure via environment:

AKIOS_LLM_PROVIDER=bedrock
AKIOS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
AKIOS_BEDROCK_REGION=us-east-1

IAM credentials are picked up automatically from the environment (AWS CLI, instance profile, etc.).

JSON output (v1.0.12+): Add --json-output to any command for machine-readable output:

akios status --json-output
akios run workflow.yml --json-output

Verification after upgrade:

akios --version                    # Should show 1.0.15
akios status --security            # Verify all protections active
akios doctor                       # Run diagnostics

No configuration changes, workflow updates, or data migration needed.

Upgrading to V1.0.11 (from V1.0.x)

V1.0.11 is a drop-in upgrade with no breaking CLI or workflow changes. Update via your installation method:

# Pip
pip install --upgrade akios

# Docker — pull latest image
docker pull akiosai/akios:v1.0.15

# Verify
akios --version

Note: AKIOS now requires Python 3.9+ (Python 3.8 is EOL). If you're on 3.8, upgrade Python first.

What's New in V1.0.11

v1.0.9 — Science + Orchestration:

  • Conditional execution — condition field on workflow steps for branching logic
  • Error recovery — on_error field (skip / fail / retry) for resilient workflows
  • LangGraph integration — 215-line working example of LangGraph tool calls through AKIOS enforcement
  • TLA+ formal verification — 130-line model-checked safety invariants for the enforcement pipeline
  • Pluggable PII backend — PIIDetectorProtocol interface for custom PII detectors
  • Insurance PII patterns — policy numbers, group numbers, claim numbers, prior-authorization detection
  • context_keywords gate — suppress false-positive PII matches without surrounding context
  • Weighted compliance scoring — security 50%, audit 30%, cost 20%
  • Config JSON Schema — auto-generated from Pydantic settings for IDE auto-completion

v1.0.10 — Hardening:

  • Non-root Docker — containers no longer run as root by default
  • Safe condition evaluator — AST-based evaluator replaces eval() + token blocklist (eliminates code injection)
  • Engine split — monolith broken into StepExecutor, TemplateRenderer, OutputExtractor, ConditionEvaluator
  • Structured logging — ~380 print() calls replaced with Python logging module

v1.0.11 — Cleanup & Hardening:

  • PyPDF2 → pypdf — replaced deprecated PyPDF2 with actively maintained pypdf
  • Python 3.9+ — dropped Python 3.8 support (EOL)
  • Wrapper fallback fix — detect_version() now reads dynamically from VERSION file
  • Pre-release gate hardening — version sync validation across all sources

Migration Notes

Python 3.8 users: Upgrade to Python 3.9+ before updating AKIOS:

# Check your Python version
python3 --version

# If < 3.9, upgrade first

PyPDF2 users: If you use PyPDF2 in custom scripts alongside AKIOS:

# Old (deprecated)
import PyPDF2

# New
import pypdf

Verification after upgrade:

akios --version                    # Should show 1.0.15
akios status --security            # Verify all protections active
akios workflow validate templates/hello-workflow.yml  # Test validation
akios doctor                       # Run diagnostics

No configuration changes, workflow updates, or data migration needed.

Upgrading to V1.0 (from pre-V1.0)

Before You Start

✓ Checklist:

  • Back up .env file
  • Back up config.yaml
  • Back up workflows/ directory
  • Export audit logs: akios audit export
  • Note your current version: akios --version

Estimated time: 10-15 minutes

Choose Your Installation Method

Option 1: Pip Installation (Recommended for Linux)

Maximum security with kernel-hard isolation.

# Upgrade AKIOS
pip install --upgrade akios

# Verify version
akios --version
# Should show: akios 1.0.15 or later

# Test installation
akios status

When to use:

  • Running on Linux
  • Need maximum security (cgroups v2 + seccomp-bpf)
  • Prefer native installation

Option 2: Docker Wrapper (Cross-Platform)

Strong security that works everywhere.

# Download latest wrapper
curl -O https://raw.githubusercontent.com/akios-ai/akios/main/src/akios/cli/data/wrapper.sh
mv wrapper.sh akios
chmod +x akios

# Force pull latest image
AKIOS_FORCE_PULL=1 ./akios --version

# Test installation
./akios status

When to use:

  • Running on macOS or Windows
  • Want simple cross-platform solution
  • Already using Docker

Option 3: Direct Docker (For CI/CD)

Container-based for automation.

# Pull latest image
docker pull akiosai/akios:v1.0.15

# Test run
docker run --rm akiosai/akios:v1.0.15 --version

When to use:

  • CI/CD pipelines
  • Automated environments
  • Custom Docker orchestration

Migration Steps

Step 1: Verify Installation

# Check version
akios --version

# Check overall status
akios status

# Check security features
akios status --security

Expected output:

AKIOS v1.0.15
Security Level: Kernel-hard (Linux) or Policy-based (Docker)
Audit: Active
PII Protection: Active
Sandbox: Enabled

Step 2: Test Configuration

# Validate existing config
akios config validate

# Or run setup wizard to reconfigure
akios setup --force

Check for warnings:

  • Invalid provider/model combinations
  • Deprecated config fields
  • Missing required settings

Step 3: Test Workflows

Start with mock mode (free):

# Set mock mode
export AKIOS_MOCK_LLM=1

# Test template
akios run templates/hello-workflow.yml

# Test your workflows
akios run workflows/my-workflow.yml

Then test with real APIs:

# Switch to real APIs
akios run templates/hello-workflow.yml --real-api

# Test your production workflow
akios run workflows/production/my-workflow.yml --real-api

Step 4: Verify Audit Trail

# Check audit logs work
akios audit view --limit 10

# Verify log integrity
akios audit verify

# Export audit logs
akios audit export --format json > audit-report.json

Expected: All audit features working, logs verifiable.

Step 5: Update Scripts & Automation

If you have scripts calling AKIOS:

Before (old):

#!/bin/bash
akios-old run workflow.yml

After (new):

#!/bin/bash
akios run workflow.yml

CI/CD pipelines:

# .github/workflows/akios.yml
steps:
  - name: Install AKIOS
    run: pip install akios>=1.0.15
    
  - name: Run workflow
    run: akios run workflows/production/*.yml

Breaking Changes

Configuration Format

Old config (pre-1.0):

security:
  sandbox: true
  pii_filter: true

New config (1.0+):

sandbox_enabled: true
pii_redaction_enabled: true

Fix: Run akios setup --force to create new config.

Environment Variables

Old:

AKIOS_PROVIDER=openai

New:

AKIOS_LLM_PROVIDER=openai

Fix: Update .env file with new variable names.

CLI Commands

Old:

akios validate workflow.yml

New:

akios config validate

Fix: Update scripts to use new command names.

Compatibility Notes

Workflows

✅ Compatible: All workflow YAML files work in V1.0

Note: Validation is stricter - workflows must have:

  • Valid agent name
  • Valid action for that agent
  • Required parameters

Audit Logs

✅ Compatible: Old audit logs can be read by V1.0

# Verify old logs
akios audit verify --path ./audit-old/

Python API

✅ Compatible: Old API calls still work

# Old name (deprecated but works)
from akios.core.runtime.engine import RuntimeEngine

# New name (preferred)
from akios.core.runtime.engine import WorkflowEngine

Platform-Specific

Linux:

  • Pip installation now provides kernel-hard security
  • cgroups v2 + seccomp-bpf automatically enabled
  • No action needed

macOS/Windows:

  • Docker wrapper recommended (unchanged)
  • Policy-based security (unchanged)
  • No action needed

Rollback Instructions

If you need to rollback:

Pip installation:

# Uninstall V1.0
pip uninstall akios

# Install previous version
pip install akios==0.9.5

# Restore backups
cp .env.backup .env
cp config.yaml.backup config.yaml

Docker:

# Use previous image
docker pull akiosai/akios:v0.9.5

# Update wrapper
curl -O https://raw.githubusercontent.com/akios-ai/akios/v0.9.5/src/akios/cli/data/wrapper.sh
mv wrapper.sh akios

Getting Help

If migration fails:

1. Check diagnostics:

akios doctor --json > diagnostics.json

2. Review logs:

akios logs --level ERROR

3. Ask for help:

Include:

  • akios --version output
  • diagnostics.json file
  • Steps you've taken
  • Error messages

Post-Migration Checklist

✓ Verify everything works:

  • akios --version shows 1.0.15+
  • akios status --security shows security active
  • Workflows run successfully in mock mode
  • Workflows run successfully with real APIs
  • akios audit verify passes
  • CI/CD pipelines updated
  • Team members notified
  • Documentation updated

Related Docs

ESC