UTM vm + claude code howto

utm-claude.md

Claude Code VM Setup on macOS with UTM (QEMU + Emulated VLAN)

This guide shows how to set up an isolated Ubuntu ARM server VM using UTM with QEMU emulation on macOS, configure SSH access via port forwarding, and install Claude Code and GitHub tools.

---

1. Install UTM

brew install --cask utm

---

2. Create Ubuntu ARM Server VM in UTM

1. Download Ubuntu Server (ARM64 ISO):
   Ubuntu Server ARM64 ISO
2. Open UTM → Create a New VM.
3. Do NOT use apple virtualization - we need Emulated VLAN mode to support Port Forwarding
4. Select the Ubuntu ARM64 ISO.
5. Configure resources:
   • CPU: 6–8 cores
   • Memory: 8–16 GB
   • Disk: 50–100 GB (virtio)
6. Network: Emulated VLAN (Shared).
7. Save and start VM to launch installer.

---

3. Install Ubuntu Server

Follow the installer prompts:

• Guided storage → use entire disk
• Set hostname, username, password
• Select Install OpenSSH server
• Complete install and reboot

---

4. Configure SSH Access (Port Forwarding)

1. Shut down the VM.
2. In UTM → Edit → Network → Emulated VLAN (Shared).
3. Add Port Forwarding rule:
   • Protocol: TCP
   • Host Address: leave blank
   • Host Port: 2222
   • Guest Address: leave blank
   • Guest Port: 22
4. Start VM.
5. From macOS terminal, connect:

ssh -p 2222 <username>@127.0.0.1

---

5. Update Ubuntu and Install Tools

Inside VM:

sudo apt update && sudo apt -y upgrade
sudo apt -y install build-essential curl git unzip ca-certificates ripgrep

---

6. Install Node.js with FNM

curl -fsSL https://fnm.vercel.app/install | bash
export PATH="$HOME/.local/share/fnm:$PATH"
eval "`fnm env`"

fnm install 20
fnm default 20
node -v
npm -v

---

7. Install Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude doctor

Set API key:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

---

8. Configure Git + GitHub

git config --global user.name  "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false

Generate SSH key:

ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub

Add the printed key to GitHub SSH keys.

Test:

ssh -T git@github.com

---

9. (Optional) GitHub CLI

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg |   sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" |   sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt -y install gh

gh auth login

---

10. Ready to Use

From macOS:

ssh -p 2222 <username>@127.0.0.1

Inside the VM, go to your project folder and run:

claude

You now have an isolated Ubuntu VM with Claude Code and GitHub access, running inside UTM on macOS.

Emulated VLAN mode for environments where Bridged networking doesn't work (some Wifi routers apparently block bridging)