Quick Install

Get ModelKnife running in 2 minutes

ModelKnife is a Python package that orchestrates ML workflows on AWS. Follow these steps to get started quickly.

Prerequisites

  • Python 3.8+ and pip
  • AWS account with CLI configured

Step 1: Install ModelKnife

One command installation

# Install ModelKnife
pip install git+ssh://git@github.com/naoo-AI/modelknife.git

# Verify installation
mk --help

✅ Success! If you see the help text, ModelKnife is installed correctly.

Step 2: Configure AWS

Set up your AWS connection

# Configure AWS CLI (if not already done)
aws configure

# Test AWS connection
mk setup status

If you see connection details, you're ready! If not, make sure your AWS CLI is configured with valid credentials.

Step 3: Choose Your Path

First user or joining an existing team?

Critical Decision: Are you the FIRST person in your organization using ModelKnife?

This determines whether you need to create AWS resources or just get access to existing ones.

YES - I'm the First User

You are:

  • The first person in your organization using ModelKnife
  • Have AWS admin permissions
  • Need to create AWS resources

What you need to do:

# Create all AWS resources and team setup
mk setup init

✅ This creates IAM roles, groups, and permissions for your entire team

NO - I'm Joining a Team

You are:

  • Someone else already set up ModelKnife
  • Need to be added to an existing team
  • Don't have AWS admin permissions

What you need to do:

  1. DO NOT run mk setup init
  2. Ask your admin to add you:
# Admin runs this command
mk team add-user --user YOUR_USERNAME --group mlknife-developers

ℹ️ Skip to Step 4: Verification after admin adds you

Not Sure Which Path?

Check with this command:

mk setup status
  • If you see "Global configuration missing" → You're likely the First User
  • If you see AWS resources configured → You're Joining a Team

Step 4: Verify Everything Works

Test your ModelKnife installation

# Check your setup status
mk setup status

# Check your team access
mk team status

# Try deploying a test service (optional)
mk s deploy --help

🎉 You're ready! If the status commands show green checkmarks, ModelKnife is working correctly.

Troubleshooting

Common issues and quick fixes

Installation Issues

Problem: "Permission denied" during pip install

Solution:

# Use virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install git+ssh://git@github.com/naoo-AI/modelknife.git

Platform-Specific Prerequisites

Platform Installation Guides

Click on your operating system below to view detailed installation instructions. Each guide includes prerequisites, installation commands, and platform-specific troubleshooting tips. Docker is required for Lambda packaging and local development.

Windows Setup

Click to view installation instructions

macOS Setup

Click to view installation instructions

Linux Setup

Click to view installation instructions

🔧 Cross-Platform Troubleshooting

Platform-Specific Issues

Different operating systems have unique challenges. Click your platform below for targeted solutions:

🪟 Windows Troubleshooting
Problem: "python is not recognized as an internal or external command"

Solutions:

  • Reinstall Python and check "Add Python to PATH"
  • Use py -3 instead of python
  • Manually add Python to system PATH
# Check Python installation
py -3 --version
where python

# Add to PATH (replace with your Python path)
setx PATH "%PATH%;C:\Users\%USERNAME%\AppData\Local\Programs\Python\Python311"
Problem: Docker Desktop issues

Solutions:

  • Enable WSL 2: wsl --install
  • Enable Hyper-V in Windows Features
  • Enable virtualization in BIOS
  • Restart Docker Desktop
# Check WSL 2 status
wsl --list --verbose
wsl --update
Problem: Permission denied errors

Solutions:

  • Run PowerShell as Administrator
  • Use virtual environment to avoid system-wide installs
  • Check antivirus exclusions
🍎 macOS Troubleshooting
Problem: "command not found" after Homebrew installation

Solutions:

  • Apple Silicon: Add /opt/homebrew/bin to PATH
  • Intel: Check /usr/local/bin is in PATH
  • Restart terminal after installation
# Apple Silicon - add to ~/.zshrc
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Problem: Xcode Command Line Tools issues

Solutions:

# Install Xcode Command Line Tools
xcode-select --install

# Reset if corrupted
sudo xcode-select --reset
🐧 Linux Troubleshooting
Problem: Docker permission denied

Solutions:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then test
docker run hello-world
Problem: "python: command not found"

Solutions:

  • Use python3 and pip3 commands
  • Create alias: alias python=python3
  • Install python-is-python3 package
Problem: "externally-managed-environment" error

Solutions:

# Use virtual environment (recommended)
python3 -m venv mlknife-env
source mlknife-env/bin/activate
pip install git+https://github.com/naoo-AI/modelknife.git

AWS Connection Issues

Problem: "AWS connection failed"

Solutions:

# Test AWS CLI directly
aws sts get-caller-identity

# Reconfigure if needed
aws configure

# Check credentials file
cat ~/.aws/credentials  # Linux/macOS
type %USERPROFILE%\.aws\credentials  # Windows

Still Need Help?

If you're still experiencing issues:

  1. Run diagnostics: mk setup status
  2. Enable verbose logging: export MLKNIFE_VERBOSE=1
  3. Check our detailed troubleshooting guide
  4. Report issues: GitHub Issues

When reporting issues, include:

  • Operating system and version
  • Python version: python --version
  • Full error message
  • Steps to reproduce

Team Management (For Admins)

Add team members after running mk setup init

You've successfully run mk setup init!

Now you can add team members to start using ModelKnife. Here's how:

Adding New Team Members

Add Developers

Most team members should be developers:

# Add developer (can deploy services/pipelines)
mk team add-user --user USERNAME --group mlknife-developers

Add Admins

For team leads who manage users:

# Add admin (can manage team + deploy)
mk team add-user --user USERNAME --group mlknife-admin

Check Team Status

# See all team members and their roles
mk team status

# List all users in a specific group
mk team list-users --group mlknife-developers

Instructions for Your Team Members

Share this with new team members:

"I've added you to our ModelKnife team! Here's how to get started:"

  1. Install ModelKnife: pip install git+https://github.com/naoo-AI/modelknife.git
  2. Configure AWS: aws configure (use our shared AWS account)
  3. Test access: mk team status (you should see developer access)
  4. Start deploying: mk s deploy or mk p deploy

Important: They do not need to run mk setup init - you already did that!

What AWS Resources Did mk setup init Create?

Your mk setup init command created these AWS resources for your team:

  • IAM Groups: mlknife-admin, mlknife-developers
  • IAM Roles: For SageMaker, Glue, Step Functions, Lambda
  • IAM Policies: Least-privilege permissions for ML services
  • Account Setup: Ready for team collaboration

All team members automatically use these shared resources - no configuration needed!

What's Next?

Start building ML pipelines

Quick Start Guide

Deploy your first ML pipeline in 5 minutes

Examples

Real-world ML pipeline templates and use cases

Configuration

YAML configuration reference and best practices

Working with Multiple AWS Accounts?

ModelKnife supports multiple organizations and environments using AWS profiles: 

# Switch between accounts/environments
export MLKNIFE_AWS_PROFILE=dev-account
mk setup status

export MLKNIFE_AWS_PROFILE=prod-account
mk s deploy