Skip to content

Home

Jump to bottom
Hamed Ghasemzadeh edited this page Nov 3, 2025 · 1 revision

AION-OS (OMERTAOS) Wiki

“A modular AI orchestration platform combining a TypeScript gateway, FastAPI control plane, and Rust execution modules.” (GitHub)

Table of Contents

  1. Overview

  2. Project Vision & Goals

  3. Architecture & Modules

  4. Current Status / Milestones

  5. Roadmap (Short-term, Mid-term, Long-term)

  6. Contributor Guidelines

  7. Getting Started

  8. Documentation & References

  9. FAQ

  10. Acknowledgements & License

1. Overview

What is AION-OS?

  • AION-OS is a modular AI orchestration platform: TypeScript gateway + FastAPI control plane + Rust/WASM modules. (GitHub)

  • Purpose: enable you (and your team) to orchestrate AI agents with predictable costs, auditable decisions, real-time feedback, multi-plane architecture. (GitHub)

  • Key features: policy-aware routing (local | api | hybrid), spec-driven delivery, secure sandboxing, observability & big-data overlay. (GitHub)

  • Target users: teams building scalable distributed AI agent systems, enterprise control & audit, edge/in-cloud hybrid.

2. Project Vision & Goals

Vision:

  • To become the open-source foundation for orchestrating multi-agent systems, combining routing, execution modules, monitoring, big-data overlay, and enterprise-grade controls (RBAC, SBOM, sandboxing).

  • To provide a standard spec (.aionos/ folder) so that agent workflows, modules, policies, and deployments are repeatable, auditable and maintainable.

Goals:

  • Provide a fully containerised “one-click” developer and production bootstrap (Linux & Windows).

  • Modular execution engine that supports Rust/WASM modules for safe, high-performance runtime.

  • A policy and routing layer to decide execution paths (local vs API vs hybrid) with budgets and SLAs.

  • Observability and big-data stack (Kafka, ClickHouse, Spark/Flink, Airflow) optional but integrated.

  • Provide tooling for spec-driven development, contracts for each agent module, CI/CD pipelines, and developer workflows.

  • Support edge deployments (reverse proxy setup, Apache/NGINX, IPv6) and cloud/Kubernetes deployments.

  • Foster community contributions: connectors (webhooks, messaging, IoT), IDE/MCP integrations, one-click wizards for spec creation.

3. Architecture & Modules

Layered architecture:

  • Gateway: TypeScript / Fastify router — handles REST/gRPC/SSE/WS, authentication, quotas, idempotency. (GitHub)

  • Control Plane: FastAPI service for orchestration, policy & budget management, storage adapters. (GitHub)

  • Execution Modules: Rust or WASM sandboxed units, signed modules, resource-limited execution. (GitHub)

  • Console / UI: Next.js “Glass style” UI with live logs, task board, real-time feedback. (GitHub)

  • Spec folder (.aionos/): repository-level contracts for planning, implementation, testing, documentation. (GitHub)

  • Big Data / Observability Overlay (optional): Kafka → ClickHouse, Spark/Flink, Airflow, Superset, Telemetry via OpenTelemetry, Prometheus/Grafana. (GitHub)

  • Deployment Layer: docker-compose / Kubernetes manifests, systemd, edge installs with Apache reverse proxy, IPv6 handling. (GitHub)

Module breakdown (folders):
Inside the repo you’ll find (as listed) folders like: agents/templates, ai_registry, bigdata, cli, config, console, control, deploy, docs, explorer, gateway, kernel, modules, policies, protos/aion/v1, schemas, scripts, tests, tools, typer. (GitHub)

4. Current Status / Milestones

What’s done so far:

  • Repository scaffold with multiple modules, dev stack (Linux + Windows installers) configured. (GitHub)

  • Core architecture described in README.

  • Basic quick start instructions (docker-compose). (GitHub)

  • License: Apache-2.0. (GitHub)

What still needs validation / is in progress:

  • Full connector pack (webhooks, messaging, IoT) still listed as roadmap. (GitHub)

  • IDE/MCP adapters, one-click spec wizard still planned. (GitHub)

  • Possibly multiple modules/tests etc need deeper coverage.

Status snapshot (for your own tracking):
You could include a table like:

Component Status Notes
Gateway (TS/Fastify) ✅ Core routing implemented
Control Plane (FastAPI) ✅ Policy & budget layer present
Execution Modules (Rust/WASM) 🔧 Base framework in place
Console (Next.js) ✅ UI scaffolding done
Spec folder (.aionos/) ✅ Contracts defined
Edge Install / Apache 🔧 Script exists, testing required
Big-Data overlay 🔧 Optional but needs validation
Connectors (webhooks/messaging/IoT) ❌ Planned in roadmap
IDE/MCP integrations ❌ Planned in roadmap

You can update this chart as you progress.

5. Roadmap

From the README you already have these items listed: (GitHub)

Short-term (Next 1-3 months):

  • Provide One-Click Spec Wizard to bootstrap .aionos/ folder.

  • Finalise and publish connector pack (webhooks, messaging, IoT).

  • Increase module test coverage (unit/integration/load).

  • Polish Windows installer + edge installer flows (Apache).

  • Create sample modules showing “local”, “api”, “hybrid” routing paths.

  • Improve documentation: architecture diagrams, developer workflow, ADRs.

Mid-term (3-9 months):

  • IDE/MCP adapters (e.g., VSCode extension, IntelliJ plugin) for safe tool/file access.

  • Expand Big Data overlay: include more tutorials, deployment manifests, BI dashboards.

  • Harden security: supply chain (SBOM, Cosign), sandboxing, RBAC multi-tenant features.

  • Provide more pre-built modules (Rust/WASM) for common AI workflows.

  • Performance/load testing: benchmark local vs API hybrid routing, module sandboxing overhead.

Long-term (9–18 months+):

  • Support large-scale distributed deployments (Kubernetes clusters, multi-region).

  • Provide marketplace of community modules/connectors.

  • Edge-native version: deployable on IoT devices, gateways, offline scenarios.

  • Integrations with more agent frameworks, LLM platforms, streaming data systems.

  • Automate release process, semantic versioning, ensure backward compatibility, migration guides.

  • Possibly commercial services/add-ons (optional) or enterprise tier.

You can embed a timeline or Gantt chart here, or use GitHub Projects/Milestones to track.

6. Contributor Guidelines

How to contribute:

  • Please read the CONTRIBUTING.md and GOVERNANCE.md files. (GitHub)

  • Fork the repository, create a feature branch, make your changes, ensure tests pass, submit a pull request.

  • Use the CODE_OF_CONDUCT.md. (GitHub)

  • For large features, please open an issue or join the Discussions tab to align with maintainers.

  • All modules/contributions should adhere to the spec folder structure .aionos/, include tests, documentation, and manifest signing where applicable.

  • Maintain backward compatibility, add migration guides when needed.

  • Follow coding style: TS for gateway, Python for control plane, Rust for modules. Use linting, static analysis, and CI.

7. Getting Started

Prerequisites:

  • Docker + Docker Compose (v2+) on host machine. (GitHub)

  • Git installed.

  • (Optional) NVIDIA Container Toolkit for GPU inference if using local model GPU path. (GitHub)

Quick-start (Linux):

git clone -b AIONOS --single-branch https://github.com/Hamedghz/OMERTAOS.git
cd OMERTAOS
cp .env.example .env
cp console/.env.example console/.env
cp control/.env.example control/.env
docker compose up -d

Endpoints:

  • Console → http://localhost:3000 (GitHub)

  • Gateway → http://localhost:8080 (GitHub)

  • Control API → http://localhost:8001 (GitHub)

Windows Quick-Install:

powershell -ExecutionPolicy Bypass -File install.ps1

Prompts will set up ports, credentials, and environment. (GitHub)

Headless / Server Use:

aion init --quickstart --no-browser --admin-email admin@local --admin-pass 'Str0ngPass!' --provider hybrid --api-key "$OPENAI_API_KEY"
curl -sf http://127.0.0.1:8001/api/health

(GitHub)

Switching Local Model Engines:
In your config config/aionos.config.yaml:

models:
  provider: local
  local:
    engine: vllm  # or ollama
    model: Qwen/Qwen2.5-7B-Instruct

(GitHub)

8. Documentation & References

  • docs/ folder: architecture diagrams, runbooks, ADRs. (GitHub)

  • Developer workflow section describes folder layout and test matrix. (GitHub)

  • Tests:

    • Gateway → npm test

    • Control → pytest

    • Modules → cargo test

    • Console → Playwright E2E suite

    • Load tests → k6 profiles (GitHub)

Recommended reading/links:

  • README.md (which you already have)

  • CONTRIBUTING.md

  • GOVERNANCE.md

  • SECURITY.md

  • CODE_OF_CONDUCT.md

9. FAQ

Q: What kinds of modules can I write?
A: Any Rust/WASM module that fits into the execution pipeline. It should be sandboxable, signed, and manifest-described.

Q: Can I route to cloud LLMs and local models?
A: Yes. The policy layer supports routing to “local”, “api”, or “hybrid” paths (for example, fallback to API if local fails). (GitHub)

Q: How is multi-tenancy handled?
A: The system supports TENANCY_MODE=multi, with enforcement of Tenant-ID header across HTTP/gRPC, and separate tenant overrides. (GitHub)

Q: What about observability / big-data?
A: Optional overlays for tracing/metrics (OpenTelemetry + Prometheus/Grafana) and big-data (Kafka → ClickHouse, Spark/Flink, Superset). (GitHub)

10. Acknowledgements & License

  • Licensed under the Apache-2.0 license. (GitHub)

  • Thanks to all contributors and the open-source community.

  • If you appreciate this project, consider a donation (TRON address provided in README). (GitHub)

Next Steps for You

  • Place this markdown file (say docs/WIKI.md) or update your GitHub Wiki with it.

  • Fill out Current Status / Milestones with actual completion percentages, dates, and signatures (yours).

  • Expand the Roadmap section with more specific feature tickets/issues (link to GitHub issues).

  • Add visuals: architecture diagrams, module interaction flows, spec folder example.

  • Add badges (CI status, coverage, version) in README (optional).

  • Encourage community contributions by linking issues marked “good first issue” etc in the Contributors section.

  • Optionally automate the Wiki update via CI when version bumps or milestone achievements happen.

If you like, I can generate a ready-to-use Wiki folder with multiple files (overview.md, roadmap.md, architecture.md, contributor.md) and boilerplate diagrams (Mermaid), tailored for your master thesis / branding style and export-ready for GitHub. Would you like me to build that?

Clone this wiki locally