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, and appears in Claude Desktop as an SSH connection.

• One command per VM. limabean new dev is ready in about a minute.
• Batteries included. Docker Engine, Go, Python, Kubernetes tooling, Terraform and 30+ CLI tools, pinned with mise.
• 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.
• Built for Claude. Every VM is registered as an SSH connection in Claude Desktop.
• Safe to throw away. rm and rebuild refuse to run while you have unpushed work.
• 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.

How it works

Commands

Command	What it does
limabean init / doctor	Set up, and check prerequisites
limabean new [name] [env]	Create a VM, choosing its secrets
limabean ls	List VMs
limabean ssh <name> [cmd]	Open a shell or run a command
limabean get <name> <repo>	Clone a repository into the VM with ghq
limabean rebuild <name>	Recreate from the current templates
limabean stop / rm <name>	Stop or delete a VM
limabean secrets set NAME [ref]	Give VMs an API key or setting
limabean github login	Give VMs a GitHub token for gh and the API
limabean claude sync	Sync VMs with Claude Desktop

Documentation

• Getting started: install, requirements, first VM
• CLI reference: commands, settings, unsaved-work protection
• Inside a VM: tools, Docker, shell, paths, updates
• Secrets: API keys and settings from the Keychain, 1Password and more
• GitHub access: a scoped token for gh, kept in your Keychain
• Claude Desktop: how VMs become SSH connections
• 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.