Noderax Agent

Noderax Agent is the Go-based node runtime for the platform. It enrolls a machine, opens the agent realtime socket, streams telemetry, claims tasks over HTTP long polling by default, and executes supported operations such as shell commands and package management.

Highlights

• Enrollment-based node onboarding with approval tokens
• Background service support for Linux-based systems
• Built-in CLI for install, start, stop, restart, status, and config updates
• Realtime Socket.IO session for agent auth, metrics, and lifecycle signaling
• HTTP long-poll task claiming as the primary execution path
• Interactive terminal session support over the agent realtime socket
• Heartbeat-based agent version, platform version, and kernel telemetry for fleet visibility
• Graceful cancellation with log-drain timeout handling
• Non-interactive execution environment with PAGER=cat and high COLUMNS
• PTY shell fallback modes for hosts where the default controlling-TTY start path is restricted
• Scheduled runs arrive as standard queued tasks, so no separate schedule runtime is required on the agent
• Persistent node identity storage

Supported Platforms

• Linux-based systems with systemd (Ubuntu, Debian, CentOS, RHEL, etc.)
• Manual source-based execution on other developer environments

Quick Install

Prerequisites:

• git
• go

git clone <repo-url> noderax-agent
cd noderax-agent
sudo ./scripts/install.sh

The installer:

• asks for the API URL
• asks for the enrollment email
• requests an enrollment token
• waits for approval from the web UI
• installs the agent as a background service
• starts it automatically

When you run the installer from a source checkout, it mirrors the entered values into repository-level config.json for local visibility. The managed service still reads its OS-specific config path.

Installed Paths

Linux (systemd)

• Binary: /opt/noderax-agent/noderax-agent
• Symlink: /usr/local/bin/noderax-agent
• Config: /etc/noderax-agent/config.json
• State: /var/lib/noderax-agent/agent_identity.json
• Service: /etc/systemd/system/noderax-agent.service

Manual Installation

1. Build the agent

go build -o noderax-agent ./cmd/agent

2. Prepare a config file

cp config.example.json config.json

Set at least:

• api_url

Leave enrollment_token empty. The enrollment command will populate it.

3. Run enrollment

./noderax-agent enroll

The agent will:

• ask for the enrollment email
• call POST /api/v1/enrollments/initiate
• save the returned token
• poll GET /api/v1/enrollments/{token}
• persist the approved nodeId and agentToken

4. Start the agent manually

./noderax-agent

Use a custom config path if needed:

NODERAX_CONFIG_FILE=/path/to/config.json ./noderax-agent

Service Management

sudo noderax-agent start
sudo noderax-agent stop
sudo noderax-agent restart
sudo noderax-agent status

Configuration Management

Show active config:

noderax-agent config show

Update config values:

sudo noderax-agent config set api_url https://api.example.com
sudo noderax-agent config set task_timeout 30s
sudo noderax-agent config set metrics_interval 15s
sudo noderax-agent config set log_level debug

Supported keys:

• api_url
• enrollment_token
• node_id
• agent_token
• heartbeat_interval
• metrics_interval
• task_poll_interval
• request_timeout
• task_timeout
• shutdown_timeout
• realtime_enabled
• realtime_ping_interval
• realtime_queue_size
• realtime_backoff_jitter
• realtime_namespace
• realtime_path
• state_file
• log_level

Task Delivery Model

The current default execution path is HTTP polling.

• The agent long-polls POST /api/v1/agent/tasks/claim
• A claimed task is acknowledged with accepted and started
• Logs are appended through POST /api/v1/agent/tasks/:taskId/logs
• Completion is posted to POST /api/v1/agent/tasks/:taskId/completed
• Cancellation intent is checked through agent control polling

The agent realtime socket remains important for:

• agent authentication
• metrics streaming
• lifecycle support
• interactive terminal control and streaming
• optional compatibility with API-side realtime task dispatch when explicitly enabled

Fleet visibility uses heartbeat telemetry only. The current product surface does not include agent self-update orchestration inside the agent runtime; upgrades remain an external deployment concern.

Realtime Socket.IO v4

Typical realtime settings:

NODERAX_API_URL=https://<domain>
NODERAX_REALTIME_NAMESPACE=/agent-realtime
NODERAX_REALTIME_PATH=/socket.io/
NODERAX_REALTIME_PING_INTERVAL=2s
NODERAX_REALTIME_METRICS_INTERVAL=3s

Notes:

• Auth is performed after socket connection with agent.auth
• Namespace and Engine.IO path are configured separately
• Startup performs a polling health-check against /socket.io/ before the full socket session is used

Common failure modes:

• invalid URL input
• tls/proxy handshake failure
• namespace connect failure
• auth error

Interactive Terminal Sessions

Interactive terminal sessions are not delivered through the HTTP task claim loop. They use the agent realtime socket directly.

Incoming control events:

• terminal.start
• terminal.input
• terminal.resize
• terminal.stop

Outgoing lifecycle events:

• terminal.opened
• terminal.output
• terminal.exited
• terminal.error

Implementation notes:

• The agent opens a PTY-backed interactive shell rather than reusing the non-interactive task executor
• Shell resolution tries $SHELL, /bin/bash, /bin/zsh, then /bin/sh
• Unix PTY startup falls back across multiple modes:
  • pty+ctty
  • pty-no-ctty
  • pty-minimal
• The terminal session environment sets TERM=xterm-256color and PAGER=cat
• Output is chunked and flushed on a timer so the web console receives live updates without waiting for more keystrokes
• On constrained hosts, fallback PTY modes may log reduced job-control capability while remaining usable

Task Execution Environment

The agent executes shell.exec tasks in a controlled non-interactive environment:

• PAGER=cat
• COLUMNS=100000
• graceful cancellation with log drain timeout
• scheduled tasks use the same execution path as manually queued tasks

For package listing on Debian/Ubuntu, the agent uses optimized dpkg -l parsing to return structured package metadata.

Project Structure

• cmd/agent: application entrypoint and CLI dispatch
• internal/agent: enrollment, identity persistence, bootstrap
• internal/agentctl: install, service management, config CLI
• internal/api: HTTP client and API models
• internal/tasks: HTTP claim loop and task execution
• internal/metrics: metrics worker
• internal/realtime: Socket.IO client and handlers
• internal/system: host and system information helpers
• scripts: installation entrypoints

Development

Run tests:

go test ./...

Build locally:

go build -o noderax-agent ./cmd/agent

Run in foreground:

cp config.example.json config.json
./noderax-agent enroll
./noderax-agent

Notes

• Linux installation assumes systemd.

• The managed service config path can be overridden with NODERAX_CONFIG_FILE.

• API-side realtime task push is not the default control path; HTTP claiming should be considered the normal operating mode.

• Interactive terminals are the main exception: they depend on the agent realtime socket being healthy.

• When a node is put into maintenance mode from the control plane, the API stops assigning new work to that node while in-flight tasks are allowed to finish.