# admin-wsl

> WSL2 Ubuntu administration from the Linux side. Profile-aware - reads preferences from
the shared Windows-side profile at /mnt/c/Users/{WIN_USER}/.admin/profiles/{hostname}.json.

Use when: apt packages, Docker containers, Python/uv in WSL, Node in WSL, shell configs
(.bashrc/.zshrc), systemd services in WSL, SSH from WSL to servers.

NOT for: .wslconfig changes (use admin-windows), Windows packages (use admin-windows),
native Linux/macOS (use admin-unix).

Keywords: wsl, wsl2, ubuntu, apt, docker, /mnt/c, wslpath, systemd wsl, python wsl, node wsl

- Author: Wes Odom
- Repository: evolv3-ai/vibeskills
- Version: 20260131171740
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/evolv3-ai/vibeskills
- Web: https://mule.run/skillshub/@@evolv3-ai/vibeskills~admin-wsl:20260131171740

---

---
name: admin-wsl
description: |
  WSL2 Ubuntu administration from the Linux side. Profile-aware - reads preferences from
  the shared Windows-side profile at /mnt/c/Users/{WIN_USER}/.admin/profiles/{hostname}.json.

  Use when: apt packages, Docker containers, Python/uv in WSL, Node in WSL, shell configs
  (.bashrc/.zshrc), systemd services in WSL, SSH from WSL to servers.

  NOT for: .wslconfig changes (use admin-windows), Windows packages (use admin-windows),
  native Linux/macOS (use admin-unix).

  Keywords: wsl, wsl2, ubuntu, apt, docker, /mnt/c, wslpath, systemd wsl, python wsl, node wsl
license: MIT
---

# 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.**

```bash
# 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

```bash
# 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

```bash
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

```bash
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)

```bash
sudo apt update
sudo apt install -y $package
```

---

## Path Conversions

Windows paths in profile need conversion for WSL:

```bash
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):

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

Or manually:

```bash
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

```bash
# 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

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

Then tell user to run in **Windows PowerShell**:
```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