GitHub - NicolasCalarco/tokioai: Autonomous AI Agent Framework — Connect Claude, GPT, or Gemini to your infrastructure. 30+ tools: servers, Docker, databases, IoT, drones, WAF, cloud. Three interfaces: CLI, REST API, Telegram Bot. Self-hosted, security-first.

████████╗ ██████╗ ██╗  ██╗██╗ ██████╗      █████╗ ██╗
╚══██╔══╝██╔═══██╗██║ ██╔╝██║██╔═══██╗    ██╔══██╗██║
   ██║   ██║   ██║█████╔╝ ██║██║   ██║    ███████║██║
   ██║   ██║   ██║██╔═██╗ ██║██║   ██║    ██╔══██║██║
   ██║   ╚██████╔╝██║  ██╗██║╚██████╔╝    ██║  ██║██║
   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝ ╚═════╝     ╚═╝  ╚═╝╚═╝

Autonomous AI Agent Framework

Connect an LLM to your entire infrastructure. Not a chatbot — an agent that gets things done.

TokioAI connects Claude, GPT, or Gemini to your servers, databases, Docker containers, IoT devices, DNS, and cloud infrastructure through a secure tool-calling architecture.

Getting Started · Features · Architecture · WAF Dashboard · Custom Tools

Demo

🌀 tokio> restart the nginx container and show me the last 20 lines of its logs

  🔧 docker restart nginx...
  🔧 docker logs --tail 20 nginx...

✅ Container nginx restarted successfully.

Last 20 lines:
2026/03/01 14:23:01 [notice] 1#1: signal process started
2026/03/01 14:23:01 [notice] 1#1: using the "epoll" event method
2026/03/01 14:23:01 [notice] 1#1: nginx/1.25.4
2026/03/01 14:23:01 [notice] 1#1: start worker processes
...

🌀 tokio> _

🧬 Philosophy

Most "AI tools" are chatbots with a nice UI. You type, it talks back. That's it.

TokioAI was built with a different belief: AI should execute, not just respond.

The world doesn't need another chatbot. It needs an agent that can restart your containers at 3 AM, query your database when something breaks, block an attacker's IP in real-time, and SSH into your server to fix what's wrong — all while you sleep.

TokioAI is built by a security architect who got tired of switching between 15 terminals, 8 dashboards, and 3 cloud consoles to do what one intelligent agent could do in seconds. Every tool in this framework exists because it solved a real problem in production, not because it looked good in a demo.

Principles:

Execute, don't chat — Every tool does something real. No decorative features.
Security first — Three layers of protection because an agent with bash access is a weapon. Treat it like one.
Own your infra — Self-hosted, no SaaS dependencies, your data stays on your machines.
Simple > clever — Python, Docker, PostgreSQL. No Kubernetes, no microservices, no buzzwords.

✨ Features

🤖 Multi-Provider LLM

Anthropic Claude (Direct API or Vertex AI)
OpenAI GPT (GPT-4o, GPT-4, etc.)
Google Gemini (Flash, Pro)
Automatic fallback between providers

🛡️ Security Layers

Prompt Guard — WAF for LLM prompts (injection detection + audit log to PostgreSQL)
Input Sanitizer — Blocks reverse shells, crypto miners, fork bombs, SQL injection
API Auth — Key-based authentication + rate limiting
Telegram ACL — Owner-based access control

🔧 30+ Built-in Tools

Category	Tools
System	`bash`, `python`, `read_file`, `write_file`
Network	`curl`, `wget`
Docker	`ps`, `logs`, `start/stop/restart`, `exec`, `stats`
Database	`postgres_query` (SQL injection protected)
SSH	`host_control` (remote server management)
IoT	`home_assistant` (lights, sensors, automations)
Cloud	`gcp_waf`, `gcp_compute` (full GCP management)
DNS	`hostinger` (DNS record management)
Router	`router` (OpenWrt management)
Tunnels	`cloudflared` (Cloudflare tunnels)
Docs	`document` (generate PDF, PPTX, CSV)
Calendar	`calendar` (Google Calendar)
Tasks	`task_orchestrator` (multi-step automation)
Security	`prompt_guard` (injection detection)

🧠 Agent Engine

Multi-round tool-calling loop with automatic retry
Session memory — Conversation history in PostgreSQL
Workspace memory — Persistent notes across sessions
Error learning — Remembers failures to avoid repeating them
Context builder — Dynamic system prompts based on available tools
Container watchdog — Auto-restarts crashed containers
Plugin system — Drop-in custom tools

📱 Three Interfaces

💻 CLI

🌐 REST API

📲 Telegram Bot

Interactive terminal with Rich formatting

╔══════════════════════════╗
║  ████████╗ ██████╗  ...  ║
║  Autonomous AI Agent v2  ║
╚══════════════════════════╝

LLM: Claude 3.5 Sonnet
Tools: 32 disponibles

🌀 tokio> _

FastAPI server with auth & CORS

curl -X POST localhost:8000/chat \
  -H "Authorization: Bearer KEY" \
  -d '{"message": "list containers"}'

# Response:
{
  "response": "Running containers:\n
    nginx (Up 3 days)\n
    postgres (Up 3 days)",
  "tools_used": ["docker"],
  "tokens": 847
}

Full multimedia support:

📷 Images — Analyzed via Vision API
🎤 Voice — Transcribed via Whisper/Gemini
🎵 Audio files
📄 Documents (PDF, DOCX, CSV, code)
🔗 YouTube link analysis
📎 File generation (PDF, CSV, PPTX sent back to you)

🚀 Quick Start

Option 1: Docker (easiest)

git clone https://github.com/TokioAI/tokioai-v1.8.git tokioai
cd tokioai
cp .env.example .env

# Edit .env — set at least ANTHROPIC_API_KEY (or OPENAI_API_KEY or GEMINI_API_KEY)
nano .env

docker compose up -d

This starts 3 containers: PostgreSQL, TokioAI API (port 8200), and Telegram bot (if configured).

Option 2: Setup Wizard

git clone https://github.com/TokioAI/tokioai-v1.8.git tokioai
cd tokioai
python3 -m venv venv && source venv/bin/activate
pip install -e .
tokio setup

The wizard walks you through LLM provider, database, Telegram, and optional features — then generates .env and docker-compose.yml.

Option 3: Manual Setup

git clone https://github.com/TokioAI/tokioai-v1.8.git tokioai
cd tokioai

cp .env.example .env
# Edit .env — set your API key

python3 -m venv venv && source venv/bin/activate
pip install -e .

# Interactive CLI
tokio

# Or start API server
tokio server

CLI Commands

tokio              # Interactive chat session
tokio server       # Start REST API server
tokio setup        # Run setup wizard
tokio status       # Show agent and infrastructure status
tokio tools        # List available tools
tokio "message"    # Single message mode (non-interactive)

Remote CLI (Docker / Cloud deployments)

If TokioAI is running inside a Docker container (local or cloud VM), use docker exec:

# Interactive session (backspace, arrows, and history work)
docker exec -it tokio-agent python3 -m tokio_agent.cli

# Single message
docker exec tokio-agent python3 -m tokio_agent.cli "list all containers"

# Status check
docker exec tokio-agent python3 -m tokio_agent.cli status

Over SSH (e.g., to a cloud VM):

# Interactive session — the -t flag is required for proper terminal support
ssh -t user@your-server "docker exec -it tokio-agent python3 -m tokio_agent.cli"

# Single message
ssh user@your-server "docker exec tokio-agent python3 -m tokio_agent.cli 'what is the WAF status?'"

Interactive commands inside the CLI: /tools, /status, /clear, /exit.

⚙️ Configuration

All configuration is via environment variables. Copy .env.example to .env and fill in your values.

Required

Variable	Description
`LLM_PROVIDER`	`anthropic`, `openai`, or `gemini`
`ANTHROPIC_API_KEY`	Claude API key (or use Vertex AI)
`POSTGRES_PASSWORD`	PostgreSQL password

LLM via Vertex AI (optional — for Claude on GCP)

Only needed if you prefer using Claude through Google Cloud instead of the direct Anthropic API.

Variable	Description
`USE_ANTHROPIC_VERTEX`	`true` to use Vertex AI
`GCP_PROJECT_ID`	Your GCP project
`GOOGLE_APPLICATION_CREDENTIALS`	Path to service account JSON
`ANTHROPIC_VERTEX_REGION`	Region (e.g., `us-east5`)

Optional Features

Variable	Description
`TELEGRAM_BOT_TOKEN`	Telegram bot token from @BotFather
`TELEGRAM_OWNER_ID`	Your Telegram user ID
`HOST_SSH_HOST`	Remote server for SSH control
`HOME_ASSISTANT_URL`	Home Assistant instance URL
`CLOUDFLARE_API_TOKEN`	Cloudflare API token
`HOSTINGER_API_TOKEN`	Hostinger DNS API token

See .env.example for the full list.

🏗️ Architecture

TokioAI is a ReAct autonomous agent — not a message router. Full comparison with OpenClaw

Detailed Architecture

                         ┌─────────────────┐
                         │    Telegram Bot  │
                         │  (multimedia,    │
                         │   voice, images) │
                         └────────┬────────┘
                                  │
  ┌───────────┐           ┌───────┴───────┐           ┌─────────────────┐
  │           │           │               │           │   Agent Loop    │
  │    CLI    │──────────>│   FastAPI      │──────────>│  (multi-round   │
  │  (Rich)   │           │   Server      │           │   tool-calling) │
  │           │           │               │           │                 │
  └───────────┘           └───────────────┘           └────────┬────────┘
                                                               │
                                                    ┌──────────┴──────────┐
                                                    │   Tool Executor     │
                                                    │  ┌────────────────┐ │
                                                    │  │ Circuit Breaker│ │
                                                    │  │ Timeouts       │ │
                                                    │  │ Error Recovery │ │
                                                    │  └────────────────┘ │
                                                    └──────────┬──────────┘
                                                               │
                    ┌──────────────┬───────────────┬───────────┼──────────────┐
                    │              │               │           │              │
              ┌─────┴────┐  ┌─────┴─────┐  ┌─────┴────┐ ┌────┴─────┐ ┌─────┴─────┐
              │  System  │  │  Docker   │  │ Database │ │   SSH    │ │   Cloud   │
              │ bash     │  │ ps/logs   │  │ postgres │ │ host_ctl │ │ gcp_waf   │
              │ python   │  │ restart   │  │ query    │ │ curl     │ │ IoT/DNS   │
              │ files    │  │ exec      │  │          │ │ wget     │ │ tunnels   │
              └──────────┘  └───────────┘  └──────────┘ └──────────┘ └───────────┘

                    ┌──────────────────────────────────────────────────────┐
                    │                  Security Layers                    │
                    │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
                    │  │ Prompt Guard │  │   Input      │  │  Secure   │ │
                    │  │ (WAF for LLM │  │  Sanitizer   │  │  Channel  │ │
                    │  │  prompts)    │  │ (cmd filter) │  │ (API auth)│ │
                    │  └──────────────┘  └──────────────┘  └───────────┘ │
                    └──────────────────────────────────────────────────────┘

                    ┌──────────────────────────────────────────────────────┐
                    │                   Persistence                      │
                    │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
                    │  │   Session    │  │  Workspace   │  │   Error   │ │
                    │  │   Memory    │  │   Memory     │  │  Learner  │ │
                    │  │ (PostgreSQL) │  │ (cross-sess) │  │ (failures)│ │
                    │  └──────────────┘  └──────────────┘  └───────────┘ │
                    └──────────────────────────────────────────────────────┘

Key Modules

Module	Description	Lines
`engine/agent.py`	Multi-round agent loop with tool calling	462
`engine/tools/executor.py`	Async execution with timeouts and circuit breaker	210
`engine/tools/builtin/loader.py`	Registers all 30+ built-in tools	542
`engine/security/prompt_guard.py`	Prompt injection WAF with PostgreSQL audit log	223
`engine/security/input_sanitizer.py`	Command/SQL/path sanitization	161
`engine/memory/session.py`	Conversation persistence	152
`engine/memory/workspace.py`	Cross-session persistent memory	283
`engine/llm/`	Multi-provider LLM abstraction	6 files
`bots/telegram_bot.py`	Full multimedia Telegram bot	1127
`setup_wizard.py`	Interactive setup wizard	707

🔒 Security

TokioAI has three security layers that protect against prompt injection, dangerous commands, and unauthorized access:

Layer 1: Prompt Guard (LLM WAF)

Detects and blocks prompt injection attacks before they reach the LLM:

Role override attempts ("ignore previous instructions")
System prompt extraction ("print your system prompt")
Delimiter injection ("```system", "<|endoftext|>")
Encoding attacks (base64/hex-encoded injections)
Tool abuse patterns ("call bash with rm -rf")

All attempts are logged to PostgreSQL with timestamp, risk level, categories, and input preview.

Layer 2: Input Sanitizer

Blocks dangerous commands before tool execution:

Reverse shells (nc -e, bash -i)
Crypto miners (xmrig, stratum://)
Fork bombs (:(){ :|:& };:)
Destructive commands (rm -rf /, mkfs, dd if=/dev/zero)
SQL injection ('; DROP TABLE)
Path traversal (../../etc/passwd)

Layer 3: Secure Channel

API key authentication for REST endpoints
Rate limiting per client
Telegram ACL with owner-only admin commands

🚢 Deployment Modes

The setup wizard (tokio setup) lets you choose how to deploy:

Mode	What runs locally	What runs in cloud	Best for
1. Full Local (default)	Everything — CLI, API, Telegram bot, PostgreSQL	Nothing	Development, testing, personal use
2. Hybrid	TokioAI CLI + tools	WAF, Kafka, PostgreSQL on GCP	Production with local agent control
3. Full Cloud	Nothing	Everything in GCP	Headless servers, max availability

Note: Mode 1 is the default and works perfectly without any cloud account. The WAF/GCP modules (tokio_cloud/) are entirely optional — the core agent, CLI, API, and Telegram bot work 100% standalone.

Tailscale Mesh — Connect to Any Hardware

When running in Full Cloud mode, TokioAI can still control local hardware (Raspberry Pi, routers, IoT devices) through a Tailscale mesh VPN:

Cloud VM (GCP/AWS)                    Your Home
┌────────────────┐                   ┌─────────────────┐
│ TokioAI Agent  │◄── Tailscale ───►│ Raspberry Pi    │
│ Telegram Bot   │    (WireGuard)   │ Router (SSH)    │
│ WAF/SOC        │                  │ IoT devices     │
└────────────────┘                  └─────────────────┘
  100.x.x.1                           100.x.x.2

Zero cost — Tailscale free tier covers up to 100 devices
Zero config — Just curl -fsSL https://tailscale.com/install.sh | sh && tailscale up
Auto-reconnect — Switch networks, reboot, change ISP — it just works
Subnet routing — Access your entire LAN (routers, printers, NAS) from the cloud
No ports exposed — All TokioAI access via Telegram, no public endpoints

For setup instructions, see docs/TAILSCALE-MESH.md.

Home Assistant — IoT Device Control

TokioAI controls IoT devices (lights, switches, vacuum, Alexa, sensors) through Home Assistant's REST API. A strict device whitelist prevents accidental control of unintended entities.

For setup instructions, see docs/HOME-ASSISTANT.md.

Use docker-compose.cloud.yml for cloud deployments with shared PostgreSQL:

docker compose -f docker-compose.cloud.yml up -d

🌐 WAF Dashboard (Optional)

This section is optional. The core TokioAI agent works perfectly without the WAF. Deploy the WAF only if you want to protect a web application with real-time attack detection.

TokioAI includes a complete Web Application Firewall with a cyberpunk-themed SOC dashboard.

Dashboard Features

┌──────────────────────────────────────────────────────────────────────┐
│  ◉ TokioAI WAF          v3-supreme                  ● LIVE    🔄  │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Requests │ │ Blocked  │ │ Unique   │ │ Critical │ │ Episodes │  │
│  │  12,847  │ │    342   │ │  1,205   │ │     47   │ │     12   │  │
│  │  ▲ 23%   │ │          │ │          │ │          │ │          │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│                                                                      │
│  ┌────────────────────────────────────┐ ┌──────────────────────┐    │
│  │  📊 Traffic Timeline              │ │ 🛡️ OWASP Top 10     │    │
│  │  ████                      ██     │ │                      │    │
│  │  █████                    ████    │ │  A01  Broken Access  │    │
│  │  ██████      ███         ██████   │ │  A03  Injection      │    │
│  │  ████████  ██████  ████ ████████  │ │  A07  XSS            │    │
│  │  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  │ │  A10  SSRF           │    │
│  └────────────────────────────────────┘ └──────────────────────┘    │
│                                                                      │
│  ┌────────────────────────────────────┐ ┌──────────────────────┐    │
│  │  🌍 Attack Origins (World Map)    │ │ 🔴 LIVE ATTACKS      │    │
│  │                                    │ │                      │    │
│  │     ·  ··                          │ │ ● 45.33.x.x SQLI    │    │
│  │    ·    ···   ····  ····           │ │   /api/users?id=1'   │    │
│  │          ··    ··   · ·            │ │                      │    │
│  │      ·                     🎯      │ │ ● 91.xx.x.x XSS     │    │
│  │       ·                            │ │   /search?q=<script> │    │
│  │                 ·                  │ │                      │    │
│  │               ·                    │ │ ● 185.x.x.x SCAN    │    │
│  └────────────────────────────────────┘ │   /.env              │    │
│                                         └──────────────────────┘    │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │ 📊 Trafico │ 📋 Episodios │ 🚫 Bloqueados │ 🏆 Top IPs │  │    │
│  │ 🔍 Signatures │ ⛓️ Kill Chain │ 📝 Auditoria              │    │
│  ├──────────────────────────────────────────────────────────────┤    │
│  │ Hora      IP            Method  URI           Sev    Threat │    │
│  │ 14:23:01  45.33.32.x    GET     /api/users    HIGH   SQLI   │    │
│  │ 14:22:58  91.108.x.x    POST    /login        CRIT   BRUTE  │    │
│  │ 14:22:45  185.220.x.x   GET     /.env         HIGH   SCAN   │    │
│  │ 14:22:30  23.94.x.x     GET     /wp-admin     MED    PROBE  │    │
│  └──────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘

WAF Engine Features

Feature	Description
25 WAF Signatures	SQL injection, XSS, command injection, path traversal, Log4Shell, SSRF, and more
7 Behavioral Rules	Rate limiting, brute force detection, scanner detection, honeypot traps
Real-time Detection	Nginx → Kafka → Realtime Processor pipeline
IP Reputation	Score-based reputation tracking per IP in PostgreSQL
Multi-phase Correlation	Recon → Probe → Exploit → Exfil attack chain detection
Auto-blocking	Instant block on critical signatures (confidence ≥ 0.90)
Honeypot Endpoints	Fake `/wp-admin`, `/phpmyadmin`, `/.env` that instantly flag attackers
GeoIP Integration	Attack origin mapping via DB-IP
Threat Intelligence	AbuseIPDB integration for IP reputation lookups
SSE Live Feed	Real-time Server-Sent Events attack stream
Attack Heatmap	Hour-of-day × Day-of-week threat visualization
CSV Export	Export filtered logs for analysis
Zero-Day Entropy Detector	Detects obfuscated payloads that bypass regex WAF signatures using Shannon entropy, URL-encoding density, and encoding layer analysis. O(n) per request, <0.1ms, no ML required
Self-Contained DDoS Shield	Multi-layer DDoS mitigation without Cloudflare: iptables/ipset (kernel) + GCP Firewall (network) + nginx blocklist (app). 7 anti-false-positive protections, progressive TTL blocking
SOC Terminal	Rich-based terminal UI for live security monitoring with autonomous AI narration mode. Designed for SOC displays and conference demos

Zero-Day Entropy Detector (`zero_day_entropy.py`)

Catches obfuscated/encoded attack payloads that traditional regex WAF signatures miss:

Detection layers:
  1. Shannon entropy — obfuscated payloads have high entropy (>4.5)
  2. Encoding layer counter — double/triple encoding detection (17 patterns)
  3. URL-encoding density — normal URLs: 0-10%, attacks: 30-80%+
  4. Character ratio anomaly — special char vs alphanumeric ratio
  5. Structural depth — nested encoding patterns

Performance: 9,500+ payloads/sec, <0.1ms average, zero I/O, zero ML model.

Examples of payloads detected:

Double/triple URL-encoded SQLi (%2527%2520OR%2520...)
JNDI obfuscation (${lower:j}${lower:n}${lower:d}${lower:i})
Overlong UTF-8 path traversal (%c0%ae%c0%ae%c0%af...)
Base64-encoded XSS in query parameters
CharCode obfuscation (String.fromCharCode(...))

DDoS Shield v2 (`ddos_shield.py`)

Self-contained DDoS mitigation — zero external dependencies (no Cloudflare required):

Layer 0: GCP Firewall     — Network-level blocking (before traffic reaches VM)
Layer 1: iptables/ipset   — Kernel-level rate limiting (50 conn/s per IP)
Layer 2: nginx             — Application-level rate limiting (10 req/s per IP)
Layer 3: DDoS Shield       — Intelligent detection + auto-blocking

Anti-false-positive protections:

Hardcoded whitelist (localhost, Docker, Tailscale mesh, GCP health checks)
Configurable whitelist via DDOS_WHITELIST and OWNER_IPS env vars
Friendly User-Agent 2x threshold multiplier (Googlebot, Bingbot, etc.)
Sustained-rate check (10s window — blocks only persistent abuse)
URI targeting filter (common paths need 4x more IPs to trigger)
Progressive TTL: 5min → 30min → 2h → 24h (based on offense count)
Max 500 blocked IPs (auto-eviction of oldest entries)

SOC Terminal (`soc_terminal.py`)

Live security monitoring terminal with Rich panels:

# Connected to live dashboard:
python3 soc_terminal.py --api http://YOUR_SERVER --user admin --pass SECRET --autonomous

# Demo mode (simulated data, no server needed):
python3 soc_terminal.py --demo

Features:

Live attacks table with severity icons and OWASP classification
Zero-Day Radar panel with animated scanning display
DDoS Shield status with RPS bar graph
System statistics (requests, threats, blocks, episodes)
Blocked IPs panel with TTL countdown
Autonomous narration mode — Tokio analyzes patterns, trends, and new threats in real-time and narrates them without human input

WAF Deployment (Optional)

The WAF can be deployed on any machine (local, VPS, or GCP VM):

cd tokio_cloud/gcp-live
cp .env.example .env
# Edit .env — set your domain, backend IP, and passwords
nano .env

docker compose up -d

Deploys 7 containers: PostgreSQL, Zookeeper, Kafka, Nginx WAF proxy, Log processor, Realtime attack detector, SOC Dashboard API.

Requirements: A server with Docker, a domain pointing to it, and a backend to protect. No GCP account required — works on any VPS or local machine.

🔌 Adding Custom Tools

Method 1: Built-in Tool

Create a file in tokio_agent/engine/tools/builtin/:

# my_tools.py
import logging

logger = logging.getLogger(__name__)

async def my_custom_tool(action: str, params: dict = None) -> str:
    """Your custom tool logic."""
    params = params or {}
    if action == "hello":
        return f"Hello, {params.get('name', 'world')}!"
    return f"Unknown action: {action}"

Register in loader.py:

from .my_tools import my_custom_tool

registry.register(
    name="my_tool",
    description="My custom tool",
    category="Custom",
    parameters={"action": "Action to perform", "params": "Additional parameters"},
    executor=my_custom_tool,
)

Method 2: Plugin (Hot-reload)

Drop a Python file in workspace/plugins/ — auto-discovered on startup:

# workspace/plugins/weather.py
TOOL_NAME = "weather"
TOOL_DESCRIPTION = "Get current weather for a city"
TOOL_PARAMETERS = {"city": "City name"}
TOOL_CATEGORY = "Custom"

async def execute(city: str) -> str:
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.get(f"https://wttr.in/{city}?format=3")
        return resp.text

📡 API Endpoints

Method	Path	Description
`POST`	`/chat`	Send a message and get a response
`GET`	`/health`	Health check
`GET`	`/tools`	List available tools
`GET`	`/sessions`	List sessions
`DELETE`	`/sessions/{id}`	Delete a session

Example

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"message": "list running docker containers", "session_id": "my-session"}'

Response:

{
  "response": "Here are the running containers:\n\n| Name | Status | Ports |\n|------|--------|-------|\n| nginx | Up 3 days | 80, 443 |\n| postgres | Up 3 days | 5432 |",
  "tools_used": ["docker"],
  "rounds": 1,
  "tokens_used": 847,
  "session_id": "my-session"
}

📁 Project Structure

tokioai/
├── tokio_agent/
│   ├── cli.py                         # Interactive CLI with Rich
│   ├── setup_wizard.py                # Setup wizard (tokio setup)
│   ├── api/
│   │   └── server.py                  # FastAPI REST server
│   ├── bots/
│   │   ├── telegram_bot.py            # Telegram bot (multimedia)
│   │   └── Dockerfile.telegram
│   └── engine/
│       ├── agent.py                   # Agent loop (multi-round)
│       ├── context_builder.py         # Dynamic system prompt builder
│       ├── db.py                      # PostgreSQL helpers
│       ├── error_learner.py           # Error learning
│       ├── watchdog.py                # Container health watchdog
│       ├── llm/                       # LLM providers
│       │   ├── anthropic_llm.py       #   Claude (direct + Vertex AI)
│       │   ├── openai_llm.py          #   GPT-4o, GPT-4
│       │   └── gemini_llm.py          #   Gemini Flash, Pro
│       ├── memory/                    # Persistence layer
│       │   ├── session.py             #   Conversation history
│       │   └── workspace.py           #   Cross-session memory
│       ├── security/                  # Security layers
│       │   ├── prompt_guard.py        #   LLM prompt WAF
│       │   ├── input_sanitizer.py     #   Command sanitization
│       │   └── secure_channel.py      #   API authentication
│       └── tools/
│           ├── registry.py            # Tool registration
│           ├── executor.py            # Async executor + circuit breaker
│           ├── plugins/               # Plugin auto-loader
│           └── builtin/               # 30+ built-in tools
│               ├── loader.py          #   Tool registration
│               ├── system_tools.py    #   bash, python, files
│               ├── docker_tools.py    #   Docker management
│               ├── db_tools.py        #   PostgreSQL queries
│               ├── gcp_tools.py       #   GCP WAF + Compute
│               ├── host_tools.py      #   SSH remote control
│               ├── iot_tools.py       #   Home Assistant
│               └── ...                #   + 10 more tool files
├── tokio_cloud/                       # ⚡ WAF deployment (100% OPTIONAL)
│   ├── gcp-live/                      # Production WAF stack
│   │   ├── docker-compose.yml         #   7-container stack
│   │   ├── dashboard-app.py           #   SOC dashboard (1385 lines)
│   │   ├── realtime-processor.py      #   WAF engine v5 (980+ lines)
│   │   ├── zero_day_entropy.py        #   Zero-day detector (entropy-based)
│   │   ├── ddos_shield.py             #   DDoS mitigation (self-contained)
│   │   ├── soc_terminal.py            #   SOC terminal UI (Rich-based)
│   │   ├── nginx.conf                 #   Reverse proxy + rate limiting
│   │   └── deploy.sh                  #   Deployment script
│   └── waf-deployment/                # WAF setup docs + ModSecurity
├── tests/                             # Test suite (10 test files)
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── pyproject.toml
└── .env.example

🧪 Tests

pip install pytest pytest-asyncio
pytest tests/ -v

📋 Requirements

Requirement	Version	Notes
Python	3.11+	Required
PostgreSQL	15+	Session/memory persistence
Docker	20+	Optional, for containerized deployment
LLM API Key	—	At least one: Anthropic, OpenAI, or Gemini

📜 License

👤 Author

A project by TokioAI Security Research, Inc.

Built by @daletoniris (MrMoz) — Security architect, hacker, builder.

TokioAI started as a personal tool to automate SOC operations and infrastructure management. It grew into a full framework because every time something broke at 3 AM, the answer was always the same: "the agent should handle this."

If you find it useful, drop a star. If you break it, open an issue. If you improve it, send a PR.

TokioAI Security Research, Inc.

Self-hosted AI that executes. Not a chatbot — an agent.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
docs		docs
tests		tests
tokio_agent		tokio_agent
tokio_cloud		tokio_cloud
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_ES.md		README_ES.md
coffee_ui.py		coffee_ui.py
docker-compose.cloud.yml		docker-compose.cloud.yml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Autonomous AI Agent Framework

Demo

🧬 Philosophy

✨ Features

🤖 Multi-Provider LLM

🛡️ Security Layers

🔧 30+ Built-in Tools

🧠 Agent Engine

📱 Three Interfaces

💻 CLI

🌐 REST API

📲 Telegram Bot

🚀 Quick Start

Option 1: Docker (easiest)

Option 2: Setup Wizard

Option 3: Manual Setup

CLI Commands

Remote CLI (Docker / Cloud deployments)

⚙️ Configuration

Required

LLM via Vertex AI (optional — for Claude on GCP)

Optional Features

🏗️ Architecture

Detailed Architecture

Key Modules

🔒 Security

Layer 1: Prompt Guard (LLM WAF)

Layer 2: Input Sanitizer

Layer 3: Secure Channel

🚢 Deployment Modes

Tailscale Mesh — Connect to Any Hardware

Home Assistant — IoT Device Control

🌐 WAF Dashboard (Optional)

Dashboard Features

WAF Engine Features

Zero-Day Entropy Detector (zero_day_entropy.py)

DDoS Shield v2 (ddos_shield.py)

SOC Terminal (soc_terminal.py)

WAF Deployment (Optional)

🔌 Adding Custom Tools

Method 1: Built-in Tool

Method 2: Plugin (Hot-reload)

📡 API Endpoints

Example

📁 Project Structure

🧪 Tests

📋 Requirements

📜 License

👤 Author

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Zero-Day Entropy Detector (`zero_day_entropy.py`)

DDoS Shield v2 (`ddos_shield.py`)

SOC Terminal (`soc_terminal.py`)

Packages