exo-models

A bash utility for transferring model files between exo nodes using HTTP.

Overview

exo-models.sh is a simple but powerful tool that allows you to download model files from one exo node to another. It works by:

1. Serve mode: Exposing a local directory via HTTP server
2. Download mode: Scraping an HTTP directory listing and downloading all linked files

This is particularly useful for transferring large language models between machines in a distributed exo setup without requiring shared filesystems or complex configuration.

Features

• Two modes: Serve files via HTTP or download from HTTP servers
• Flexible configuration: Custom ports, source/target directories
• Automatic directory creation: Creates target directories if they don't exist
• Simple workflow: Perfect for node-to-node model transfers
• Backward compatible: Still accepts positional arguments for URL

Requirements

• bash (any modern version)
• curl (for downloading)
• python3 with http.server module (for serving)
• grep and sed (for parsing HTML)

All these tools are typically pre-installed on Linux and macOS systems.

Installation

1. Clone or download the repository
2. Make the script executable:

   chmod +x exo-models.sh

3. Optionally, move it to a directory in your PATH:

   sudo mv exo-models.sh /usr/local/bin/exo-models

Usage

./exo-models.sh [OPTIONS]

Options

Flag	Description	Default
--url <URL>	URL to download from	http://localhost:8000
--target-dir <DIR>	Target directory for downloads	current directory
--serve	Start HTTP server instead of downloading	disabled
--bind-port <PORT>	Port to bind HTTP server to	8000
--serve-dir <DIR>	Directory to serve files from	current directory
--self-update-from <URL>	Download and replace script with new version	-
-h, --help	Show help message	-

Examples

Download Mode

Download from localhost to current directory:

./exo-models.sh

Download from a custom URL:

./exo-models.sh --url http://example.com:8080

Download to a specific directory:

./exo-models.sh --url http://localhost:8000 --target-dir ./models

Serve Mode

Serve current directory on default port (8000):

./exo-models.sh --serve

Serve on a custom port:

./exo-models.sh --serve --bind-port 8080

Serve a specific directory:

./exo-models.sh --serve --serve-dir /path/to/models

Full Workflow: Transferring Models Between Exo Nodes

On the source node (the node that has the model):

./exo-models.sh --serve --serve-dir ~/.exo/models/mlx-community--Kimi-K2-Thinking/

On the destination node (the node that needs the model):

./exo-models.sh --url http://source-node-ip:8000 --target-dir ~/.exo/models/mlx-community--Kimi-K2-Thinking/

Self-Update

Update the script to a new version from a remote URL:

./exo-models.sh --self-update-from https://example.com/path/to/exo-models.sh

This downloads the new version, creates a backup of the current version (.bak), replaces the script, and exits. The backup can be used for recovery if needed.

Replace source-node-ip with the actual IP address or hostname of the source node.

How It Works

Download Mode

The script:

1. Fetches the HTML directory listing from the specified URL
2. Parses all href links using grep and sed
3. Filters out directory links (/) and absolute URLs (http*)
4. Downloads each file using curl
5. Optionally places files in a target directory

Serve Mode

The script:

1. Validates the serve directory exists
2. Starts Python's built-in HTTP server on the specified port
3. Serves files from the specified directory using the -d flag
4. Runs until manually stopped (Ctrl+C)

Advanced Usage

Serving Multiple Models

You can serve an entire models directory:

./exo-models.sh --serve --serve-dir ~/.exo/models --bind-port 9000

Then download specific models on another node:

# Download all models
./exo-models.sh --url http://source:9000 --target-dir ~/.exo/models

# Or download into a specific model directory
mkdir -p ~/.exo/models/new-model
./exo-models.sh --url http://source:9000/specific-model/ --target-dir ~/.exo/models/new-model/

Using with Different Network Configurations

For nodes on different networks, you may need to:

1. Ensure the serving node's port is accessible (firewall rules)
2. Use the correct IP/hostname
3. Consider using SSH tunneling for security:

   # On destination node, create tunnel
   ssh -L 8000:localhost:8000 source-node
   
   # Then download via localhost
   ./exo-models.sh --url http://localhost:8000 --target-dir ./models

Troubleshooting

Self-Update Failed

If self-update fails:

• Check the URL is correct and accessible
• Ensure you have write permissions to the script directory
• The original script remains intact if download fails
• Restore from backup: mv exo-models.sh.bak exo-models.sh

Port Already in Use

If you get "Address already in use" error:

# Use a different port
./exo-models.sh --serve --bind-port 8080

Connection Refused

If you get "Connection refused" when downloading:

• Verify the source node is running and accessible
• Check firewall rules
• Ensure you're using the correct IP/hostname and port

Permission Denied

If you get permission errors when downloading:

• Ensure you have write permissions to the target directory
• Use sudo if downloading to system directories
• Or download to a directory you own first, then move files

Security Considerations

• This tool uses plain HTTP, not HTTPS. Only use on trusted networks.
• The HTTP server exposes all files in the served directory. Be careful what you serve.
• Consider using SSH tunneling for secure transfers over untrusted networks.
• No authentication is implemented. Anyone can download served files.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

mlx-community/Kimi-K2-Thinking

Contributor

mlx-community/MiniMax-M2.7-8bit