Quick Start Guide¶

Get up and running with azlin in 5 minutes.

Prerequisites¶

Azure account (create free account)
Azure CLI installed and configured (az login)

Step 1: Install azlin¶

# Download pre-built binary (recommended)
curl -sSL https://github.com/rysweet/azlin/releases/latest/download/azlin-linux-x86_64.tar.gz | tar xz -C ~/.local/bin

Or run without installing:

uvx --from git+https://github.com/rysweet/azlin azlin new

See Installation for all options including macOS, Cargo, and pip.

az login

Step 3: Create Your First VM¶

azlin new --name myproject

azlin will:

Create an Ubuntu 24.04 VM
Install 12 development tools
Configure SSH access
Start tmux session
Connect you automatically

Total time: 4-7 minutes

Step 4: Verify VM¶

Once connected, verify the tools:

# Check Docker
docker --version

# Check Python
python3 --version

# Check Node.js
node --version

# List all installed tools
which docker az gh git node python3 rustc go dotnet

Step 5: Explore Commands¶

# List all your VMs
azlin list

# Check VM health with Four Golden Signals
azlin health

# View distributed metrics
azlin top

# Keep azlin up to date
azlin self-update

What's Next?¶

Create Shared Storage - Set up NFS storage
GUI Forwarding - Run remote GUI apps locally
Set Up Authentication - Use service principals

Troubleshooting¶

Issue: Quota exceeded

Check Azure quota limits with az vm list-usage --location <region>.

Issue: Connection timeout

Verify SSH connectivity and that the VM's public IP is accessible.

Issue: Authentication failed

Run az login to refresh your Azure credentials. See Service Principal Auth for automated setups.

Quick Reference¶

Essential Commands¶

# VM Lifecycle
azlin new --name myvm          # Create VM
azlin list                     # List VMs
azlin connect myvm             # Connect to VM
azlin stop myvm                # Stop VM
azlin start myvm               # Start VM
azlin destroy myvm             # Delete VM

# GUI Forwarding
azlin connect --x11 myvm      # X11 forwarding for lightweight GUI apps
azlin gui myvm                 # Full VNC desktop session

# Storage
azlin storage create           # Create NFS storage
azlin storage mount            # Mount storage

# Monitoring
azlin health                   # VM health dashboard
azlin status                   # VM status
azlin w                        # Who is logged in
azlin top                      # Distributed metrics
azlin cost                     # Cost tracking

# Maintenance
azlin self-update              # Update azlin to latest version

Next: Learn core concepts or dive into VM lifecycle