limabean

README

limabean creates disposable Ubuntu dev VMs on your Mac from layered Lima templates. Each VM has a complete, version-pinned toolchain and your git identity. It pushes with your SSH keys without ever copying them in. Claude can drive it: through limabean's MCP server it creates VMs, runs code in them and snapshots them, and every VM appears in Claude Desktop as an SSH connection.

Docs: rossedman.github.io/limabean

• One command per VM. limabean new dev is ready in about a minute, and limabean up builds the VM a repository's .limabean.yaml describes.
• Batteries included, in packs. Docker, Go, Python, Node, Kubernetes, Terraform and 30+ CLI tools by default, every version pinned; add Rust, Java, Ruby and more with --with.
• Keys stay on your Mac. SSH keys stay in your agent, a scoped GitHub token lives in your Keychain, and your git and AWS config are mounted read-only.
• Secrets without files. API keys and tokens come from your Keychain, 1Password, environment variables or commands, chosen when you create a VM.
• Sandboxes for agents. Limit a VM to the domains its work needs (learn mode records them for you) and lock it, so nothing inside, an agent included, can turn that off.
• Claude drives it. With MCP, Claude creates VMs, clones repositories, runs builds and tests, and snapshots VMs, all without touching your Mac. Every VM is also an SSH connection in Claude Desktop.
• Safe to throw away. ~/code lives on its own disk, so rebuild keeps your repositories, and rm refuses to run while you have unpushed work. Clones take seconds, and --ttl or run --rm VMs delete themselves.
• Plain Lima underneath. Templates are ordinary YAML and shell, and limactl always works.

Quick start

brew install lima
go install github.com/rossedman/limabean/cmd/limabean@latest   # or download a release

limabean init       # save settings, fix ~/.ssh/config, check your setup

# optional: log VMs into GitHub for gh and the API (scoped tokens: docs/github.md)
gh auth token --hostname github.com | limabean github login --with-token

limabean new dev    # create a VM; a form asks which secrets it gets
limabean ssh dev    # or: ssh lima-dev

Prebuilt binaries for Apple Silicon and Intel are on the releases page.

Use it with Claude

Add limabean's MCP server to Claude Code:

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

Then ask:

Make a VM called scratch, clone owner/repo into it and get the tests passing.

Claude creates the VM, clones the repository, runs commands in it and can snapshot it before risky changes. For an agent that should only reach certain hosts, ask for a locked sandbox: "create a locked VM that can only reach github and python". Nothing runs on your Mac, Claude never sees secret values, and deleting or restoring VMs needs --allow-destructive.

Claude and MCP covers Claude Desktop, example prompts, every tool and the safety model.

How it works

Commands

Leave out a VM name and you pick one from a list. Every command has --help with examples, and the CLI reference has the details.

Setup

Command	What it does
limabean init	Set up: git config, code directory, SSH Include, GitHub token
limabean doctor	Check everything VMs depend on
limabean bump	Update the pinned tool versions in templates/packs/*.toml

VMs

Command	What it does
limabean new [name] [env]	Create a VM, choosing its secrets; --with rust adds a pack
limabean up	Create or start the VM a repository's .limabean.yaml describes
limabean run --rm -- <cmd>	Run one command in a new VM, then delete it
limabean packs	List the tool packs and which VMs get by default
limabean ls	List VMs, or print them as JSON with --json
limabean ssh [name] [cmd]	Open a shell or run a command, starting the VM if needed
limabean get [name] <repo>	Clone a repository into the VM with ghq
limabean cp <src> <dst>	Copy files between your Mac and a VM (dev:path)
limabean code [name] [repo]	Open the VM, or a repository in it, in VS Code or Cursor
limabean ports [name]	List the ports a VM forwards to your Mac
limabean open [name] [port]	Open a forwarded port in your browser
limabean start [name]	Start a stopped VM
limabean stop [name]	Stop a running VM, or with --idle 2h every VM nobody is using
limabean rebuild [name]	Recreate a VM from the current templates, keeping ~/code
limabean clone <name> <new>	Copy a VM, ~/code and all, in seconds
limabean rm [name]	Delete a VM
limabean snapshot save|ls|restore|rm	Save a VM, ~/code included, and roll back to it later
limabean autostop on|off|status	Stop idle VMs, and delete --ttl ones, in the background

Secrets and access

Command	What it does
limabean secrets ls	List secrets and where their values come from
limabean secrets set NAME [ref]	Add or change a secret (Keychain, 1Password, env var, command)
limabean secrets rm NAME	Remove a secret
limabean secrets edit	Edit a secrets file in your editor
limabean secrets sync	Install secrets in running VMs
limabean github login	Save a GitHub token for gh, the API and https pushes
limabean github status	Show the token's account and expiry, and which VMs have it
limabean github sync	Install the token in every running VM
limabean github logout	Remove the token from the Keychain and VMs
limabean network ls|allow|rm|open|lock|unlock	Limit which domains a VM can reach, and lock it so that holds
limabean network learn|log	Record what a VM reaches to build its allowlist, and see what was blocked
limabean claude sync	Register running VMs in Claude Desktop, remove the rest
limabean mcp	Let Claude create, run and snapshot VMs, as an MCP server (details)

More

Command	What it does
limabean completion <shell>	Print a completion script for bash, zsh, fish or PowerShell
limabean version	Print the version

Documentation

The full docs are at rossedman.github.io/limabean, built from the docs/ folder:

• Getting started: install, requirements, first VM
• Claude and MCP: let Claude create and drive VMs
• Claude Desktop: how VMs become SSH connections
• Sandboxes: network allowlists, learn mode and locked VMs
• Projects: .limabean.yaml and limabean up
• Rebuilds, clones and snapshots: throwaway VMs and autostop too
• Inside a VM: tools, Docker, shell, ports, paths
• Secrets: API keys and settings from the Keychain, 1Password and more
• GitHub access: a scoped token for gh, kept in your Keychain
• CLI reference: every command and setting
• Customizing: templates, adding tools and environments
• Troubleshooting
• Design notes and the Go CLI's design

Contributing

Issues and pull requests are welcome. CI runs go test, go vet, gofmt, shellcheck and limactl tmpl validate, and every pull request gets a snapshot build to try; see Customizing.

License

MIT

Documentation

Overview

Package limabean embeds the VM templates, so the limabean binary works on its own. See internal/templates for how they're written out for Lima.

Index

• Variables

Variables

var Templates embed.FS

Templates is the templates/ directory: Lima templates, provisioning scripts and the files they install.