AKIOS Logo AKIOS
EN | FR

Migration Guide

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

Upgrading to V1.6.0 (from V1.0.15)

V1.6.0 is a major feature release with new agents, parallel execution, a plugin system, a REST API, Ollama support, and EnforceCore integration. Most changes are additive — existing workflows continue to work unchanged.

# Pip
pip install --upgrade akios

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

# Verify
akios --version

What's New in V1.1.0–V1.6.0

v1.1.0 — Webhook & Database Agents + Parallel Execution:

  • 2 new agents — webhook (Slack, Teams, Discord, PagerDuty) and database (SQLite, PostgreSQL read queries)
  • Parallel execution — parallel: blocks in workflow YAML run steps concurrently
  • Plugin system — pip-installable agent packages via akios.agents entry points
  • Doctor redesigned — 9 diagnostic checks with structured output

v1.2.0 — EnforceCore Integration:

  • pip install akios[enforcecore] — optional dependency activates EnforceCore as enforcement backend
  • use_enforcecore: true in config.yaml delegates policy, PII, and audit to EnforceCore
  • akios protect secrets — scan for leaked secrets (requires EnforceCore)

v1.3.0 — Merkle Bridge:

  • Merkle Bridge — links AKIOS audit entries to EnforceCore's audit store via external_hash

v1.4.0 — PII Boundary Change (⚠ Breaking):

  • 53 → 44 PII patterns — 8 healthcare-specific patterns (NPI, DEA, MRN, etc.) and 5 financial patterns removed from OSS; available via EnforceCore NER backend (enforcecore[ner])
  • Pluggable PII backend now supports EnforceCore NER + secret scanner

v1.4.2 — Ollama Provider:

  • Ollama support — run local open-source models (llama3.2, mistral, codellama, etc.)
  • No API key needed — set AKIOS_LLM_PROVIDER=ollama and OLLAMA_HOST=http://localhost:11434
  • HTTPS enforcement exempted for localhost / 127.0.0.1

v1.5.0 — Dashboard, Reports, Audit Tools:

  • akios run --report — generate HTML security posture report after execution
  • akios audit migrate — migrate JSONL audit to SQLite or PostgreSQL
  • akios audit prune — enforce retention policies on audit ledger
  • audit_retention_days / audit_archive_days config settings

v1.5.2 — PII Restoration:

  • 5 general health patterns restored — brings total back to 44 from 39

v1.6.0 — Compliance Dashboard:

  • akios dashboard — local compliance dashboard reading from audit trail
  • Minor bug fixes and performance improvements

Migration Notes

PII boundary change (v1.4.0 — ⚠ Breaking): If you relied on healthcare PII patterns (NPI, DEA, MRN) or financial patterns in the OSS regex engine, these are now available only via EnforceCore's NER backend:

pip install akios[enforcecore] enforcecore[ner]
# Then in config.yaml:
use_enforcecore: true

Ollama users (v1.4.2+): Install Ollama separately, then configure:

AKIOS_LLM_PROVIDER=ollama
AKIOS_LLM_MODEL=llama3.2
OLLAMA_HOST=http://localhost:11434

New agents (v1.1.0+): No migration needed — webhook and database agents are additive. Existing workflows using only filesystem, http, llm, tool_executor continue unchanged.

Plugin system (v1.1.0+): If you wrote custom tool_executor wrappers, consider converting to proper plugins:

pip install akios-my-plugin  # Any package with akios.agents entry point

Audit migration (v1.5.0+): Optionally migrate your JSONL audit ledger to a database:

akios audit migrate --backend sqlite --target audit/audit.db

Verification after upgrade:

akios --version                    # Should show 1.6.0
akios status --security            # Verify all protections active
akios doctor                       # Run 9 diagnostic checks

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.6.0

# 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.6.0
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.6.0

# 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.6.0
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.6.0 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.6.0

# Test run
docker run --rm akiosai/akios:v1.6.0 --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.6.0
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.6.0
    
  - 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.6.0+
  • 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