Nexus

Nexus is the process-wide runtime for an Aether application. It hosts the embedded OPC UA server, HTTP API, MCP endpoint, startup/shutdown lifecycle, certificates, and observability integration.

Singleton behavior

• Nexus is a singleton: repeated construction returns the same instance.
• Only the first initialization applies runtime options.
• Treat one process as owning one Nexus instance for its full lifetime.

Common constructor options

• opc_ua_url: embedded OPC UA listen endpoint (for example opc.tcp://localhost:4840 or opc.tcp://0.0.0.0:4840 in containers).
• namespace: namespace URI used for embedded OPC UA nodes.
• device_id: logical object node under Objects where embedded variables are grouped.
• otlp_endpoint: optional OTLP exporter endpoint for traces.
• token: optional constructor token source for licensing (alternative to environment variable).
• aws_iot_endpoint: optional AWS IoT Core endpoint to enable device provisioning/publishing flow.

Licensing

• A valid license JWT is required to run nexus.start().
• Provide the token through VEILNET_AETHER_TOKEN or Nexus(..., token=...).
• Token validation happens at startup before services are exposed.

Runtime surfaces

When nexus.start() runs, the application exposes:

• HTTP on 0.0.0.0:8000
• GET /health for liveness checks.
• /docs for interactive OpenAPI.
• /nexus/mcp for MCP over HTTP.
• Embedded OPC UA on opc_ua_url.

Lifecycle and ordering

Use this startup sequence:

1. Construct Nexus first.
2. Define all Sigil instances at module scope.
3. Define all Weave instances at module scope.
4. Call nexus.start().

Declaring Sigils and Weaves before startup ensures routes, tools, OPC UA nodes, and loop scheduling are fully registered.

Certificates

Nexus expects certificate material in certs/ (typically cert.pem and key.pem) and can generate self-signed files when missing. In production, mount or manage this directory explicitly.

Optional integrations

• Tracing: use otlp_endpoint to export traces; otherwise Nexus keeps local trace output for inspection.
• AWS IoT Core: when configured, Nexus can provision/connect and publish Sigil events.

Related

• Nexus, Sigils, and Weaves overview
• MCP connection
• Sigil reference
• Weave reference