WSL Administration

Requires: WSL2 context, Ubuntu 24.04

Navigation

Troubleshooting & known issues: references/OPERATIONS.md
Environment verification: scripts/verify-wsl-environment.sh

⚠️ Critical: Profile Location

The profile lives on the WINDOWS side, not in WSL home.

# WRONG - this doesn't exist in WSL
ls ~/.admin/profiles/  # Empty!

# RIGHT - profile is on Windows, accessed via /mnt/c
WIN_USER=$(cmd.exe /c "echo %USERNAME%" 2>/dev/null | tr -d '\r')
ADMIN_ROOT="/mnt/c/Users/$WIN_USER/.admin"
PROFILE_PATH="$ADMIN_ROOT/profiles/$(hostname).json"

Quick Start

# Verify environment first
bash scripts/verify-wsl-environment.sh

# Load profile
source /path/to/admin/scripts/load-profile.sh
load_admin_profile
show_admin_summary

Package Installation (Profile-Aware)

Python - Check Preference First

PY_MGR=$(jq -r '.preferences.python.manager' "$PROFILE_PATH")

case "$PY_MGR" in
    uv)     uv pip install "$package" ;;
    pip)    pip install "$package" ;;
    conda)  conda install "$package" ;;
esac

Node - Check Preference First

NODE_MGR=$(jq -r '.preferences.node.manager' "$PROFILE_PATH")

case "$NODE_MGR" in
    npm)    npm install "$package" ;;
    pnpm)   pnpm add "$package" ;;
    yarn)   yarn add "$package" ;;
    bun)    bun add "$package" ;;
esac

System Packages (apt)

sudo apt update
sudo apt install -y $package

Path Conversions

Windows paths in profile need conversion for WSL:

win_to_wsl() {
    local win_path="$1"
    local drive=$(echo "$win_path" | cut -c1 | tr '[:upper:]' '[:lower:]')
    local rest=$(echo "$win_path" | cut -c3- | sed 's|\\|/|g')
    echo "/mnt/$drive$rest"
}

# Usage
SSH_PATH=$(jq -r '.paths.sshKeys' "$PROFILE_PATH")
WSL_SSH_PATH=$(win_to_wsl "$SSH_PATH")

SSH to Servers

Use the loader helper (auto-converts paths):

source load-profile.sh
load_admin_profile
ssh_to_server "cool-two"

Or manually:

SERVER=$(jq '.servers[] | select(.id == "cool-two")' "$PROFILE_PATH")
HOST=$(echo "$SERVER" | jq -r '.host')
USER=$(echo "$SERVER" | jq -r '.username')
KEY=$(win_to_wsl "$(echo "$SERVER" | jq -r '.keyPath')")

ssh -i "$KEY" "$USER@$HOST"

Docker Operations

# Verify Docker working
docker info

# Common commands
docker ps                      # List running
docker logs <container>        # View logs
docker exec -it <c> bash       # Shell into container
docker-compose up -d           # Start compose stack

If Docker not working: Check Docker Desktop is running on Windows side with WSL integration enabled.

Handoffs to Windows

Some tasks cannot be done from WSL. Log a handoff and instruct user:

Example: Increase WSL Memory

# Log it
echo "[$(date -Iseconds)] HANDOFF: Need .wslconfig memory=24GB" \
    >> "$ADMIN_ROOT/logs/handoffs.log"

Then tell user to run in Windows PowerShell:

# Edit .wslconfig
notepad "$env:USERPROFILE\.wslconfig"
# Add: [wsl2] memory=24GB

# Restart WSL
wsl --shutdown

See references/OPERATIONS.md for more handoff examples.

Scope Boundaries

Task	Handle Here	Hand Off To
apt packages	✅	-
Docker containers	✅	-
Python/Node in WSL	✅	-
.bashrc/.zshrc	✅	-
systemd services	✅	-
SSH to servers	✅	-
.wslconfig	❌	admin-windows
Windows packages	❌	admin-windows
MCP servers	❌	admin-mcp
Native Linux (non-WSL)	❌	admin-unix

References

references/OPERATIONS.md - Known issues, troubleshooting, handoff examples, setup checklist

admin-wsl