Installation

Edge Connector Setup

This guide walks you through downloading, installing, and verifying the nara Edge Connector on your workstation or server.

System requirements

Before installing, ensure your system meets the following requirements:

Requirement	Details
Node.js	Version 18 or later
Operating system	Windows 10+, macOS 12+, or Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+)
Network	Outbound WebSocket access to the nara platform server
Disk space	100 MB minimum for the CLI and runtime, plus space for tool bundles
Permissions	Write access to the installation directory; admin/root for autostart configuration

Note

The Edge Connector uses WebSocket connections (typically on port 443 for production). Ensure your firewall and proxy allow outbound WebSocket traffic to the nara platform server URL.

Download and extract

The simplest setup path is through the webapp.

1. Sign in to the nara webapp as an organization administrator.

2. Navigate to Admin > Edge Connector.

3. Click Download Edge Connector for your platform.

4. Extract the archive into your preferred installation directory.

5. Keep the included configuration file in place unless your deployment process requires custom paths or environment overrides.

First-time setup

After downloading and extracting the Edge Connector, follow these steps to get up and running.

1. Authenticate with the nara platform

   Run the authentication command to link this Edge Connector to your organization:

   ./edge-connector auth --browser

   This opens your default browser for OAuth authentication. After you log in and authorize, the token is saved locally. Alternatively, provide a token directly:

   ./edge-connector auth --token <YOUR_JWT_TOKEN>

2. Generate tool implementations when needed

   If you are building custom edge tools, scaffold boilerplate code for the tools registered in your organization:

   ./edge-connector generate --language typescript --tool <tool_name> --output ./custom-implementations

   This connects to the nara platform server, fetches the tool’s parameter and result schemas, and generates a TypeScript implementation file with the correct types.

3. Implement your tool logic

   Open the generated file in your editor and implement the handler function. The generated code includes typed parameters, a result template, and error handling scaffolding.

4. Test locally

   Start the Edge Connector in local test mode to verify your implementation:

   ./edge-connector run --implementations ./custom-implementations --url ws://localhost:3001

   Test mode disables state persistence and autostart, making it safe to iterate quickly.

5. Package and upload

   When your implementation is ready, package it into a bundle and upload it to the platform:

   ./edge-connector upload --implementations ./custom-implementations

   This compiles TypeScript, creates a .tgz archive, and uploads it. Connected Edge Connectors will automatically sync the new bundle.

Note

If you only want to run an already prepared edge setup, you may not need the generate and upload steps immediately. They are mainly relevant when you are developing custom edge implementations.

Directory structure

After installation and first-time setup, your Edge Connector directory looks like this:

edge-connector/
  config.json                    # Runtime configuration
  auth-token.json                # Saved authentication token
  custom-implementations/        # Your tool implementation source code
    tools/                       # Individual tool files
      my_tool.ts                 # TypeScript tool implementation
      other_tool.ref.json        # Reference to server-hosted tool version
    package.json                 # Dependencies for your implementations
    dist/                        # Compiled output (generated during build)
      index.js                   # Auto-generated tool index
      tools/
        my_tool.js               # Compiled tool
  artifacts/                     # Bundle archives created by the package command
  runtime/                       # Edge Connector runtime (do not modify)
  cli/                           # CLI commands and generators (do not modify)

Verifying the installation

Confirm the Edge Connector is installed correctly:

./edge-connector --version

This prints the CLI version (e.g., 0.3.0). If you see a version number, the installation is complete.

To verify authentication and platform access:

./edge-connector bundle list

This fetches and displays the bundles registered for your organization. If authentication is configured correctly, you will see your bundle list (or a message indicating no bundles exist yet).

Tip

If you run ./edge-connector without any arguments, the CLI opens an interactive flow that helps with authentication and common setup tasks.

Next steps

Authenticate

Learn about the different authentication modes and how to manage tokens securely.

Build your first tool

Generate, implement, and test a custom tool on the Edge Connector.