nami-surf 0.1.1

Node Administration Made Intuitive

Nami 🌊

Node Access & Manipulation Interface is a simple tool for managing connections to multiple remote instances (particularly GPU servers), with built-in GPU monitoring, file transfer capabilities via rsync/S3, and a template system for common tasks.

Features

• 🔗 Multi-instance SSH management - Add, list, and connect to remote servers
• 🌐 Heterogeneous environments - Works across different Linux distros and cloud providers (Vast, AWS, Runpod, etc.)
• 📊 GPU monitoring - GPU utilization and memory tracking
• 📁 File transfer - Transfer files between instances directly via rsync or using S3 as intermediary
• 📜 Template system - Execute pre-configured bash script templates on remote instances
• ⚙️ Configuration management - Personal and global configuration storage

Installation

pip install -U nami-surf

Quick Start

# Add a remote instance
nami add gpu-box 192.168.1.100 22 --user ubuntu --description "Main GPU server"

# List all instances with GPU status
nami list

# Connect to an instance via SSH  
nami ssh gpu-box

# Run a command on an instance
nami ssh gpu-box "nvidia-smi"

# Transfer files between instances
nami transfer --source_instance local --dest_instance gpu-box --source_path ./data --dest_path ~/data

# Upload files to S3 from an instance
nami to_s3 --source_instance gpu-box --source_path ~/results --dest_path s3://bucket/experiment1/

# Download files from S3 to an instance  
nami from_s3 --dest_instance gpu-box --source_path s3://bucket/dataset/ --dest_path ~/data/

# Execute a template on an instance
nami template gpu-box setup_conda --env_name myenv --python_version 3.9

🔧 Commands

Instance Management:

# Add a new instance
nami add <name> <host> <port> [--user USER] [--local-port PORT] [--description DESC]

# List all instances with GPU status
nami list

# Remove an instance
nami remove <name>

# Connect via SSH or run a command
nami ssh <instance> [command]

Configuration:

# Set personal config value
nami config set <key> <value>

# Show configuration (all or specific key)
nami config show [key]

File Transfer:

# Transfer files between instances
nami transfer --source_instance SRC --dest_instance DEST \
              --source_path PATH \
              [--dest_path PATH] \
              [--method rsync|s3] \
              [--exclude PATTERNS] \
              [--archive] \
              [--rsync_opts "OPTIONS"]

# Upload to S3
nami to_s3 --source_instance INSTANCE \
           --source_path PATH \
           --dest_path S3_PATH \
           [--exclude PATTERNS] \
           [--archive] \
           [--aws_profile PROFILE]

# Download from S3  
nami from_s3 --dest_instance INSTANCE \
             --source_path S3_PATH \
             --dest_path PATH \
             [--exclude PATTERNS] \
             [--archive] \
             [--aws_profile PROFILE]

Templates:

# Execute a template with variables
nami template <instance> <template_name> [--var1 value1 --var2 value2 ...]

⚙️ Configuration

NAMI stores its configuration in ~/.nami/:

• config.yaml - Instance definitions and global settings
• personal.yaml - User-specific configurations (S3 bucket, AWS profile, etc.)
• templates/ - Custom bash script templates

Configuration File Structure

~/.nami/config.yaml - Main configuration file:

instances:
  gpu-box:
    host: "192.168.1.100"
    port: 22
    user: "ubuntu"
    description: "Main GPU server"
    local_port: 8888  # optional - for SSH tunneling
  
  cloud-instance:
    host: "ec2-xxx.compute.amazonaws.com"
    port: 22
    user: "ec2-user"
    description: "AWS EC2 instance"

variables:
  # Global template variables available to all templates
  # var1: value1
  # ...

~/.nami/personal.yaml - User-specific settings (excluded from git):

# S3 configuration for file transfers
aws_profile: "my-profile"
s3_bucket: "my-bucket"

aws_access_key_id: XXXX
aws_secret_access_key: XXXX
aws_endpoint_url: https://XXXX.com

# Other personal settings
# ...

Variable Priority: Template variables are resolved in this order (highest priority first):

1. Command-line variables (--var key=value)
2. Personal config (personal.yaml)
3. Global config (config.yaml variables section)