Runtime

Edge Connector Architecture

The Edge Connector runtime is the long-running process that keeps your environment connected to the nara platform. Most users only need to know how it starts, how it reconnects, how it receives updates, and how to check whether it is healthy.

Startup sequence

When the runtime starts, it typically:

1. Loads configuration

   It reads the local configuration and applies any environment overrides.

2. Authenticates

   It uses the saved token or deployment credentials to connect the installation to your organization.

3. Loads local or assigned implementations

   Built-in diagnostics are available automatically. Custom edge implementations are loaded from the configured bundle or local implementation directory.

4. Connects to the platform

   It establishes the WebSocket connection used for tool execution and status reporting.

5. Starts health reporting and sync

   The runtime begins heartbeats, exposes health endpoints, and checks for bundle updates.

WebSocket connection

The Edge Connector maintains a persistent WebSocket connection to the platform. This connection is used for tool execution requests, results, heartbeats, and update signals.

When the connection succeeds, the platform knows which edge-backed tools are available through this runtime.

Reconnection logic

If the WebSocket connection drops, the runtime automatically retries with backoff. Once it reconnects, it re-registers its available tools and resumes normal operation.

Note

Temporary disconnects usually recover automatically. Persistent failures usually indicate a credential, network, or deployment issue that needs operator attention.

Heartbeat mechanism

The runtime sends periodic heartbeats to the platform server so the platform can tell whether the connection is still alive.

• Liveness detection
• Connection maintenance through intermediaries such as proxies or load balancers

Bundle sync

The runtime periodically checks for updated bundles from the platform and downloads them automatically when needed.

Typical behavior:

• An initial sync happens if local implementations are missing
• Periodic checks look for new bundle versions
• A newly assigned bundle is loaded and registered without manual file management

Tip

Bundle sync is automatic. In normal operation, you assign a bundle in the platform and the runtime picks it up on its next sync.

Local webhook relay

For local-hosted integrations, the runtime can accept provider webhooks locally and relay them to the platform over the authenticated Tool RPC connection.

Choose the relay exposure mode based on where the provider runs:

• Provider on the same LAN: this is the default. The relay listens on the LAN interface and provisioning uses the edge host address. Run it only on a trusted network or behind host firewall rules that allow the provider to reach the relay.
• Provider on the same host as the Edge Connector only: set NARA_LOCAL_HOSTING_WEBHOOK_RELAY_EXPOSE_LAN=0 to force loopback-only relay URLs.
• Provider cannot reach the edge host: do not enable edge-relay webhook delivery. Use cloud-public webhook delivery or polling fallback.

If the provider base URL is not loopback and loopback-only mode is explicitly enabled, the platform rejects edge-relay webhook provisioning. This prevents registering an unreachable 127.0.0.1 webhook URL.

Health monitoring

The runtime exposes an HTTP health server for monitoring and orchestration.

Common endpoints:

Endpoint	Purpose
GET /livez	Confirms the process is running
GET /healthz	Confirms the runtime is ready
GET /statusz	Returns a more detailed operational view

# Quick health check
curl http://localhost:8080/healthz

# Detailed status
curl http://localhost:8080/statusz

Graceful shutdown

The Edge Connector supports graceful shutdown and tries to stop cleanly so the connection, state, and process lock are released correctly.

1. It stops accepting new work.
2. It closes the platform connection.
3. It releases local runtime state and locks.
4. It exits cleanly.

Next steps

Installation Set up the Edge Connector on a workstation or server.

Custom Tools Build edge-backed tools that the runtime can load and execute.