# Nami 🌊
**N**ode **A**ccess & **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.
### 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 <img src="https://img.shields.io/pypi/v/nami-surf?color=blue&style=flat-square">
```bash
pip install -U nami-surf
```
### Quick Start
```bash
# 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:**
```bash
# 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:**
```bash
# Set personal config value
nami config set <key> <value>
# Show configuration (all or specific key)
nami config show [key]
```
**File Transfer:**
Nami supports two strategies for moving data between machines:
- **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.
- **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.
```bash
# 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:**
```bash
# 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:
```yaml
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):
```yaml
# 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "nami-surf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ssh, rsync, s3, remote, administration, automation",
"author": null,
"author_email": "Alexander Lutsenko <lex.lutsenko@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/38/5a/617128af468b72d0695e4b2707965c1f2c88cad0aec08c93362e654aa83d/nami_surf-0.1.3.tar.gz",
"platform": null,
"description": "# Nami \ud83c\udf0a\n\n**N**ode **A**ccess & **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- **\ud83d\udd17 Multi-instance SSH management** - Add, list, and connect to remote servers\n- **\ud83c\udf10 Heterogeneous environments** - Works across different Linux distros and cloud providers (Vast, AWS, Runpod, etc.)\n- **\ud83d\udcca GPU monitoring** - GPU utilization and memory tracking\n- **\ud83d\udcc1 File transfer** - Transfer files between instances directly via rsync or using S3 as intermediary\n- **\ud83d\udcdc Template system** - Execute pre-configured bash script templates on remote instances \n- **\u2699\ufe0f Configuration management** - Personal and global configuration storage\n\n### Installation <img src=\"https://img.shields.io/pypi/v/nami-surf?color=blue&style=flat-square\">\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# 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 --env_name myenv --python_version 3.9\n```\n\n### \ud83d\udd27 Commands\n\n**Instance Management:**\n```bash\n# Add a new instance\nnami add <name> <host> <port> [--user USER] [--local-port PORT] [--description DESC]\n\n# List all instances with GPU status\nnami list\n\n# Remove an instance\nnami remove <name>\n\n# Connect via SSH or run a command\nnami ssh <instance> [command]\n```\n\n**Configuration:**\n```bash\n# Set personal config value\nnami config set <key> <value>\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** \u2013 Files are copied directly between the two instances over SSH. This is ideal for smaller transfers and, thanks to rsync\u2019s synchronization logic, it will only transmit files that are new or have changed on the source, saving both time and bandwidth.\n- **s3** \u2013 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**Templates:**\n```bash\n# Execute a template with variables\nnami template <instance> <template_name> \\\n [--var1 value1 --var2 value2 ...]\n```\n\n### \u2699\ufe0f 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 (excluded from git):\n```yaml\n# S3 configuration for file transfers\naws_profile: \"my-profile\"\ns3_bucket: \"my-bucket\"\n\naws_access_key_id: XXXX\naws_secret_access_key: XXXX\naws_endpoint_url: https://XXXX.com\n\n# Other personal settings\n# ...\n```\n\n**Variable Priority**: Template 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",
"bugtrack_url": null,
"license": null,
"summary": "Node Administration Made Intuitive",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/AlexanderLutsenko/nami/issues",
"Homepage": "https://github.com/AlexanderLutsenko/nami",
"Repository": "https://github.com/AlexanderLutsenko/nami"
},
"split_keywords": [
"ssh",
" rsync",
" s3",
" remote",
" administration",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb6b35352b1f4eb010007cd395bf287c8a6001e1db89cace4ae40395d872cd44",
"md5": "e6d8785914fdfbc530d8ed12b20dec23",
"sha256": "ca4123e60cc962f3760b32a8fea107e889018502ee7d060f69f6d3f1f2b0ce93"
},
"downloads": -1,
"filename": "nami_surf-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6d8785914fdfbc530d8ed12b20dec23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15668,
"upload_time": "2025-07-22T16:45:19",
"upload_time_iso_8601": "2025-07-22T16:45:19.447797Z",
"url": "https://files.pythonhosted.org/packages/eb/6b/35352b1f4eb010007cd395bf287c8a6001e1db89cace4ae40395d872cd44/nami_surf-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "385a617128af468b72d0695e4b2707965c1f2c88cad0aec08c93362e654aa83d",
"md5": "45f3b7cc48ba93bcd7ae0a20d8119d67",
"sha256": "18ca49f5d462266dce9409e5342ebe731292e460910cd04a7dbf1dcba06464cf"
},
"downloads": -1,
"filename": "nami_surf-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "45f3b7cc48ba93bcd7ae0a20d8119d67",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15968,
"upload_time": "2025-07-22T16:45:21",
"upload_time_iso_8601": "2025-07-22T16:45:21.605670Z",
"url": "https://files.pythonhosted.org/packages/38/5a/617128af468b72d0695e4b2707965c1f2c88cad0aec08c93362e654aa83d/nami_surf-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 16:45:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AlexanderLutsenko",
"github_project": "nami",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "paramiko",
"specs": [
[
">=",
"3.4.0"
]
]
},
{
"name": "sty",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "nami-surf"
}
JSON
