Node Operator Guide¶

This comprehensive guide covers everything you need to deploy and manage Manta nodes - the distributed agents that execute tasks on your computing resources.

CLI Reference

Configuration Reference

Quick Start¶

Get a node running in minutes:

# Install the node software
pip install manta-node

# Create configuration interactively
manta_node config init

# Start your node
manta_node start default

# Check status
manta_node status

What is a Manta Node?¶

A Manta node is a lightweight agent that:

Executes Tasks: Runs containerized workloads sent by the platform
Manages Resources: Controls CPU, memory, and GPU allocation
Provides Data Access: Serves local datasets to running tasks
Reports Metrics: Sends health and performance data to the manager
Maintains Security: Ensures isolated, secure task execution

Node Architecture¶

┌─────────────────────────────────────────┐
│           Manta Platform                 │
│  ┌─────────────┐      ┌─────────────┐  │
│  │   Manager   │◄─────│   Frontend  │  │
│  └──────┬──────┘      └─────────────┘  │
│         │                               │
└─────────┼───────────────────────────────┘
          │ gRPC/MQTT
┌─────────▼───────────────────────────────┐
│           Manta Node                     │
│  ┌─────────────────────────────────┐    │
│  │         Node Agent               │    │
│  │  ┌──────────┐  ┌──────────┐    │    │
│  │  │  gRPC    │  │  MQTT    │    │    │
│  │  │ Services │  │  Client  │    │    │
│  │  └──────────┘  └──────────┘    │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │      Task Execution Engine      │    │
│  │  ┌──────────┐  ┌──────────┐    │    │
│  │  │  Docker  │  │  Dataset │    │    │
│  │  │ Manager  │  │  Manager │    │    │
│  │  └──────────┘  └──────────┘    │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

Installation Methods¶

Standard Installation¶

For most users:

# Install from PyPI
pip install manta-node

# Or install from source
git clone https://github.com/manta-network/manta-node
cd manta-node
pip install -e .

Docker Installation¶

For containerized deployments:

# Pull the official image
docker pull manta/node:latest

# Run with configuration
docker run -d \
  --name manta-node \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.manta:/root/.manta \
  -e MANTA_NODE_TOKEN=$TOKEN \
  manta/node:latest

System Requirements¶

Minimum:

Python 3.9+ or Docker
2 CPU cores
4 GB RAM
10 GB storage
Network connectivity

Recommended:

8+ CPU cores
16+ GB RAM
100+ GB SSD storage
GPU with CUDA (for ML workloads)
1 Gbps network

Configuration Overview¶

Nodes are configured through TOML files stored in ~/.manta/nodes/:

# Example configuration
[identity]
secured_token = "${MANTA_NODE_TOKEN}"
alias = "gpu-worker-1"

[network]
manager_host = "localhost"
manager_port = 50051

[resources]
max_concurrent_tasks = 2

[datasets]
mappings = {
  "training_data" = "/data/datasets/training"
}

Management Commands¶

The manta_node CLI provides comprehensive node management:

Configuration Management:

config init - Create new configuration interactively
config list - List available configurations
config show - Display configuration details
config validate - Verify configuration validity
config edit - Edit configuration in text editor
config delete - Remove configuration

Node Operations:

start - Start a node instance
stop - Stop running nodes
status - Check node status
logs - View node logs

Cluster Management:

cluster start - Start multiple nodes
cluster stop - Stop cluster nodes

Common Use Cases¶

Single Node Deployment¶

Perfect for development and testing:

# Configure node
manta_node config init

# Start in foreground for debugging
manta_node start default

# Or start in background
manta_node start default --background

Multi-Node Cluster¶

For parallel processing:

# Start cluster with same config
manta_node cluster start 5 --config production

# Or configure each node individually
manta_node cluster 5

GPU Workstation¶

For machine learning tasks:

[identity]
alias = "ml-workstation"

[containers]
gpu_enabled = true

[resources]
max_concurrent_tasks = 1  # One task at a time for GPU

Edge Device¶

For resource-constrained environments:

[identity]
alias = "edge-sensor-1"

[resources]
reserve_cpu_percent = 5
reserve_memory_mb = 256
max_concurrent_tasks = 1

Security Considerations¶

Authentication¶

Nodes authenticate using JWT tokens
Tokens contain permissions and expiration
Never commit tokens to version control
Use environment variables for tokens

Network Security¶

TLS encryption for production
Firewall rules to limit access
Private networks for sensitive data
Monitor for unauthorized connections

Container Isolation¶

Tasks run in isolated Docker containers
Resource limits prevent exhaustion
Network isolation between tasks
Filesystem access controls

Best Practices¶

Configuration Management
- Use version control for configs (without tokens)
- Document your configuration choices
- Validate configs before deployment
- Keep backups of working configurations
Resource Planning
- Monitor resource usage regularly
- Set appropriate limits
- Plan for peak loads
- Leave headroom for system processes
Monitoring and Logging
- Enable appropriate log levels
- Configure log rotation
- Monitor node health
- Set up alerting for failures
Security
- Rotate tokens regularly
- Use TLS in production
- Limit network exposure
- Keep software updated
Maintenance
- Schedule regular restarts
- Clean up old logs and data
- Update node software
- Test disaster recovery

Troubleshooting¶

Common Issues¶

Node won’t start:

Check configuration validity
Verify Docker is running
Ensure manager is reachable
Check JWT token validity

Tasks failing:

Review task logs
Check resource availability
Verify dataset access
Monitor container health

Connection issues:

Test network connectivity
Check firewall rules
Verify DNS resolution
Validate certificates

Debug Mode¶

Enable detailed logging for troubleshooting:

[logging]
level = "DEBUG"
debug_mode = true
log_to_console = true