AetherEdge

Documentation website: docs.aetheriot.dev

AI-native platform · Get started · Documentation · Agent Skill · MCP · 中文

Let AI agents run your physical space — safely, locally, deterministically.

AetherEdge is an open-source, industry-neutral IoT edge kernel, runtime, and Rust SDK for Linux gateways. It connects field devices, keeps authoritative live state in shared memory, runs deterministic local rules and alarms, and stores embedded history — no Redis, no PostgreSQL, no cloud service, no browser, no LLM required.

What makes it different: AI is a first-class client behind a typed, governed boundary. Agents discover real capabilities over MCP and OpenAPI, propose changes, and commission behavior — while device control stays deny-by-default, explicitly confirmed, and audited, and the edge keeps executing deterministically even when no AI is connected.

AetherEdge is the edge product in the AetherIoT platform, alongside AetherCloud and AetherContracts. The official energy-management distribution is AetherEMS.

Try it in five minutes

Have a running edge system? Expose it to your AI assistant as read-only MCP tools:

claude mcp add aether -- aether mcp

Then ask your assistant:

Inspect my edge runtime and generate a read-only operations app for the
capabilities it exposes.

The MCP server talks to the authenticated API gateway (aether-api:6005), so set AETHER_ACCESS_TOKEN for the session. Claude on your laptop, edge on a server? One line still works: claude mcp add aether -- ssh user@gateway aether mcp, or point AETHER_API_URL at an HTTPS ingress — see Connect AI assistants.

No hardware? The SDK compositions run anywhere, need no external service, and commission nothing:

cargo run -p aether-example-minimal-gateway   # empty industry-neutral gateway
cargo run -p aether-example-energy-gateway    # disabled-by-default Energy Pack proof

You can also simulate devices on the wire — Modbus TCP/RTU, CAN, J1939 — and acquire from them exactly like a physical site:

cargo run -p simulator -- --scenario tools/simulator/scenarios/pv_daily.yaml --port 5020

See Getting Started for the full safe-empty runtime setup, Connect devices for wiring channels, and the Agent Quickstart for a complete assistant-driven setup.

Install AetherEdge

For a Docker-based Linux edge host, download the matching AetherEdge-<arch>-<version>.run file and its .sha256 file from GitHub Releases. Verify and run the fresh-install package on the target host:

sha256sum -c AetherEdge-<arch>-<version>.run.sha256
chmod +x AetherEdge-<arch>-<version>.run
sudo ./AetherEdge-<arch>-<version>.run

The .run package installs the six-service edge Runtime and the aether CLI. Releases also contain standalone CLI archives; those do not install the Runtime. For a source checkout or SDK development, follow Getting Started. Running cargo install --path tools/aether --locked installs only the CLI. See Deployment for Docker and bare-metal package contracts. AetherEdge is not an npm or Bun package; npx and bunx do not install it.

What AetherEdge provides

• Deterministic edge runtime — six isolated Rust services continue acquisition, rules, alarms, history, and uplink when no AI client is connected.
• Local-first data plane — shared memory is authoritative for live point state; SQLite provides embedded desired state, history, audit, and durable outbox storage.
• Machine-readable contracts — runtime manifests, OpenAPI, capability metadata, Pack manifests, experimental CloudLink schemas, MCP tools, and Markdown documentation give agents facts instead of prompt folklore.
• One application boundary — HTTP, CLI, MCP, and generated clients share governed queries and commands instead of writing SHM or storage directly.
• Domain Packs — industry knowledge, models, mappings, rules, and processing declarations layer over the kernel without becoming core dependencies.

AI-native product direction

AetherIoT's product direction is to let people describe outcomes in conversation instead of programming device identifiers, triggers, conditions, and actions through fixed configuration screens. Agents discover typed capabilities, generate governed proposals, and commission behavior; AetherEdge executes the accepted behavior locally without the model.

The complete end-user conversational agent is not shipped in the current beta. AetherEdge provides the foundations it requires today: runtime and Pack discovery, agent-readable documentation, OpenAPI, MCP tools and resources, governed commands, revisioned configuration, audit evidence, and deterministic local execution.

The planned platform lifecycle is:

human intent -> agent proposal -> typed contracts -> policy and confirmation
             -> commissioned behavior -> deterministic edge execution
             -> observation, explanation, and governed revision

Future intent, proposal, simulation, expiry, and continuous-adaptation capabilities must be added as explicit application and AetherContracts surfaces. An agent cannot fabricate a device feature, write SHM or SQLite, bypass confirmation, or become a hidden second configuration authority. See the AI-native platform and platform status for the delivery boundary.

Beta: AetherEdge is the industry-neutral Kernel, Runtime, and SDK. Existing crates, binaries, the CLI, and some compatibility artifacts retain their aether-* / aether names. This repository was formerly named EvanL1/AetherIot; software identifiers remain stable during the migration.

How agent access is governed

The repository's Agent Skill is optional development guidance, not an AetherEdge software package. See Build Applications with AI if you want to add it to a compatible assistant.

The optional Skill supplies the development method and pulls current Markdown from the online docs. MCP supplies live, structured capabilities. Write tools are not registered unless the operator starts an explicitly write-enabled session, and every write still crosses the server-enforced permission, confirmation, validation, and audit boundary.

See Build Applications with AI for the client contract and Agent Quickstart for a complete safe-empty runtime setup.

Conversation-first, headless by design

AetherEdge does not ship a generic Web Console. A fixed dashboard cannot express every industry Pack, and a browser must never become a second configuration authority. Instead, AetherEdge ships the contracts, Agent Skill, and development guidance needed to generate or maintain fit-for-purpose applications.

The long-term configuration experience is conversation-first: users describe the result they want, while an agent generates an inspectable, versioned change. Consequential changes may still produce an on-demand summary, risk explanation, simulation, or confirmation surface. Those generated views explain a change; they do not own it.

User interfaces are downstream clients and reference implementations. They consume published application APIs, remain replaceable, and receive no direct SHM, SQLite, or internal-service access. The optional AetherEMS Console is one energy-domain implementation of this model.

Rust SDK

aether-edge-sdk, imported as aether_sdk, is the only supported Rust application facade. Workspace implementation crates are source-only and cannot be published independently. Downstream builds pin the exact commit behind a signed source release and select local adapters through the SDK's local-runtime feature. The example compositions above are SDK smoke tests, not the supervised production runtime.

Edge runtime

Process	Responsibility
aether-io	Protocol acquisition and sole telemetry/status writer
aether-automation	Instances, rules, and audited control dispatch
aether-alarm	Alarm evaluation and lifecycle
aether-history	Embedded history and optional history adapters
aether-api	Authenticated remote application API and WebSocket
aether-uplink	Legacy Cloud/MQTT delivery through a durable local outbox; experimental CloudLink foundation

Devices -> aether-io -> authoritative SHM
                         |-> automation and alarms
                         |-> API and embedded history
                         `-> durable outbox -> optional cloud

domain <- ports <- application <- runtime/interfaces
             ^
             `---- extensions

Only aether-api is a remote application boundary. The other process APIs stay on loopback. Generated clients must use published application capabilities and must not expose or proxy those internal ports.

Contributing

Development setup and verification live in CONTRIBUTING.md. Repository rules for agents and contributors live in AGENTS.md.

License

MIT OR Apache-2.0, at your option. See the MIT license and Apache License 2.0.