akios 1.0.7

AKIOS runtime for secure AI agent execution

AKIOS

The open-source security cage for AI agents

Kernel-hard sandbox · 50+ PII patterns · Merkle audit trail · Cost kill-switches

AKIOS wraps any AI agent in a hardened security cage — kernel-level process isolation,
real-time PII redaction, cryptographic Merkle audit trails, and automatic cost kill-switches —
so you can deploy AI workflows in regulated environments without building security from scratch.

Quick Start · Architecture · Features · Documentation · Contributing

🏗️ Architecture

Every workflow step passes through five security layers before anything touches the outside world.

              ┌────────────────────────────────────┐
              │        Untrusted AI Agents         │
              │        LLMs, Code, Plugins         │
              └──────────────────┬─────────────────┘
                                 │
                                 ▼
╔════════════════════════════════════════════════════════════════╗
║                     AKIOS SECURITY RUNTIME                     ║
║                                                                ║
║  ┌──────────────────────────────────────────────────────────┐  ║
║  │ 1. Policy Engine    allowlist verification               │  ║
║  │ 2. Kernel Sandbox   seccomp-bpf + cgroups v2             │  ║
║  │ 3. PII Redaction    50+ patterns, 6 categories           │  ║
║  │ 4. Budget Control   cost kill-switches, token limits     │  ║
║  │ 5. Audit Ledger     Merkle tree, SHA-256, JSONL          │  ║
║  └──────────────────────────────────────────────────────────┘  ║
║                                                                ║
╚════════════════════════════════╤═══════════════════════════════╝
                                 │
                                 ▼
              ┌────────────────────────────────────┐
              │      Protected Infrastructure      │
              │       APIs, Databases, Cloud       │
              └────────────────────────────────────┘

🚀 Quick Start

pip install akios
akios init my-project && cd my-project
akios setup                              # Configure LLM provider (interactive)
akios run templates/hello-workflow.yml    # Run inside the security cage

📦 Docker (all platforms — macOS, Linux, Windows)

curl -O https://raw.githubusercontent.com/akios-ai/akios/main/src/akios/cli/data/wrapper.sh
mv wrapper.sh akios && chmod +x akios
./akios init my-project && cd my-project
./akios run templates/hello-workflow.yml

What happens when you run a workflow

$ akios run workflow.yml

╔══════════════════════════════════════════════════════════╗
║                   AKIOS Security Cage                    ║
╠══════════════════════════════════════════════════════════╣
║  🔒 Sandbox:   ACTIVE (seccomp-bpf + cgroups v2)        ║
║  🚫 PII Scan:  50+ patterns loaded                      ║
║  💰 Budget:    $1.00 limit ($0.00 used)                  ║
║  📋 Audit:     Merkle chain initialized                  ║
╚══════════════════════════════════════════════════════════╝

  ▶ Step 1/3: read-document ─────────────────────────────
    Agent: filesystem │ Action: read
    ✓ PII redacted: 3 patterns found (SSN, email, phone)
    ✓ Audit event #1 logged

  ▶ Step 2/3: analyze-with-ai ───────────────────────────
    Agent: llm │ Model: gpt-4o │ Tokens: 847
    ✓ Prompt scrubbed before API call
    ✓ Cost: $0.003 of $1.00 budget
    ✓ Audit event #2 logged

  ▶ Step 3/3: save-results ─────────────────────────────
    Agent: filesystem │ Action: write
    ✓ Output saved to data/output/run_20250211_143052/
    ✓ Audit event #3 logged

══════════════════════════════════════════════════════════
  ✅ Workflow complete │ 3 steps │ $0.003 │ 0 PII leaked
══════════════════════════════════════════════════════════

🎯 Why AKIOS?

AI agents can leak PII to LLM providers, run up massive bills, execute dangerous code, and leave no audit trail. Every team building with LLMs faces this security engineering burden.

AKIOS provides compliance-by-construction — security guarantees that are architectural, not bolted on:

	Without AKIOS	With AKIOS
🚫	PII leaks to LLM providers	Automatic redaction before any API call
💸	Runaway API costs	Hard budget limits with kill-switches
📋	No audit trail for compliance	Cryptographic Merkle-chained logs
🔓	Manual security reviews	Kernel-enforced process isolation
🤞	Hope-based security	Proof-based security

🛡️ Key Features

🔒 Kernel-Hard Sandbox seccomp-bpf syscall filtering + cgroups v2 resource isolation on native Linux. Policy-based isolation on Docker (all platforms). 🚫 PII Redaction Engine 50+ detection patterns across 6 categories: personal, financial, health, digital, communication, location. Includes NPI, DEA, and medical records. Redaction happens before data reaches any LLM. 📋 Merkle Audit Trail Every action is cryptographically chained. Tamper-evident JSONL logs with SHA-256 proofs. Export to JSON for compliance reporting.

💰 Cost Kill-Switches Hard budget limits ($1 default) with automatic workflow termination. Token tracking across all providers. Real-time akios status --budget dashboard. 🤖 Multi-Provider LLM Support OpenAI, Anthropic, Grok (xAI), Mistral, Gemini — swap providers in one line of config. All calls are sandboxed, audited, and budget-tracked. 🏥 Industry Templates Healthcare (HIPAA), Banking (PCI-DSS), Insurance, Accounting (SOX), Government (FedRAMP), Legal — production-ready sector workflows out of the box.

📝 Workflow Schema

AKIOS orchestrates YAML-defined workflows through 4 secure agents — each running inside the security cage:

# workflow.yml — every step runs inside the cage
name: "document-analysis"
steps:
  - name: "read-document"
    agent: filesystem           # 📁 Path-whitelisted file access
    action: read
    parameters:
      path: "data/input/report.pdf"

  - name: "analyze-with-ai"
    agent: llm                  # 🤖 Token-tracked, PII-scrubbed
    action: complete
    parameters:
      prompt: "Summarize this document: {previous_output}"
      model: "gpt-4o"
      max_tokens: 500

  - name: "notify-team"
    agent: http                 # 🌐 Domain-whitelisted, rate-limited
    action: post
    parameters:
      url: "https://api.example.com/webhook"
      json:
        summary: "{previous_output}"

🔍 Preview what the LLM actually sees (after PII redaction)

$ akios protect show-prompt workflow.yml

Interpolated prompt (redacted):
  "Summarize this document: The patient [NAME_REDACTED] with
   SSN [SSN_REDACTED] was seen at [ADDRESS_REDACTED]..."

# 3 PII patterns redacted before reaching OpenAI

🔐 Security Levels

Environment	Isolation	PII	Audit	Budget	Best For
Native Linux	seccomp-bpf + cgroups v2	✅	✅	✅	Production, maximum guarantees
Docker (all platforms)	Container + policy-based	✅	✅	✅	Development, cross-platform

Native Linux provides kernel-level guarantees where dangerous syscalls are physically blocked. Docker provides strong, reliable security across macOS, Linux, and Windows.

⌨️ CLI Reference

Command	Description
akios init my-project	Create secure workspace with templates
akios setup	Configure LLM provider (interactive)
akios run workflow.yml	Execute workflow inside security cage
akios workflow validate w.yml	Validate workflow YAML against schema
akios status	Security & budget dashboard
akios status --budget	Cost tracking breakdown per workflow
akios cage up / down	Activate / destroy cage + all data
akios cage up --no-pii --no-audit	Ablation mode (benchmarking)
akios cage down --passes N	Secure overwrite with N passes
akios protect scan file.txt	Scan file for PII patterns
akios protect show-prompt w.yml	Preview what the LLM sees (redacted)
akios audit verify	Verify Merkle chain integrity
akios audit stats	Audit ledger statistics (event count, Merkle root)
akios audit rotate	Rotate audit log with Merkle chain linkage
akios audit export --format json	Export audit logs for compliance
akios doctor	System health check
akios templates list	Browse industry workflow templates
akios http GET https://...	Secure HTTP request via agent

⚡ Performance

Measured on AWS EC2 t4g.micro (ARM64, 1 GB RAM) — the smallest instance available.

Operation	Latency	Notes
Full security pipeline	0.47 ms	PII + policy + audit + budget
PII scan (50+ patterns)	0.46 ms	All 6 categories
SHA-256 Merkle hash	0.001 ms	Per audit event
CLI cold start (Docker)	~1.4 s	One-time startup

Sub-millisecond overhead means security adds virtually zero cost to your workflows.

📊 Reproducibility & methodology

All benchmarks are reproducible. See EC2 Performance Testing for the full methodology, validation procedures, and instructions to run on your own infrastructure.

📚 Documentation

	Guide	Description
🚀	Getting Started	3-minute setup guide
⌨️	CLI Reference	All commands and flags
⚙️	Configuration	Settings, .env, config.yaml
🔒	Security	Architecture and threat model
🤖	Agents	Filesystem, HTTP, LLM, Tool Executor
🐳	Deployment	Docker, native Linux, EC2
🔧	Troubleshooting	Common issues and fixes
📝	Changelog	Release history

🏛️ Project Structure

Click to expand source tree

src/akios/
├── cli/                        # 18 CLI commands (argparse)
│   └── commands/               # audit, compliance, doctor, http, protect, run, ...
├── config/                     # YAML + .env configuration, themes, detection
├── core/
│   ├── analytics/              # Cost tracking (cost_tracker.py)
│   ├── audit/                  # Merkle-chained JSONL ledger
│   │   └── merkle/             # SHA-256 Merkle tree (tree.py, node.py)
│   ├── compliance/             # Compliance report generation
│   ├── runtime/
│   │   ├── agents/             # LLM, HTTP, Filesystem, ToolExecutor
│   │   ├── engine/             # Workflow orchestrator + kill switches
│   │   ├── llm_providers/      # OpenAI, Anthropic, Grok, Mistral, Gemini
│   │   └── workflow/           # YAML parser + validator
│   └── ui/                     # Rich terminal output, PII display, colors
└── security/
    ├── pii/                    # 50+ regex patterns, 6 categories (detector, redactor, rules)
    ├── sandbox/                # cgroups v2 resource isolation (manager, quotas)
    ├── syscall/                # seccomp-bpf policy + interceptor
    └── validation.py           # Runtime security validation

🔬 Research

AKIOS introduces compliance-by-construction — the idea that security guarantees should be architectural properties of the runtime, not features that can be misconfigured or bypassed.

Our NeurIPS 2026 submission formalizes this paradigm. Preprint coming soon on arXiv.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/akios-ai/akios.git
cd akios
make build    # Build Docker image
make test     # Run test suite

Good first issues are tagged with good first issue.

💬 Community

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker
• 🔒 Security issues → [e-mail] (private disclosure)

⚖️ Legal & Disclaimers

EU AI Act: AKIOS is not designed for "high-risk" use cases under the EU AI Act. For such deployments, consult a compliance expert and implement additional regulatory controls on top of AKIOS.

AKIOS is provided "AS IS" without warranty of any kind. By using AKIOS you acknowledge:

• You are responsible for your own API keys, cloud costs (AWS/GCP/Azure), IAM configurations, credential management, and infrastructure security. AKIOS cost kill-switches cover LLM API spend only — not compute, storage, or data transfer.
• Docker mode provides strong policy-based security but does not enforce host filesystem permissions or kernel-level seccomp-bpf isolation. For maximum security, use native Linux with sudo.
• Performance varies by instance type, region, load, and configuration. Published benchmarks are measured on AWS EC2 t4g.micro (ARM64) in us-east-1 and may not match your environment.
• PII redaction uses regex pattern matching (50+ patterns, >95% accuracy) — it is not a substitute for professional data governance. Review output before sharing with external parties.
• Audit logs in Docker may lose up to ~100 events if the container is forcefully killed (SIGKILL) during a flush window. Use native Linux for zero-loss audit durability.

AKIOS is not responsible for: cloud infrastructure charges, credential leaks, data breaches from misconfigured deployments, performance on untested platforms, or regulatory compliance decisions. See LEGAL.md and SECURITY.md for full details.

📄 License

AKIOS is licensed under GPL-3.0-only. See NOTICE, LEGAL.md, and THIRD_PARTY_LICENSES.md.

---

Run AI agents safely — anywhere.

Get Started · CLI Reference · Agents · Changelog

_{Built by akios-ai · Licensed under GPL-3.0-only}