@navada/edge-sdk

Official SDK for the NAVADA Edge Network — a distributed AI infrastructure connecting physical nodes, cloud services, and AI models through a single unified API.

Zero dependencies. Works with npm, pnpm, and yarn. Node.js 18+.

pnpm add @navada/edge-sdk

What is NAVADA Edge Network?

NAVADA Edge is a distributed computing mesh that connects physical servers, cloud VMs, and managed services over an encrypted Tailscale VPN:

                         TAILSCALE VPN MESH
    ┌──────────────────────────────────────────────────┐
    │                                                    │
    │  [Node 1]          [Node 2]         [Node 3]      │
    │  Production         Database         Monitoring    │
    │  MCP Server         Postgres         Telegram Bot  │
    │  Dashboard          OpenCode         Lucas CTO     │
    │  Registry                                          │
    │  YOLO AI            [Node 4]                       │
    │                     Docker Infra                   │
    │                     Portainer                      │
    │                     Grafana                        │
    │                                                    │
    └──────────────────────────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         [Cloudflare]  [Azure]     [AI APIs]
         R2 Storage    n8n         OpenAI
         Flux (free)   Container   HuggingFace
         Stream CDN    Apps        YOLO
         Tunnel/DNS

The SDK gives you one require() to access everything.

Quick Start

const navada = require('@navada/edge-sdk');

// Configure (choose one):

// Option A: environment variables (recommended for Docker)
// Set NAVADA_ASUS, NAVADA_MCP, etc. in your .env or container env

// Option B: programmatic
navada.init({
  asus: '10.0.0.1',
  mcp: 'http://10.0.0.1:8811',
  dashboard: 'http://10.0.0.1:7900',
  registry: 'http://10.0.0.1:5000',
});

// Use it
const status = await navada.network.ping();
const tools = await navada.mcp.tools();
const images = await navada.registry.catalog();

Configuration

The SDK reads from environment variables. Copy .env.example to .env:

cp node_modules/@navada/edge-sdk/.env.example .env

Environment Variables

| Variable | Module | Description | |----------|--------|-------------| | SERVICE_NAME | config | Your service name | | NAVADA_NODE | config | Which node this runs on | | Nodes | | | | NAVADA_ASUS | network | Node 1 Tailscale IP | | NAVADA_HP | network | Node 2 Tailscale IP | | NAVADA_EC2 | network | Node 3 Tailscale IP | | NAVADA_ORACLE | network | Node 4 Tailscale IP | | Services | | | | NAVADA_MCP | mcp | MCP server URL (e.g. http://10.0.0.1:8811) | | NAVADA_DASHBOARD | dashboard | Command Dashboard URL | | NAVADA_REGISTRY | registry | Docker registry URL | | NAVADA_LUCAS | lucas | Lucas CTO MCP URL | | NAVADA_PORTAINER | network | Portainer URL | | Database | | | | NAVADA_PG_HOST | db | Postgres host | | NAVADA_PG_PORT | db | Postgres port (default: 5432) | | NAVADA_PG_DB | db | Database name | | NAVADA_PG_USER | db | Username | | NAVADA_PG_PASS | db | Password | | Auth | | | | MCP_API_KEY | mcp | MCP server API key | | DASHBOARD_API_KEY | dashboard | Dashboard API key | | Cloudflare | | | | CLOUDFLARE_ACCOUNT_ID | cloudflare.* | Account ID | | CLOUDFLARE_API_TOKEN | cloudflare.* | API token | | CLOUDFLARE_R2_BUCKET | cloudflare.r2 | Default R2 bucket | | CLOUDFLARE_STREAM_SUBDOMAIN | cloudflare.stream | Stream subdomain | | CLOUDFLARE_DOMAIN | network | Your domain | | CLOUDFLARE_ZONE_ID | cloudflare.dns | DNS zone ID | | Azure | | | | AZURE_N8N_URL | azure.n8n | n8n Container App URL | | AZURE_N8N_RESOURCE_GROUP | azure.n8n | Resource group | | AZURE_N8N_APP_NAME | azure.n8n | App name | | AI | | | | NAVADA_YOLO | ai.yolo | YOLO service URL | | HF_TOKEN | ai.huggingface | HuggingFace token | | OPENAI_API_KEY | ai.openai | OpenAI key |

Programmatic Config

const navada = require('@navada/edge-sdk');

navada.init({
  asus: '10.0.0.1',
  hp: '10.0.0.2',
  ec2: '10.0.0.3',
  oracle: '10.0.0.4',
  mcp: 'http://10.0.0.1:8811',
  dashboard: 'http://10.0.0.1:7900',
  registry: 'http://10.0.0.1:5000',
  cfAccountId: 'your-cf-account-id',
  cfApiToken: 'your-cf-token',
  openaiKey: 'sk-...',
});

You can mix env vars and init() — init() values override env vars.

API Reference

navada.init(config)

Override any config value programmatically.

navada.network

await navada.network.ping()     // Ping all configured nodes + cloud services
await navada.network.status()   // Full status from Command Dashboard
navada.network.nodes             // { asus: { ip, role }, hp: {...}, ... }

navada.mcp

Call tools on the MCP server (Model Context Protocol).

await navada.mcp.tools()                    // List available tools
await navada.mcp.call('tool_name', {args})  // Execute a tool

navada.lucas

Run commands on remote nodes via Lucas CTO MCP.

await navada.lucas.exec('docker ps')             // Bash on EC2
await navada.lucas.ssh('hp', 'df -h')            // SSH to any node
await navada.lucas.docker('container', 'cmd')    // Docker exec
await navada.lucas.deploy('name', 'node')        // Deploy container
await navada.lucas.readFile('/path/to/file')      // Read file
await navada.lucas.writeFile('/path', 'content')  // Write file
await navada.lucas.listFiles('/dir')              // List files
await navada.lucas.networkStatus()                // Full network status

navada.dashboard

Register services and log activity to the Command Center.

await navada.dashboard.register(3000)                  // Register this service
await navada.dashboard.activity('deploy', 'v2 live')   // Log an event

navada.db

Query Postgres. Requires pg package (npm install pg).

await navada.db.query('SELECT NOW()')
await navada.db.query('SELECT * FROM users WHERE id = $1', [42])
const client = await navada.db.getClient()  // For transactions
await navada.db.close()                      // Close pool

navada.registry

Query the private Docker registry.

await navada.registry.catalog()          // ['my-api', 'dashboard', ...]
await navada.registry.tags('my-api')     // ['latest', 'v2']

navada.opencode

Check OpenCode instances on each node.

await navada.opencode.status('asus')   // { node, online, status }
await navada.opencode.statusAll()       // All nodes

navada.cloudflare.r2

Cloudflare R2 object storage.

await navada.cloudflare.r2.buckets()                            // List buckets
await navada.cloudflare.r2.list('images/')                      // List objects
await navada.cloudflare.r2.upload('key', buffer, 'image/png')   // Upload
await navada.cloudflare.r2.upload('key', '/path/to/file.jpg')   // Upload from file
await navada.cloudflare.r2.delete('key')                        // Delete
navada.cloudflare.r2.publicUrl('key')                            // Get public URL

navada.cloudflare.flux

Free AI image generation via Cloudflare Workers AI (Flux model).

const { buffer, size } = await navada.cloudflare.flux.generate('a futuristic city')
await navada.cloudflare.flux.generate('logo', { width: 512, height: 512, savePath: './out.png' })
const { key, url } = await navada.cloudflare.flux.generateAndStore('prompt')  // Generate + upload to R2

navada.cloudflare.stream

Cloudflare Stream video CDN.

await navada.cloudflare.stream.list()                        // All videos
await navada.cloudflare.stream.uploadFromUrl(url, 'Title')   // Upload from URL
await navada.cloudflare.stream.get(videoId)                  // Video info
await navada.cloudflare.stream.delete(videoId)               // Delete
navada.cloudflare.stream.playbackUrl(videoId)                 // HLS URL
navada.cloudflare.stream.embedHtml(videoId)                   // Embed iframe

navada.cloudflare.tunnel

await navada.cloudflare.tunnel.list()        // List active tunnels
await navada.cloudflare.tunnel.get(id)       // Tunnel details

navada.cloudflare.dns

await navada.cloudflare.dns.list()                            // All records
await navada.cloudflare.dns.list('CNAME')                     // Filter by type
await navada.cloudflare.dns.create('CNAME', 'app', 'target')  // Create record

navada.cloudflare.trace(url)

Trace a request through Cloudflare WAF/rules.

await navada.cloudflare.trace('https://your-domain.com')

navada.azure.n8n

Manage n8n on Azure Container Apps.

await navada.azure.n8n.health()    // Health check
navada.azure.n8n.restart()          // Restart via Azure CLI
navada.azure.n8n.url                // Get URL

navada.ai.yolo

YOLOv8 object detection running on your Edge node.

await navada.ai.yolo.health()                      // Service status
await navada.ai.yolo.model()                       // Model info + classes
await navada.ai.yolo.detect('/path/to/image.jpg')  // Detection JSON
const { buffer, detections } = await navada.ai.yolo.detectImage('/path/to/image.jpg')  // Annotated image

navada.ai.huggingface

HuggingFace Inference API. Qwen Coder is free.

await navada.ai.huggingface.qwen('Write a REST API for user auth')  // Qwen Coder 32B
await navada.ai.huggingface.inference('model-name', 'input')         // Any HF model

navada.ai.openai

OpenAI API (GPT, DALL-E).

await navada.ai.openai.chat('What is the ISA allowance?')          // GPT-4o-mini
await navada.ai.openai.chat(messages, { model: 'gpt-4o' })         // Custom model
await navada.ai.openai.image('a futuristic server room')           // DALL-E 3

navada.request(url, opts) / navada.requestMultipart(url, fields, file, opts)

Low-level HTTP helpers. Zero dependencies. Used internally, exposed for custom calls.

const r = await navada.request('http://any-service/api', {
  method: 'POST',
  body: { key: 'value' },
  headers: { 'Authorization': 'Bearer token' },
  timeout: 5000,
});
console.log(r.status, r.data);

Docker Integration

The SDK is designed for Docker-first workflows. In your docker-compose.yml:

services:
  my-api:
    build: .
    env_file: .env
    ports:
      - "3000:3000"

Your .env contains all NAVADA network config. The SDK reads it automatically via process.env.

Security

• Never commit .env files — add .env to .gitignore
• Rotate API keys regularly — the SDK reads fresh from env on each call
• Use Tailscale — nodes communicate over encrypted WireGuard VPN
• Scope Cloudflare tokens — create per-service API tokens with minimal permissions
• Audit logs — use navada.dashboard.activity() to log all operations

Optional Dependencies

The SDK has zero required dependencies. Everything uses Node.js builtins.

Postgres requires the pg package:

pnpm add pg
# or
npm install pg

If pg is not installed, calling navada.db.* throws: pg not installed. Run: npm install pg

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm test
5. Submit a pull request

License

MIT - Leslie Akpareva / NAVADA