Overview

What is Aether?

Aether is the VeilNet real-time engine for digital twins. It hosts an embedded OPC UA server so HMIs, SCADA, and other OPC UA clients browse the same variables you expose over REST and MCP. Weaves run your Python logic on a fixed cycle—plant models, observers, or closed-loop control against live hardware.

Nexus (singleton runtime)

Nexus is the singleton stack inside a running process:

• Embedded OPC UA server (bind address from Nexus(opc_ua_url=...)).
• FastAPI HTTP API (default 0.0.0.0:8000).
• MCP over HTTP (mounted at /nexus).
• Certificates under certs/ (self-signed material is generated on first run when missing).

Call nexus.start() to run the stack after you have defined Sigils and Weaves.

Licensing

Every Nexus run requires a license JWT—including local development, examples, and tests. There is no mode that skips it. Use an early-access or trial key from VeilNet, or a token your operator distributes.

Supply the token in either way:

• Set the environment variable VEILNET_AETHER_TOKEN to the JWT string, or
• Pass the token when you construct Nexus (for example a token= argument on Nexus(...); use the exact parameter name from your SDK version).

Offline validation: Nexus verifies the JWT locally (cryptographic signature and expiry) using the runtime’s configured signing secret. No internet access is required for that check, so air-gapped sites work as long as the token and verification secret are configured.

Sigil (one OPC UA variable)

A Sigil represents one OPC UA node:

• Readable always; writable when you allow REST/MCP/OPC UA writes (writable=True, default where not stated otherwise in examples).
• Omit opc_ua_url to host the variable on Aether’s embedded server.
• Set opc_ua_url (and optional user_name / password or certificate fields) to read and write a node on an external OPC UA server such as a PLC.

REST and MCP follow the same read/write rules as OPC UA for that Sigil.

Weave (periodic callback)

A Weave registers an async callback invoked every cycle_time seconds. Use it for physics, synchronization, or closed-loop control that reads and writes Sigils.

How the pieces connect

At a high level:

1. You construct one Nexus with the embedded OPC UA listen address (for example opc.tcp://0.0.0.0:4840 in Docker so the published port works), and a license JWT via VEILNET_AETHER_TOKEN or Nexus(..., token=...) (see Licensing above).
2. You declare Sigils with node_id strings (OPC UA NodeId form) and initial values.
3. You attach one or more Weave instances with label, cycle_time, and callback.
4. You call nexus.start() (typically under if __name__ == "__main__").

External tools can then use:

• OPC UA at your configured endpoint.
• HTTP GET /health for liveness, /docs for interactive OpenAPI.
• MCP at /nexus for agent and tool integrations.

Next steps

• Install the SDK
• Nexus, Sigils, and Weaves example
• Docker deployment