https://lima-ai.readthedocs.io/
Run several Claude Code agents in parallel on a Mac, each in its own disposable Linux VM, each working on one workspace of your project: a branch, an experiment, a review.
REMARK: This project uses Lima Vms. This project isn't associated to Lima itself.
lima-ai new preludian/myapp feat-login → lima-dev-myapp-feat-login.local
lima-ai new preludian/myapp feat-billing → lima-dev-myapp-feat-billing.local
Every VM gets its own copy of the project, its own Docker daemon and its own
network address. The same docker compose app can run on the same port in
every VM at once, and you open each one by name from your Mac's browser.
Inside a VM the agent has full control: root, Docker, and claude --dangerously-skip-permissions with no permission prompts. It still cannot
write to your Mac's files, except for one backup folder.
How it works
lima-ai base builds one golden Ubuntu VM with Docker, Node, Rust, Claude
Code and the AWS CLI, then seals it. Anything else you want in every VM goes in a
hook script that lima-ai base --use-hook runs during the build. lima-ai new clones that base in
seconds, copies in your project, your Claude config, your git config and, if
you say yes, your AWS config, and gives the clone its own IP and mDNS name. Nothing is shared with your Mac except a read-only
mount of ~/Developer and one read-write backups folder, and no VM port is
forwarded to your Mac's localhost.
Documentation
The manual is at https://lima-ai.readthedocs.io/:
- Introduction: how it works, with diagrams, and what an agent in a VM can and cannot do
- Installation: requirements and install methods
- Quickstart: two workspaces of one project, side by side
- Everyday tasks: syncing, pausing, and what is copied into a VM
- Docker backups: the shared folder, and docker-backup from inside a VM
- Command reference: every command and flag, and how VMs are named
- Configuration:
config.tomland the files lima-ai keeps on your Mac - Troubleshooting
Requirements
- macOS on Apple Silicon
- Lima 2.0 or later:
brew install lima - Rosetta, for running
linux/amd64images:softwareupdate --install-rosetta --agree-to-license - Claude Code on the Mac, signed in with a Claude subscription (any plan)
- Optional: an SSH key loaded in
ssh-agent, togit pushfrom inside a VM - uv, to install lima-ai from PyPI or from source (not needed with Homebrew)
- Optional: docker-backup 0.4.0 or
later, to restore VM backups into the Mac's Colima:
brew install joepreludian/tap/docker-backup
Installation
From PyPI (recommended):
uv tool install lima-ai # or: pipx install lima-ai
With Homebrew (installs Lima too):
brew install joepreludian/tap/lima-ai
Or download a self-contained executable (macOS Apple Silicon, Linux x86_64 or
Linux arm64) from GitHub Releases
(the macOS one is unsigned; see the manual for the Gatekeeper step), or install from a checkout
with uv tool install . or make pex. The
Installation page covers
all of these.
Then, in order:
lima-ai doctor # what is still missing, with the fix for each
ssh-add -l || ssh-add ~/.ssh/id_ed25519 # optional: only to git push from inside a VM
lima-ai auth # once: store a Claude token
lima-ai base # once: build dev-base (5-10 minutes)
lima-ai new preludian/myapp feat-login # a workspace VM, then lima-ai shell to get in
The Quickstart walks through
these with two workspaces side by side. Upgrading from 0.12 or earlier? Run
lima-ai base --rebuild: VMs now mount the backups folder at /backups and
ship the AWS CLI.
Development
make test # unit tests; no VM or Lima install needed
make test-lima # end-to-end tests with real VMs (a few minutes; longer if dev-base must be built)
make lint # ruff check and format check
make pex # dist/lima-ai, a self-contained executable for this machine's platform
make test-lima builds dev-base if it is missing, creates
dev-limaaitest-* VMs from a small compose project, and deletes them when
it finishes. A dev-base built by lima-ai 0.11 or earlier fails the first test
with a message asking for lima-ai base --rebuild, since VMs now mount the
backups folder at /backups.
Metadata
Release files for lima-ai 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lima_ai-0.16.0.tar.gz | 57.3 kB | With provenance | Details for lima_ai-0.16.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lima_ai-0.16.0-py3-none-any.whl | Python 3 | none | any | Details for lima_ai-0.16.0-py3-none-any.whl |
Total release size: 125.9 kB
Release files / lima_ai-0.16.0.tar.gz
| Download URL | lima_ai-0.16.0.tar.gz |
|---|---|
| Size | 57.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cae68b956556134f19ba76fb0630354c40b7bc329c6e5ce498b1a17968c3a61e
|
|
BLAKE2b-256 checksum How to use checksums |
d66b00f5c68bf7465f73f9f5062361c734e82307ebdb569a83dd53a10bd83afb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / lima_ai-0.16.0-py3-none-any.whl
| Download URL | lima_ai-0.16.0-py3-none-any.whl |
|---|---|
| Size | 68.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
162eed66ddb61e591c32421492c877073b9dbf506a328d82fce36f6772fbdbfe
|
|
BLAKE2b-256 checksum How to use checksums |
e502eef69a5f0be4a217de34d6e9709b074c1d7147e0c992a7423cedc80bd32e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for lima-ai 0.16.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for lima_ai-0.16.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.