AETHER
Universal runtime portability.
Deploy once. Move workloads across Podman, Kubernetes, and KubeVirt without rewriting infrastructure.
v0.4.0
Apache-2.0
-
Product overview
Why Aether exists and where it fits.
-
Migration credibility
State machine, rollback, and the limits matrix.
-
Runtime decisions
Scoring engine weights, intent, and explain output.
-
Enterprise trust
Deployment topologies and the production reference.
-
Ecosystem
Where Aether fits in the Zyvor suite.
Take a closer look¶
Local dev and edge containers. Fast iteration, single-host, no cluster required.
Best for: laptops, edge nodes, CI runners, and quick local testing before a workload ever touches a cluster.
Cluster orchestration, services, scaling. The production default for multi-node workloads.
Best for: horizontally-scaled services, anything needing Ingress/Service networking, HPA, or multi-replica health gates.
VM isolation and GPU passthrough on top of Kubernetes.
Best for: legacy VM workloads, hardware-bound GPU jobs, and anything that needs a full guest OS rather than a container.
Performance¶
Baseline latency ranges from benchmarks/aether-bench.sh — numbers vary by hardware, published as honest modest ranges rather than a single cherry-picked figure.
| Command | Typical range |
|---|---|
aether validate |
5–50 ms |
aether decide --explain |
10–80 ms |
aether migrate (blue-green) |
30s–5m (runtime-dependent) |
Full benchmark methodology and latest run →
Trust and proof¶
| Document | Description |
|---|---|
| Migration Internals | State machine, rollback, limits matrix |
| Stateful Portability | Volumes, databases, honest boundaries |
| Scoring / Decision Engine | Weights, intent, explain output |
| Deployment Topologies | Single-node, HA, hybrid, edge |
| Fleet Architecture | Multi-cluster now vs roadmap |
| Networking | Runtime translation, DNS, ingress |
| Production Reference | Scale, recovery, upgrades |
| Benchmarks | Deploy/migrate/API baselines |
| Cloud Matrix | Vendor support levels |
| Atlas Storage | Atlas-backed persistent volumes |
| Forge GPU / AI | GPU capacity, nodes, placement, cost |
| Ecosystem | Aether + Zyvor suite |
| Roadmap | Ship vs planned |
Table of Contents¶
🚀 Getting Started¶
| Document | Description | Time |
|---|---|---|
| Installation Guide | Prerequisites, build from source, package managers, container image, Helm chart, shell completions, first-time setup, verification | 5 min |
| Quick Start (5 min) | Create, validate, build, deploy, status, logs, migrate, TUI -- all in five minutes | 10 min |
🎓 Tutorials¶
Beginner¶
| Topic | Document | What You Learn | Time |
|---|---|---|---|
| First Deployment | Beginner Tutorial | Create, deploy, monitor, and delete a workload | 30 min |
| Templates | Templates Guide | Generate workload specs from 8 built-in templates (web-app, rest-api, database, cache, worker, cron-job, ml-training, microservice) |
15 min |
| Shell Completions | Installation Guide | Tab completion for bash, zsh, fish, PowerShell, elvish | 5 min |
Intermediate¶
| Topic | Document | What You Learn | Time |
|---|---|---|---|
| Workflows | Intermediate Workflows | Compose files, migrations, output formats, watch mode | 45 min |
| Workload Schema | Schema Reference | Full YAML specification: metadata, build, requirements, runtime, network, persistence, health, config, ingress, scaling | 20 min |
| Cost Analysis | Cost Estimation | Compare costs across AWS, Azure, GCP, DigitalOcean, Linode | 15 min |
Advanced¶
| Topic | Document | What You Learn | Time |
|---|---|---|---|
| Advanced Features | Advanced Tutorial | Policies, AES-256 secrets, drift reconciliation, plugins | 60 min |
| How It Works | Deep Dive Tutorial | Internal architecture, decision engine, runtime adapters, state management, security model | 90 min |
| CI/CD Integration | CI/CD Guide | GitHub Actions, GitLab CI, Jenkins pipelines | 30 min |
📗 Guides¶
Architecture¶
| Guide | Description |
|---|---|
| Architecture Overview | System design, component architecture, data flow, security model, key design decisions |
CLI Guide¶
| Guide | Description |
|---|---|
| CLI Reference | All 40+ commands with flags, descriptions, and examples |
| Quick Reference Card | One-page command cheat sheet |
Core Lifecycle Commands¶
| Command | Description |
|---|---|
aether init |
First-time setup wizard |
aether validate |
Validate workload YAML specification |
aether build |
Build workload container image |
aether run [--runtime <rt>] |
Deploy a workload (optional runtime override) |
aether stop <name> |
Stop a running workload |
aether status <name> |
Get workload instance status |
aether logs <name> [--follow] |
View workload logs |
aether delete <name> |
Delete a workload instance |
aether list |
List all deployed workloads |
aether exec <name> [cmd] |
Execute a command inside a running workload |
aether port-forward <name> <local:remote> |
Forward local ports to a workload |
aether watch [--runtime <rt>] |
Watch spec file and auto-redeploy on changes |
Batch Operations¶
| Command | Description |
|---|---|
aether deploy <dir> [--runtime <rt>] [--fail-fast] [--dry-run] |
Deploy all workloads from a directory |
aether compose up [file] [--runtime <rt>] [--dry-run] |
Deploy all workloads from a compose file |
aether compose down [file] |
Stop all workloads from a compose file |
aether compose validate [file] |
Validate a compose file |
Migration¶
| Command | Description |
|---|---|
aether migrate <name> <target> [--strategy <s>] |
Migrate workload to a different runtime |
aether migration-advice <name> <target> |
AI-powered migration path recommendations |
aether rollback <name> |
Rollback to the latest snapshot |
aether diff <name> |
Compare spec vs stored vs live state |
AI & Analysis¶
| Command | Description |
|---|---|
aether recommend |
AI-powered runtime recommendation with scoring |
aether profile [--name <n>] |
Workload profiling and optimization recommendations |
aether analyze-logs <name> |
Anomaly and pattern detection in logs |
aether scaling-advice |
Predictive scaling recommendations |
aether compare |
Compare workload across runtimes (cost, capabilities) |
aether affinity recommend <class> |
Runtime affinity for a workload class |
aether affinity matrix |
Full compatibility matrix |
Infrastructure & Scheduling¶
| Command | Description |
|---|---|
aether cost [--provider <p>] |
Multi-cloud cost estimation |
aether config [--show] [--init] |
Show or initialize configuration |
aether template <name> [--output <file>] |
Generate workload from template |
aether env create <name> [--tier <t>] |
Create deployment environment |
aether env promote <workload> <from> <to> |
Promote workload between environments |
aether schedule place <name> [--strategy <s>] |
Schedule workload placement |
aether schedule utilization |
Show runtime utilization |
Observability¶
| Command | Description |
|---|---|
aether tui |
Interactive TUI dashboard |
aether serve [--host <h>] [--port <p>] |
Start API server and web dashboard |
aether metrics |
Export Prometheus metrics |
aether health <name> [--summary] |
View workload health history and uptime |
aether events [--last <n>] [--severity <s>] |
View and filter events |
aether audit [--last <n>] [--workload <w>] |
View audit trail |
aether sla check <workload> --uptime <u> |
Check SLA compliance |
Security & Compliance¶
| Command | Description |
|---|---|
aether secrets create <name> |
Create a new encrypted secret |
aether secrets set <secret> <key> <value> |
Set a key-value pair (AES-256 encrypted) |
aether secrets get <secret> <key> |
Retrieve a decrypted value |
aether secrets list |
List all secrets |
aether secrets audit |
Check rotation status |
aether policy-check [--policy <p>] |
Check workload against policies |
aether drift <name> [--reconcile] |
Detect and reconcile configuration drift |
Operations¶
| Command | Description |
|---|---|
aether backup [--name <n>] |
Backup workload state |
aether restore <backup> [--merge] |
Restore state from backup |
aether list-backups |
List available backups |
aether deps show |
Show dependency graph |
aether deps impact <workload> |
Show impact of stopping a workload |
aether webhook add <name> <url> |
Add webhook notification channel |
aether webhook test <name> |
Send test notification |
Health-Aware Orchestration¶
| Command | Description |
|---|---|
aether orchestrate register <name> |
Register workload for health monitoring |
aether orchestrate status |
Health status of all managed workloads |
aether orchestrate health-check |
Run a single round of health checks |
aether orchestrate watch [--interval <s>] |
Continuous health monitoring loop |
aether orchestrate rolling-update <name> |
Rolling update with configurable replicas |
aether orchestrate reset-circuit <name> |
Reset circuit breaker |
Global Flags¶
| Flag | Short | Description |
|---|---|---|
--spec <file> |
-s |
Workload spec file (default: workload.yaml) |
--verbose |
-v |
Enable debug logging |
--quiet |
-q |
Suppress all output except errors |
--json |
Output as JSON | |
--output <fmt> |
-o |
Output format: table, json, yaml, wide |
--yes |
-y |
Skip confirmation prompts (CI/automation) |
--dry-run |
Show what would happen without executing | |
--skip-policy |
Skip policy checks on deploy |
Operations Guide¶
| Guide | Description |
|---|---|
| Migration Checklist | Pre/post migration steps, strategy selection, rollback procedures |
| Operational Runbook | Troubleshooting playbooks and recovery procedures |
| Backup & Restore | State backup, disaster recovery, merge restore |
⭐ Features¶
| Feature | Document | Description |
|---|---|---|
| Compose Files | Compose Guide | Multi-workload deployment with dependency ordering, runtime overrides, env injection |
| Plugin System | Plugins Guide | Runtime extension via JSON manifest discovery and JSON-RPC protocol |
| Health Monitoring | Health Guide | Uptime tracking, restart history, timeline views, bounded storage |
| Security | Security Guide | AES-256 encryption, policy engine, state locking |
| Drift Detection | -- | Field-level drift reports with severity classification and auto-reconciliation |
| Migration Strategies | -- | Immediate, blue-green, and rolling cross-runtime migration with rollback |
| Runtime Affinity | -- | AI-powered runtime recommendations per workload class (8 classes) |
| SLA Compliance | -- | Uptime/latency/error-rate targets per workload (3 tiers) |
| Dependency Management | -- | Directed dependency graph, topological ordering, impact analysis |
| Webhook Notifications | -- | Push-based alerting with severity filtering and retry queues |
| Environment Management | -- | dev/staging/production tiers, promote, parity checking |
| Workload Scheduling | -- | 4 strategies: balanced, cost, performance, bin-packing |
| Cost Estimation | Cost Guide | Multi-cloud analysis across AWS, Azure, GCP, DigitalOcean, Linode |
| Templates | Templates Guide | 8 built-in templates: web-app, rest-api, database, cache, worker, cron-job, ml-training, microservice |
🚢 Deployment¶
| Document | Description |
|---|---|
| Deployment Guide | Kubernetes manifests, Helm chart, container image deployment |
| CI/CD Integration | GitHub Actions, GitLab CI, Jenkins pipeline recipes |
| Backup & Restore | State backup, disaster recovery, merge restore |
📐 Reference¶
| Document | Description |
|---|---|
| Workload Spec Schema | Complete YAML specification reference with all fields |
| REST API Reference | 40+ REST API endpoints, request/response schemas |
| Prometheus Metrics | All exported metrics, labels, and types |
| Cost Models | Provider-specific cost models and formulas |
| Templates Catalog | Built-in template catalog and customization |
| Operational Runbook | Troubleshooting playbooks and recovery procedures |
| Web Dashboard | REST API server and browser-based UI |
REST API Endpoints (Summary)¶
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Health check |
GET |
/api/workloads |
List all workloads |
POST |
/api/workloads |
Create and deploy a workload |
GET |
/api/workloads/:name |
Get workload details |
DELETE |
/api/workloads/:name |
Delete a workload |
GET |
/api/workloads/:name/logs |
Get workload logs |
POST |
/api/workloads/:name/start |
Start a workload |
POST |
/api/workloads/:name/stop |
Stop a workload |
POST |
/api/workloads/:name/migrate |
Migrate to a different runtime |
POST |
/api/workloads/:name/build |
Trigger a build |
POST |
/api/validate |
Validate a workload YAML |
POST |
/api/cost |
Estimate costs |
GET |
/api/metrics |
Prometheus metrics (text/plain) |
GET |
/api/backups |
List backups |
POST |
/api/backups |
Create a backup |
GET |
/api/secrets |
List secrets |
GET |
/api/secrets/:name |
Get secret metadata |
DELETE |
/api/secrets/:name |
Delete a secret |
POST |
/api/ai/recommend |
AI runtime recommendation |
GET |
/api/ai/profile/:name |
Workload profiling |
GET |
/api/ai/analyze/:name |
Log anomaly analysis |
GET |
/api/ai/migration-advice/:name/:target |
Migration advice |
GET |
/api/ai/scaling-advice |
Predictive scaling |
GET |
/api/drift/:name |
Drift detection |
POST |
/api/policy/check |
Policy evaluation |
GET |
/api/dependencies |
Dependency graph |
POST |
/api/dependencies |
Add a dependency |
GET |
/api/audit |
Audit events |
GET |
/api/templates |
List templates |
POST |
/api/templates/:name |
Generate from template |
GET |
/api/sla/:workload |
SLA compliance |
GET |
/api/events |
Recent events |
GET |
/api/events/summary |
Event summary |
GET |
/api/environments |
List environments |
GET |
/api/scheduler/utilization |
Runtime utilization |
GET |
/api/scheduler/optimize |
Optimization suggestions |
GET |
/api/orchestrator/status |
Managed workload statuses |
GET |
/api/orchestrator/summary |
Health summary |
GET |
/api/affinity/:class |
Runtime affinity recommendation |
GET |
/api/plugins |
List plugins |
POST |
/api/plugins/discover |
Discover plugins |
GET |
/api/health/:workload |
Health history summary |
POST |
/api/compose/validate |
Validate compose spec |
🃏 Quick Reference¶
| Item | Document | Description |
|---|---|---|
| Cheat Sheet | Quick Reference Card | One-page command cheat sheet |
| Hub | Documentation Hub | Landing page with role-based quick access |
Glossary¶
| Term | Definition |
|---|---|
| Workload | A deployable unit described by a YAML spec (workload.yaml) |
| Runtime | A deployment target: Podman, Kubernetes, or KubeVirt |
| RuntimeKind | Enum identifying one of the three supported runtimes |
| Instance | A running workload on a specific runtime |
| Migration | Moving a workload from one runtime to another |
| Drift | Divergence between declared spec and actual live state |
| Compose | A multi-workload deployment defined in aether-compose.yaml |
| Plugin | A third-party runtime extension registered via JSON manifest |
| Policy | A set of rules evaluated before deployment is allowed |
| SLA Target | Uptime/latency/error-rate thresholds for a workload |
| Circuit Breaker | Automatic protection that halts health checks after repeated failures |
| Blue-Green | Migration strategy running both versions simultaneously before switching |
| Rolling | Migration strategy shifting traffic gradually (25%/50%/75%/100%) |
| Affinity | AI-learned runtime preference for a workload class |
FAQ¶
Q: Which runtime should I use?
A: Run aether recommend for AI-powered scoring, or set runtime.preferred: auto in your spec for automatic selection.
Q: Can I migrate between any two runtimes? A: Yes. All 12 runtime-pair combinations are supported (4 source x 3 target).
Q: Is the spec format compatible with Kubernetes YAML?
A: The aether spec is its own format (apiVersion: aether/v1). Use aether template to generate specs from common patterns.
Q: How do I run aether in CI/CD?
A: Use --yes --quiet --json flags for non-interactive, machine-readable output. See the CI/CD Guide.
Q: Where is state stored?
A: In ~/.aether/ by default. Use aether backup and aether restore for portability.
🗺️ Learning Paths¶
Beginner Path¶
Installation --> Quick Start --> First Deployment --> Quick Reference
Intermediate Path¶
Workflows --> Compose --> Health --> CLI Reference --> Cost
Advanced Path¶
Advanced Features --> Security --> Plugins --> REST API --> CI/CD
Enterprise Path¶
Migration Checklist --> Security --> Deployment --> REST API --> Runbook
📄 License¶
Proprietary - Copyright (c) 2024-2026 HyperSDK. All rights reserved.
- 4 runtime kinds (Podman, Docker, Kubernetes, KubeVirt) × 3 valid targets each, source ≠ target. See the limits matrix. ↩
- Counted from this page's own CLI command tables below. See the full CLI Reference. ↩
- Counted from this page's own REST API endpoint summary below. See the full REST API Reference. ↩