lima-devbox

Lima Devbox Setup Skill

This skill guides users through creating a Lima VM configured for development work on macOS.

Prerequisites

• macOS with Homebrew installed
• Lima (brew install lima)

Workflow

Phase 1: Configuration Wizard

Use AskUserQuestion to gather configuration. Ask these in sequence:

Question 1: VM Name

• Header: "VM Name"
• Options: "devbox" (default), "sandbox", "test"
• Description: Name for your Lima VM (used in commands like limactl shell <name>)

Question 2: Resources

• Header: "Resources"
• Options:
  • "Standard (6 CPU, 8GB RAM, 100GB disk)" - Good for most development
  • "Light (4 CPU, 4GB RAM, 50GB disk)" - Lower resource usage
  • "Heavy (8 CPU, 16GB RAM, 200GB disk)" - For large projects or multiple services
• multiSelect: false

Question 3: Shared Directories

• Header: "Mounts"
• Options:
  • "Single directory" - Recommended, simple setup
  • "Multiple directories" - I'll ask for a comma-separated list
• Description: Only these directories will be accessible from the VM (read/write). The VM has no access to any other host files.

Question 3b: Ask for the directory path(s)

• If single directory selected: Ask "What directory should the VM have access to?" with options like "/github", "/projects", or let them type a custom path
• If multiple directories selected: Ask for comma-separated paths

Question 4: Git Configuration Ask for git user.name and user.email (can use AskUserQuestion with text input)

Question 5: Languages

• Header: "Languages"
• Options: "Node.js", "Go", "Rust", "Python"
• multiSelect: true
• Description: Languages to install via mise (version manager)

Question 6: Tools

• Header: "Tools"
• Options: "GitHub CLI (gh)", "Docker (nerdctl already included)"
• multiSelect: true
• Description: Optional tools. Note: nerdctl (docker-compatible CLI) is already installed by default - try it before installing Docker.

Question 6b: AI Coding Agents

• Header: "AI Agents"
• Options: "Claude Code (Anthropic)", "Gemini CLI (Google)", "Codex CLI (OpenAI)", "OpenCode", "None"
• multiSelect: true
• Description: AI coding assistants to install. All support autonomous/YOLO modes for hands-off operation in this sandboxed environment.

Question 7: SSH Password (Optional)

• Header: "SSH Password"
• Options: "No password (key-only)" (default), "Set a password"
• Description: Lima uses SSH keys by default. You can optionally set a password for convenience.

Question 7b (if password selected): Ask user to enter their desired password

Question 8: Port Forwarding

• Header: "Ports"
• Options: "8080", "3000", "5000", "5432 (PostgreSQL)", "6379 (Redis)", "None"
• multiSelect: true
• Description: Forward these ports from VM to host. Access VM services at localhost: on your Mac.

Question 9: SSH Agent Forwarding

• Header: "SSH Agent"
• Options: "Yes - forward SSH agent (Recommended)", "No"
• multiSelect: false
• Description: Allows the VM to use your Mac's SSH keys for git operations, etc.

Question 10: VM Type

• Header: "VM Type"
• First, detect macOS version. If macOS 13+, recommend "vz":
• Options: "vz (Virtualization.framework) - Recommended, faster" (default on macOS 13+), "qemu - More compatible, slower"
• multiSelect: false
• Description: "vz" uses Apple's native virtualization (faster, requires macOS 13+). "qemu" works on older macOS.

Question 11: Rosetta (Apple Silicon only)

• Skip this question on Intel Macs
• Header: "Rosetta"
• Options: "Yes - enable Rosetta (Recommended)", "No"
• multiSelect: false
• Description: Run x86_64 Linux binaries in the VM. Useful for compatibility with older tools. Requires vz VM type.

Phase 2: Setup Execution

After gathering configuration, create a todo list and execute each step:

Step 1: Install Lima (if needed)

limactl --version

If not installed, install it:

brew install lima

Step 2: Create VM

limactl start --name=<vm_name> --cpus=<cpus> --memory=<memory> --disk=<disk> -y

Wait for VM to be running:

limactl list --json | jq -r '.[] | select(.name=="<vm_name>") | .status'

Step 3: Configure VM Settings

Edit ~/.lima/<vm_name>/lima.yaml to apply user's configuration choices:

VM Type (if user selected vz):

vmType: "vz"

Rosetta (if enabled, requires vmType: vz):

rosetta:
  enabled: true

SSH Agent Forwarding (if enabled):

ssh:
  forwardAgent: true

Port Forwarding (for each selected port):

portForwards:
- guestPort: 8080
  hostPort: 8080
- guestPort: 3000
  hostPort: 3000

Mounts - configure ONLY the shared directories (no home directory access):

Find the mounts: section and replace it with:

mounts:
- location: "<writable_path>"
  writable: true

For multiple directories:

mounts:
- location: "~/github"
  writable: true
- location: "~/projects"
  writable: true

IMPORTANT: Do NOT include a location: "~" mount. Only the specified directories should be accessible.

Step 4: Full Stop/Start VM (required after mount changes)

IMPORTANT: Mount configuration changes (especially writable: true) require a full stop/start cycle to take effect. A simple limactl restart is NOT sufficient - you must explicitly stop and then start the VM.

limactl stop <vm_name>
limactl start <vm_name>

After restarting, verify the mount is writable by checking the mount flags:

limactl shell <vm_name> -- mount | grep <mount_path>

The output should show rw (read-write), not ro (read-only):

mount0 on /path/to/mount type virtiofs (rw,relatime)

If it still shows ro, stop and start again.

Step 5: Setup SSH Config Symlink

mkdir -p ~/.ssh/config.d
ln -sf ~/.lima/<vm_name>/ssh.config ~/.ssh/config.d/<vm_name>

Ensure ~/.ssh/config includes:

Include config.d/*

After this, user can SSH with: ssh <vm_name>

SSH Authentication Note: Lima uses key-based authentication by default:

• Creates a private key at ~/.lima/_config/user
• Sets up the VM user with your macOS username
• Configures all SSH settings in the symlinked config file
• Password authentication is optional (configured in Step 7 if requested)

Step 6: Run Base Setup Script

Copy and execute scripts/setup-vm.sh in the VM:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/setup-vm.sh)" -- "<git_name>" "<git_email>" "<working_dir>"

Where <working_dir> is the first (or primary) mounted directory path. This will be the default directory when the user shells into the VM.

This installs system packages, configures git, sets up .bash_profile for SSH sessions, and configures the shell to start in the shared directory.

Step 7: Set SSH Password (if requested)

If user chose to set a password:

limactl shell <vm_name> -- bash -c "echo '<username>:<password>' | sudo chpasswd"

Where <username> is the user's macOS username (same as VM user).

Step 8: Install Languages (if selected)

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-mise.sh)" -- <languages>

Where <languages> is a space-separated list like nodejs go rust python.

Step 9: Install Optional Tools

For GitHub CLI:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-gh.sh)"

For Docker (if user specifically wants Docker instead of nerdctl):

limactl shell <vm_name> -- bash -c "curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker \$USER"

Note: nerdctl is already available (nerdctl run, nerdctl build, etc.) and is docker-compatible. Most users won't need Docker.

Step 10: Install AI Coding Agents (if selected)

For Claude Code:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-ai-agent.sh)" -- claude

For Gemini CLI:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-ai-agent.sh)" -- gemini

For Codex CLI:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-ai-agent.sh)" -- codex

For OpenCode:

limactl shell <vm_name> -- bash -c "$(cat <skill_path>/scripts/install-ai-agent.sh)" -- opencode

All agents are configured with aliases for autonomous/YOLO mode operation.

Step 11: Verify Setup

limactl shell <vm_name> -- bash -c "echo 'VM is ready!' && git --version && mise --version"

Step 12: Final Restart (ensures mount permissions are correct)

Stop and restart the VM to ensure shared directory permissions are properly applied:

limactl stop <vm_name>
limactl start <vm_name>

Wait for the VM to be running before presenting the summary to the user.

Phase 3: Post-Setup Summary

After successful setup, provide the user with:

1. Access commands:

   • limactl shell <vm_name> - Interactive shell (starts in shared directory)
   • ssh <vm_name> - SSH access (if config symlink created)
   • exit or Ctrl+D - Exit the VM shell and return to Mac terminal

2. Common Lima commands:

   • limactl stop <vm_name> - Stop the VM
   • limactl start <vm_name> - Start the VM
   • limactl restart <vm_name> - Restart the VM
   • limactl delete <vm_name> -f - Delete the VM

3. Working with files:

   • Only files in configured directories (e.g., ~/github) are accessible from the VM
   • Files are available at the same path in the VM
   • Changes sync bidirectionally between host and VM

4. Container tools:

   • nerdctl is pre-installed (docker-compatible commands)
   • Example: nerdctl run -it ubuntu bash

5. Port forwarding (if configured):

   • Forwarded ports are accessible at localhost:<port> on your Mac
   • Example: A server running on port 8080 in the VM is available at localhost:8080

6. SSH agent (if enabled):

   • Your Mac's SSH keys are available inside the VM
   • Git operations using SSH will work without additional configuration

7. Reference: Point to references/lima-commands.md for full command reference

Script Locations

Scripts are located in scripts/ relative to this skill:

• setup-vm.sh - Base system setup (packages, git config, bash_profile, default working directory)
• install-mise.sh - Mise installation and language setup
• install-gh.sh - GitHub CLI installation
• install-ai-agent.sh - AI coding agent installation (Claude Code, Gemini CLI, Codex CLI, OpenCode)

Error Handling

• If Lima not installed: Guide user to brew install lima
• If VM creation fails: Check Lima logs with limactl logs <vm_name>
• If script fails: Can re-run individual scripts after SSH into VM
• If mounts are read-only: This is a common issue. Mount changes require a full limactl stop followed by limactl start (not just restart). Verify with mount | grep <path> - look for rw not ro
• If mounts don't work: Verify lima.yaml syntax, then do a full stop/start cycle

Notes

• Default Lima template uses Ubuntu 24.04 LTS
• Only explicitly configured directories are mounted (VM has no access to other host files)
• nerdctl (containerd CLI) is included by default for container operations