The Edge Connector is a managed runtime that bridges the nara platform with your local and on-premises systems. It runs as a lightweight daemon on your infrastructure and keeps your environment connected to nara so agents can execute tools against resources inside your network — databases, internal APIs, local file systems, and other services that are not exposed to the public internet.
The Edge Connector sits between the nara platform and your internal systems. When an agent needs to execute an EDGE tool, the request flows through the following path:
Webapp / Agent | v nara Platform | v Edge Connector (your infrastructure) | v Your Systems (databases, APIs, services)Agent requests tool execution. During a conversation, an agent determines that it needs to call a tool with execution type EDGE.
The platform routes the call. nara forwards the request to the Edge Connector instance that has registered that tool.
Edge Connector executes locally. The Edge Connector loads the corresponding tool implementation and runs it against your local infrastructure.
Result flows back to the agent. The structured result is returned through the platform and back to the agent for incorporation into the conversation.
The Edge Connector supports two distinct deployment modes, each tailored to different use cases.
Desktop Mode
Interactive mode with a system tray icon. Designed for individual workstations where a user needs to authenticate via browser OAuth and monitor the connector status visually. The system tray provides login, status indicators, and a quit action.
Server Mode
Headless mode for production deployments. Authenticates via DEPLOYMENT_ID and
DEPLOYMENT_SECRET environment variables. No system tray or interactive prompts. Ideal for
always-on servers, containers, and CI/CD environments.
Understanding these core concepts will help you navigate the rest of the Edge Connector documentation.
Bundles — A bundle is a versioned, packaged collection of tool implementations. When you write custom tool code, you package it into a bundle (a .tgz archive containing compiled JavaScript and a manifest) and upload it to the nara platform. Bundles are versioned automatically on each upload.
Deployments — A deployment is a named environment that represents a running Edge Connector instance or group of instances. Each deployment can be assigned a specific bundle, controlling which tool implementations it runs. Deployments are managed from the admin panel or via the CLI.
Implementations — Implementations are the actual code files you write to handle EDGE tool executions. Each tool has a corresponding implementation file (typically TypeScript) that exports a handler function. The handler receives the tool’s parameters, executes the required logic, and returns a structured result.
Tool references — A .ref.json file that points to a previously uploaded tool version on the server. When a bundle includes references instead of source code for a tool, the platform resolves the reference to the correct version at sync time. This allows you to mix local source files with server-hosted tool versions in a single bundle.
| Criteria | Edge Connector | Cloud Connector |
|---|---|---|
| Runs on | Your infrastructure (workstation, server, VM) | nara-managed cloud infrastructure |
| Network access | Full access to your internal network and systems | Access to public APIs and nara-hosted services only |
| Authentication | Browser OAuth or deployment credentials | Managed automatically by the platform |
| Management | You install, configure, and maintain the runtime | Fully managed — provision, start, stop via CLI or admin panel |
| Best for | Internal tools, on-premise databases, firewall-restricted APIs | Stateless tools, public API integrations, no infrastructure to manage |