AetherEdge

AetherEdge

Product site: aetheriot.ai · Developer site: aetheriot.dev

Documentation: docs.aetheriot.ai · Getting started · User journeys · Connect devices · Protocol adapters · Connect AI · 中文

Connect physical devices, prove the data path, and commission deterministic behavior—without making the cloud, a browser, or an AI model part of the control loop.

AetherEdge is an open-source, industry-neutral IoT edge kernel, six-service runtime, CLI, and Rust SDK for Linux gateways. Shared memory is authoritative for live point state; embedded SQLite stores desired state, history, audit, and a durable outbox. The default distribution needs no Redis, PostgreSQL, cloud service, browser, or LLM.

AI is a replaceable client behind the same typed, governed application boundary as every other client. Device control is deny-by-default, explicitly confirmed, and audited. Already commissioned acquisition, safety, rules, and alarms keep running deterministically when every external client is disconnected.

Is AetherEdge the right starting point?

You want to…	Start with…
Connect field devices and run local behavior on a Linux gateway	AetherEdge
Deploy an energy-management solution and operator Console	AetherEMS
Coordinate an edge fleet or cloud jobs	AetherCloud
Implement or validate a shared protocol	AetherContracts

AetherEdge's direct users are device manufacturers, system integrators, solution builders, application developers, and edge operators. It deliberately does not pretend to be a finished application for every industry.

From a blank host to a useful Edge

The product journey is:

safe-empty install -> operator identity -> disabled device channel
  -> physical/logical point mapping -> read-only data proof
  -> reviewed behavior -> explicit commissioning -> audit and operation

Every consequential change follows:

inspect -> plan -> validate -> confirm -> apply -> audit -> observe -> revise

Creating configuration never silently enables hardware.

1. Install a safe-empty runtime

Download the matching .run package and checksum from GitHub Releases, then verify and run the fresh-install package on the target Linux host:

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

The installer creates the six services, aether CLI, private bootstrap credentials, embedded database, and an empty configuration. It does not add a device, enable a rule, or install a domain solution.

2. Establish identity and prove the empty runtime

Start with the local health gate:

aether doctor

A healthy first boot has six healthy services and valid SHM. Sign in with the private bootstrap credential, change that password immediately, create a dedicated account for normal operation, and export its signed AETHER_ACCESS_TOKEN. Then prove that nothing was commissioned implicitly:

aether channels list --json
aether models instances list --json
aether rules list --json

The channel, instance, and rule collections should all be empty. Getting Started covers the exact bootstrap and token flow.

3. Create one channel—still disabled

Choose a protocol included in the installed IO build. A governed create command requires authentication and confirmation, but the new channel remains disabled unless --enabled true is explicitly requested:

AETHER_ACCESS_TOKEN='<signed access JWT>' aether channels create \
  --name "PLC#1" \
  --protocol modbus_tcp \
  --params '{"host":"192.168.1.10","port":502}' \
  --confirmed

Before enabling it, declare the physical points, map protocol addresses, bind the required points to a logical instance supplied by a Domain Pack, and review unresolved mappings. Follow Connect Devices for that complete workflow and the Protocol Adapter Reference for the exact feature, runtime ID, transport, and mapping matrix.

4. Prove observation before control

device -> aether-io -> authoritative SHM -> API and embedded history -> client

Verify channel health, timestamps, quality, freshness, topology generation, historical samples, and unmapped points. A connected socket without fresh data is not a healthy acquisition path, and a missing value is not zero.

Once the mapping is complete, enable the channel with the latest desired-state revision returned by the channel query:

AETHER_ACCESS_TOKEN='<signed access JWT>' aether channels enable <CHANNEL_ID> \
  --expected-revision <REVISION> \
  --confirmed

The first useful milestone is a read-only data path. Do not add physical commands merely to prove acquisition.

5. Add and commission deterministic behavior

Add logical models, calculations, alarms, and local rules through a downstream Domain Pack or application composition. Draft rules and control paths stay disabled until their inputs, targets, permissions, failure behavior, and audit path have been reviewed.

review disabled behavior -> validate -> confirm -> enable
  -> inspect audit evidence -> observe the physical outcome

A successful command acceptance is not proof that the physical device reached the requested state. Observe that outcome separately.

6. Choose a replaceable client

All clients enter through authenticated aether-api:6005:

Client	Use it for
aether CLI	Installation, commissioning, diagnostics, and operations
HTTP/OpenAPI	Dedicated applications and generated clients
Read-only MCP	AI-assisted inspection and explanation
Temporary write-enabled MCP	One bounded, explicitly authorized maintenance task
aether-edge-sdk	A downstream solution or embedded composition
Downstream Console	A domain-specific operator experience, such as AetherEMS

The other five process APIs stay on loopback. Clients must not proxy them or write SHM or SQLite directly. AetherEdge ships no universal Web Console; a UI is a replaceable application client, never a second state authority.

To attach an existing runtime to Claude in the default read-only mode:

claude mcp add aether -- aether mcp

Set AETHER_ACCESS_TOKEN for the session. Use SSH stdio or an HTTPS ingress for a remote Edge—never expose an internal service port. See Connect AI Assistants.

Developing without field hardware

Run the industry-neutral SDK composition or a protocol verification simulator. Neither commissions a physical device:

cargo run -p aether-example-minimal-gateway
cargo run -p simulator -- \
  --scenario tools/simulator/scenarios/modbus_protocol_verification.yaml \
  --port 5020

A source checkout is a developer path, not the normal operator installation flow. See Getting Started.

Build a downstream solution

cargo add aether-edge-sdk --features local-runtime

aether-edge-sdk, imported as aether_sdk, is the supported Rust application facade. A downstream product combines the SDK, a Domain Pack, and a dedicated application or agent in its own repository. Domain processors, models, and Consoles do not become dependencies of the AetherEdge kernel. AetherEMS is the reference energy-domain implementation of this model.

Runtime model

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	Durable legacy Cloud/MQTT delivery and experimental CloudLink foundation

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

              domain <- ports <- application <- runtime/interfaces
                        ^
                        `---- downstream static Rust adapters (out of tree)

AetherEdge currently delivers the integrator-grade runtime, application contracts, governed commands, MCP foundations, Pack v1, and SDK facade. The complete conversational intent compiler, simulation, temporary behavior, and continuous outcome evaluation remain product direction. See the platform status for the exact delivery boundary.

Contributing

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

License

Licensed under either MIT or Apache-2.0, at your option.