{"id":30186270,"url":"https://github.com/alexanderlutsenko/nami","last_synced_at":"2026-01-20T17:35:16.827Z","repository":{"id":305736943,"uuid":"1023779394","full_name":"AlexanderLutsenko/nami","owner":"AlexanderLutsenko","description":"Node Administration Made Intuitive","archived":false,"fork":false,"pushed_at":"2025-08-10T10:27:39.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-10T12:26:43.746Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexanderLutsenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-21T17:20:23.000Z","updated_at":"2025-08-10T10:27:42.000Z","dependencies_parsed_at":"2025-08-10T12:14:00.611Z","dependency_job_id":"41da8848-45ba-4b98-badd-ffaccc881929","html_url":"https://github.com/AlexanderLutsenko/nami","commit_stats":null,"previous_names":["alexanderlutsenko/nami"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AlexanderLutsenko/nami","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderLutsenko%2Fnami","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderLutsenko%2Fnami/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderLutsenko%2Fnami/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderLutsenko%2Fnami/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexanderLutsenko","download_url":"https://codeload.github.com/AlexanderLutsenko/nami/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderLutsenko%2Fnami/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270073666,"owners_count":24522393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-12T14:10:57.068Z","updated_at":"2026-01-20T17:35:16.820Z","avatar_url":"https://github.com/AlexanderLutsenko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nami 🌊\n\n**N**ode **A**ccess \u0026 **M**anipulation **I**nterface 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.\n\n### Features\n\n- **🔗 Multi-instance SSH management** - Add, list, and connect to remote servers\n- **🌐 Heterogeneous environments** - Works across different Linux distros and cloud providers (Vast, AWS, Runpod, etc.)\n- **📊 GPU monitoring** - GPU utilization and memory tracking\n- **📁 File transfer** - Transfer files between instances directly via rsync or using S3 as intermediary\n- **🗄️ NFS mesh mounting** - Set up and mount shared directories across selected instances\n- **📜 Template system** - Execute pre-configured bash script templates on remote instances  \n- **⚙️ Configuration management** - Personal and global configuration storage\n\n### Installation \u003cimg src=\"https://img.shields.io/pypi/v/nami-surf?color=blue\u0026style=flat-square\"\u003e\n\n```bash\npip install -U nami-surf\n```\n\n### 🚀 Quick Start\n\n```bash\n# Add a remote instance\nnami add gpu-box 192.168.1.100 22 --user ubuntu --description \"Main GPU server\"\n\n# List all instances with GPU status\nnami list\n\n# Connect to an instance via SSH  \nnami ssh gpu-box\n\n# Run a command on an instance\nnami ssh gpu-box \"nvidia-smi\"\n\n# Forward an arbitrary local port (override the one in config)\nnami ssh gpu-box --forward 9000\n\n# Transfer files between instances\nnami transfer --source_instance local --dest_instance gpu-box --source_path ./data --dest_path ~/data\n\n# Upload files to S3 from an instance\nnami to_s3 --source_instance gpu-box --source_path ~/results --dest_path s3://bucket/experiment1/\n\n# Download files from S3 to an instance  \nnami from_s3 --dest_instance gpu-box --source_path s3://bucket/dataset/ --dest_path ~/data/\n\n# Execute a template on an instance\nnami template gpu-box setup_conda\n```\n\n#### Example output\n```text\n$ nami list\n\n📋 Configured Instances:\n-----------------------------------------------------------------\n🖥️ training-box (✅ Online)\n   SSH: ubuntu@203.0.113.10:2222, local port: 8080\n   Description: Primary training server\n   GPUs:\n     🟢 GPU0:   0% | Mem:   2% | NVIDIA A100 80GB\n     🔴 GPU1: 100% | Mem:  94% | NVIDIA A100 80GB\n     🟠 GPU2:   0% | Mem:  51% | NVIDIA A100 80GB\n\n🖥️ idle-node (✅ Online)\n   SSH: admin@203.0.113.11:2222\n   Description: Spare capacity node\n   GPUs:\n     🟢 GPU0:   0% | Mem:   0% | NVIDIA H100\n\n🖥️ backup-box (❌ Offline)\n   SSH: root@203.0.113.12:2222\n   Description: Cold backup server\n```\n\n### 🔧 Commands\n\n#### Instance Management\n```bash\n# List all instances with GPU status\nnami list\n\n# Connect via SSH or run a command\nnami ssh \u003cinstance_name\u003e [command] [--forward [PORT]]\n\n# Add a new instance\nnami add \u003cinstance_name\u003e \u003chost\u003e \u003cport\u003e [--user USER] [--local-port PORT] [--description DESC]\n\n# Remove an instance\nnami remove \u003cinstance_name\u003e\n\n# Add SSH public key to instance(s)\nnami ssh-key add \"\u003cpublic_key\u003e\" [--instance \u003cinstance_name\u003e]\n\n# Remove SSH key(s) matching a pattern from instance(s)\nnami ssh-key remove \"\u003cpattern\u003e\" [--instance \u003cinstance_name\u003e]\n```\n\n#### Configuration\n```bash\n# Set personal config value\nnami config set \u003ckey\u003e \u003cvalue\u003e\n\n# Show configuration (all or specific key)\nnami config show [key]\n```\n\n#### File Transfer\n\nNami supports two strategies for moving data between machines:\n\n- **rsync** – Files are copied directly between the two instances over SSH. This is ideal for smaller transfers and, thanks to rsync’s synchronization logic, it will only transmit files that are new or have changed on the source, saving both time and bandwidth.\n- **s3** – Data are first uploaded from the source instance to an S3 bucket and then downloaded to the destination instance. Despite the extra hop, this approach is usually the fastest for large datasets because the upload/download steps can fully saturate network bandwidth and run in parallel.\n\n```bash\n# Transfer files between instances\nnami transfer --source_instance SRC \\\n    --dest_instance DEST \\\n    --source_path PATH \\\n    [--dest_path PATH] \\\n    [--method rsync|s3] \\\n    [--exclude PATTERNS] \\\n    [--archive] \\\n    [--rsync_opts \"OPTIONS\"]\n\n# Upload to S3\nnami to_s3 \\\n    --source_instance INSTANCE \\\n    --source_path PATH \\\n    --dest_path S3_PATH \\\n    [--exclude PATTERNS] \\\n    [--archive] \\\n    [--aws_profile PROFILE]\n\n# Download from S3  \nnami from_s3 \n    --dest_instance INSTANCE \\\n    --source_path S3_PATH \\\n    --dest_path PATH \\\n    [--exclude PATTERNS] \\\n    [--archive] \\\n    [--aws_profile PROFILE]\n```\n\n#### NFS Mesh\n\nSet up NFS exports on selected servers and mount a full mesh among them (each instance mounts every other instance, including itself via loopback) in one command.\n\n```bash\n# Export local /workspace on each server; mount peers under /mnt/peers/\u003cinstance\u003e\nnami nfs mount-mesh \\\n--instances instance-1 instance-2 instance-3 \\\n--export_dir /workspace \\\n--mount_base /mnt/peers\n```\n\nAfter this completes on, say, `instance-1`, running `ls /mnt/peers` will show one directory per selected instance (including itself).\n\n```bash\ninstance-1$ ls /mnt/peers\ninstance-1  instance-2  instance-3\n```\n\nNotes:\n- The command installs and configures NFS server on the selected instances (if needed) and exports `--export_dir`.\n- On each instance, mounts every peer under `--mount_base/\u003cinstance-name\u003e` using NFSv4.\n- Idempotent behavior: if the mount directory is a real non-empty directory (not a mount), it is skipped to avoid masking data; otherwise mounts/remounts as needed.\n- Changing `--export_dir` updates existing mounts and `/etc/fstab` entries accordingly.\n- Ensure network access to NFS ports (2049/TCP+UDP and 111/TCP+UDP) in your firewall/Security Groups.\n\n#### Templates\n```bash\n# Execute a template with variables\nnami template \u003cinstance\u003e \u003ctemplate_name\u003e \\\n    [--var1 value1 --var2 value2 ...]\n```\n\n### ⚙️ Configuration\n\nNami stores its configuration in `~/.nami/`:\n\n- `config.yaml` - Instance definitions and global settings\n- `personal.yaml` - User-specific configurations (S3 bucket, AWS profile, etc.)\n- `templates/` - Custom bash script templates\n\n#### Configuration File Structure\n\n**`~/.nami/config.yaml`** - Main configuration file:\n```yaml\ninstances:\n  gpu-box:\n    host: \"192.168.1.100\"\n    port: 22\n    user: \"ubuntu\"\n    description: \"Main GPU server\"\n    local_port: 8888  # optional - for SSH tunneling\n  \n  cloud-instance:\n    host: \"ec2-xxx.compute.amazonaws.com\"\n    port: 22\n    user: \"ec2-user\"\n    description: \"AWS EC2 instance\"\n\nvariables:\n  # Global template variables available to all templates\n  # var1: value1\n  # ...\n```\n\n**`~/.nami/personal.yaml`** - User-specific settings:\n```yaml\nhome_dir: \"/workspace/\u003cusername\u003e\"\n\ns3_bucket: \"\u003cusername\u003e\"\n\naws_profile: \"my-profile\"\naws_access_key_id: XXXX\naws_secret_access_key: XXXX\naws_endpoint_url: https://XXXX.com\n\n# Other personal settings\nssh_key: \"~/.ssh/id_rsa_default\"  # Default SSH key for all instances\nssh_keys:  # Per-instance SSH key overrides\n  gpu-box: \"~/.ssh/id_rsa_custom\"\n  cloud-instance: \"~/.ssh/id_ed25519_custom\"\n\n```\n\n#### Variable Priority\nTemplate variables are resolved in this order (highest priority first):\n1. Command-line variables (`--var key=value`)\n2. Personal config (`personal.yaml`)\n3. Global config (`config.yaml` variables section)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderlutsenko%2Fnami","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexanderlutsenko%2Fnami","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderlutsenko%2Fnami/lists"}