Skip to content

Getting started

Install

limabean needs macOS and Lima 2.0 or newer. It's a single binary with the VM templates built in.

With Homebrew (installs Lima too):

brew install rossedman/tap/limabean
brew upgrade limabean   # later, for a new release

The other ways need Lima first: brew install lima.

From a release. The download works on Apple Silicon and Intel:

# download limabean_<version>_darwin_universal.tar.gz from
# https://github.com/rossedman/limabean/releases, then:
tar -xzf limabean_*_darwin_universal.tar.gz limabean
xattr -d com.apple.quarantine limabean 2>/dev/null   # downloaded binaries are quarantined by macOS
mv limabean ~/.local/bin/                            # any directory on your PATH

With Go:

go install github.com/rossedman/limabean/cmd/limabean@latest

For tab completion in zsh: limabean completion zsh > "${fpath[1]}/_limabean". limabean completion --help covers other shells.

Set up

limabean init

init asks for the host directory that holds your git config and where repositories should go inside VMs. It saves both to ~/.config/limabean/config, offers to add the SSH Include described below, and then runs limabean doctor. Run limabean doctor any time to recheck everything.

Requirements

doctor checks each of these and prints the exact fix.

SSH config includes Lima's host entries

Lima writes an SSH config for each VM to ~/.lima/<name>/ssh.config and rewrites it on every start, because the forwarded port changes. Include those files so every VM is reachable as lima-<name>:

Include ~/.lima/*/ssh.config

The line must sit at the top of ~/.ssh/config, before any Host or Match block. An Include inside a block only applies to that block.

Your SSH key is loaded in the agent

VMs never receive a copy of your private keys. Lima forwards your Mac's ssh-agent instead, so git inside a VM can push as you while the key is loaded:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

To load it automatically after a reboot, add this below the Include line:

Host *
  AddKeysToAgent yes
  UseKeychain yes

With another agent, such as 1Password or Secretive, make sure SSH_AUTH_SOCK points at it in the shell where you run limabean up.

Your git config is in a directory

Lima mounts directories, not single files. Each VM mounts one host directory read-only at /mnt/host/git, and the VM's ~/.gitconfig includes the config found there. Edits on the Mac show up in every VM immediately.

Your setup What to do
~/.config/git/config (git's XDG location) Nothing, it's the default.
~/.gitconfig as a plain file mkdir -p ~/.config/git && mv ~/.gitconfig ~/.config/git/config. Git still finds it.
~/.gitconfig symlinked from a dotfiles repo Nothing. init follows the symlink and suggests that directory.

In that directory the VM looks for, first match wins:

  • config: config, .gitconfig
  • global ignore: ignore, .gitignore
  • commit template: .gitcommit.txt, commit-template.txt

Settings that only make sense on the Mac are overridden in the VM: core.editor becomes vim.

Your first VM

limabean up dev                       # a few minutes the first time; later VMs are copies of an image
limabean ssh dev ssh -T git@github.com # should greet you by your GitHub username
limabean get dev owner/repo            # clone into ~/code/github.com/owner/repo

In a terminal, up asks which packs the VM gets (Go, Node, Kubernetes, …) and which secrets; --with go,node answers the first question on the command line. The first VM of a kind provisions everything from scratch, and builds an image of itself in the background. Every later VM like it is a copy of that image, so it only has to boot.

For gh and the GitHub API inside VMs, add a scoped token once with limabean github login; see GitHub access.

Connect Claude

Every VM already shows up in Claude Desktop as an SSH connection: pick SSH → dev (limabean) in the prompt box's environment menu (details).

To let Claude manage VMs itself, add limabean's MCP server to Claude Code:

claude mcp add --scope user limabean -- limabean mcp

Then ask Claude to "make a VM, clone owner/repo and run the tests". Setup for Claude Desktop, example prompts and what Claude can and can't do are in Claude and MCP.

A VM for each project

Put a .limabean.yaml in a repository to describe the VM it needs (its packs, size, network, secrets and setup), and limabean up in the checkout creates it, clones the repository and sets it up:

# .limabean.yaml
packs: [rust]
ports: [3000]
setup: |
  make deps

To start from a recipe instead of a blank file:

limabean recipes                 # go-service, node-web, python-api, rails, claude-agent, …
limabean recipes go-service      # writes .limabean.yaml here; edit it, then limabean up

See Projects.

Next