Nex Codebase Navigation

NEX Codebase Navigation

Overview

NEX (NATS Execution Engine) is a workload deployment and execution system built on NATS. This skill indexes the codebase structure for efficient navigation.

Repository Structure (synadia-io/nex)

Top-Level Directories

Key Codepaths

1. CLI → Workload Deployment

cmd/nex/main.go           # Entry point, Kong CLI parsing
  └─ cmd/nex/workload.go  # `nex workload start` handler
       └─ client/client.go
            ├─ Auction()           # Bid for workload placement
            └─ StartWorkload()     # Deploy to winning bidder

Key functions:

• client.Auction() - Broadcasts auction request, collects bids
• client.StartWorkload() - Sends deployment request to selected node

2. Node Startup + Agent Registration

node/node.go: NewNexNode()     # Create node with identity
  └─ node/node.go: Start()     # Start NATS handlers
       └─ node/handlers.go     # NATS microservice endpoints
            ├─ handleAuction()              # Respond to auction requests
            ├─ handleAuctionDeployWorkload() # Mint creds + deploy
            └─ handleAgentRegister()        # Accept agent registration

Key functions:

• NewNexNode() - Initializes node with config, identity keys
• Start() - Registers NATS micro handlers, starts heartbeat
• handleAuction() - Evaluates auction request, returns bid
• handleAuctionDeployWorkload() - Mints credentials, deploys to agent

3. Agent Lifecycle

agent/agent.go: Agent interface   # 9 required methods
  └─ Register()                   # Declare capabilities
  └─ StartWorkload()              # Deploy + emit WorkloadStartedEvent
  └─ StopWorkload()               # Terminate + emit WorkloadStoppedEvent
  └─ Heartbeat()                  # Report health every 30s

_test/nexlet_inmem/inmemagent.go  # Reference implementation

Agent interface methods:

type Agent interface {
    // Lifecycle
    Start(ctx context.Context) error
    Stop() error

    // Registration
    Register(parentId string) error
    AgentID() string

    // Workload management
    StartWorkload(request *StartWorkloadRequest) (*WorkloadInfo, error)
    StopWorkload(workloadId string) error
    ListWorkloads() ([]WorkloadInfo, error)

    // Health
    Heartbeat() AgentHeartbeat
}

4. Credential Minting

node/minter.go: SigningKeyMinter
  └─ Mint()                       # Create JWT with scoped permissions
       └─ WorkloadClaims()        # Pub: _INBOX.>, Sub: logs.{ns}.>, _INBOX.>

Workload permissions (scoped JWT):

• Publish: _INBOX.> (request-reply responses)
• Subscribe: logs.{namespace}.>, _INBOX.> (requests)
• Response limit: 1 message per request

File Quick Reference

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                         NEX Architecture                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────┐  │
│  │   Client    │───▶│  NexNode    │───▶│   Agent (Nexlet)        │  │
│  │  (CLI/SDK)  │    │  (Host)     │    │   (Runtime Executor)    │  │
│  └─────────────┘    └─────────────┘    └─────────────────────────┘  │
│        │                  │                       │                  │
│        │    1. Auction    │    2. Deploy          │    3. Execute    │
│        ▼                  ▼                       ▼                  │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                    NATS Messaging Fabric                         ││
│  │  $NEX.SVC.<namespace>.control.*  (auction, deploy)               ││
│  │  $NEX.FEED.<namespace>.event.*   (lifecycle events)              ││
│  │  $NEX.FEED.<namespace>.logs.*    (workload logs)                 ││
│  └─────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘

NATS Subjects

Control Plane (Request-Reply)

Data Plane (Pub/Sub)

deepwiki Queries

Use deepwiki MCP for detailed exploration:

// Get wiki structure
mcp__deepwiki__read_wiki_structure({ repoName: "synadia-io/nex" })

// Ask about specific components
mcp__deepwiki__ask_question({
  repoName: "synadia-io/nex",
  question: "How does the auction system work?"
})

// Explore agent interface
mcp__deepwiki__ask_question({
  repoName: "synadia-io/nex",
  question: "What methods must an agent implement?"
})

// Understand credential minting
mcp__deepwiki__ask_question({
  repoName: "synadia-io/nex",
  question: "How are workload credentials scoped?"
})

Wiki Pages Index

Workload Lifecycles

Event Types

// Node events
type NexNodeStartedEvent struct { ... }
type NexNodeStoppedEvent struct { ... }

// Agent events
type AgentStartedEvent struct { ... }
type AgentStoppedEvent struct { ... }

// Workload events
type WorkloadStartedEvent struct {
    WorkloadId    string
    NodeId        string
    WorkloadName  string
    Namespace     string
    Type          string
    Lifecycle     string
}
type WorkloadStoppedEvent struct { ... }
type WorkloadTriggeredEvent struct { ... }  // For functions

Configuration Files

Node Configuration

{
  "node_name": "my-node",
  "nexus": "default",
  "tags": {
    "env": "production",
    "region": "us-west"
  },
  "agents": ["native"],
  "nats": {
    "servers": ["nats://localhost:4222"],
    "credentials": "/path/to/creds.creds"
  },
  "events": {
    "destinations": ["nats", "logs"]
  }
}

Nexfile Format

name: my-workload
type: native
lifecycle: service
description: My workload description
tags:
  env: production
start_request:
  uri: "file:///path/to/binary"
  argv: ["--config", "/etc/app.yaml"]
  environment:
    LOG_LEVEL: "debug"
  workdir: "/app"

Building Custom Agents

Reference the in-memory test agent:

// _test/nexlet_inmem/inmemagent.go

type InMemoryAgent struct {
    id        string
    parentId  string
    workloads map[string]*WorkloadInfo
    nc        *nats.Conn
}

func (a *InMemoryAgent) Register(parentId string) error {
    a.parentId = parentId
    // Register capabilities with parent node
    return a.nc.Publish(
        fmt.Sprintf("$NEX.SVC.%s.agents.REGISTER", a.parentId),
        registerPayload,
    )
}

func (a *InMemoryAgent) StartWorkload(req *StartWorkloadRequest) (*WorkloadInfo, error) {
    // Validate request
    // Start execution
    // Return workload info
}

Debugging Tips

1. Enable verbose logging:

   nex -v node up
   

2. Subscribe to events:

   nats sub "$NEX.FEED.default.event.>"
   

3. Watch logs:

   nats sub "$NEX.FEED.default.logs.>"
   

4. Check node status:

   nex node list --json
   

Related Skills

• /nex-cli-guide - Complete CLI reference
• /nex-effect-services - Effect-TS integration patterns

References

• NEX GitHub
• NATS Documentation
• NATS Micro Services