Skip to main content
lima-ai

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/:

Requirements

  • macOS on Apple Silicon
  • Lima 2.0 or later: brew install lima
  • Rosetta, for running linux/amd64 images: 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, to git push from 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)

Source distribution for lima-ai 0.16.0
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)

Table of built distributions (wheels) for lima-ai 0.16.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page