Skip to content
Fungi
Esc
↑↓navigate↵open⌘Jpreview
On this page
Use Fungi

Run Fungi in its own VM

Run Shiitake in a Lima Linux VM that mounts only your project folder. Use your Claude or ChatGPT subscription; stop and restart the VM with Lima.

Run Fungi in its own VM

Run Shiitake in a Lima Linux VM that mounts only your project folder. Use your Claude or ChatGPT subscription; stop and restart the VM with Lima.

Fungi publishes a Lima template that starts an Ubuntu 24.04 VM with Node.js 24 and Spore installed. Only the project folder you start it from is mounted. Inside the VM, fungi opens Shiitake in that folder.

The agent can change and run anything in this project folder and reach the internet. Your home folder, SSH keys and other projects are not mounted, and your SSH agent is not forwarded. Secrets inside the project, such as .env files, are visible to it. Logins you make inside the VM are stored on the VM’s disk. Code the agent writes runs on your computer when you run it there.

This is a separate Linux VM, not a network sandbox. The VM can reach the internet and your local network. Services listening only on your computer’s localhost (127.0.0.1) are blocked by a firewall rule inside the VM; the agent can run commands as root in the VM, so it could remove that rule. Services your computer offers on its network addresses stay reachable.

Before you start

  • macOS: Apple Silicon with macOS 13.5 or newer. Install Lima with brew install lima. Intel Macs are not tested.
  • Linux: x86_64 or arm64 with KVM. Install Lima and QEMU by following Lima’s installation guide. Your user needs read and write access to /dev/kvm.
  • Lima 2.0 or newer, about 4 GB of free disk for the first VM, and a Claude or ChatGPT subscription.

Windows is not supported.

Quick start with fungi vm

With Spore installed on your computer, one command creates the VM, starts it when it is stopped, and opens Shiitake inside it in this folder:

cd your-project
fungi vm

The first run prints the folder it mounts and the access notice above. Once per Spore version it prepares a stopped base VM, fungi-base-<id>, from the template below: it downloads Ubuntu and installs Node.js and the same Spore version as your computer, which takes about a minute. Each project’s VM, fungi-<folder>-<id>, is a Lima clone of that base with only the project mounted, so a new project’s VM is ready in about 15 seconds. The base uses about 2 GB of disk; remove it with limactl delete fungi-base-<id>. Every command fungi vm runs is printed first, so you can repeat it with limactl yourself, and Lima’s output goes to ~/.fungi/logs/.

  • fungi vm login shows what the VM is already signed in to, then signs in inside it. A Claude sign-in prints a link; approve it in your browser and paste the code back. While it runs, port 1455 on your computer is forwarded to the VM, so a ChatGPT browser sign-in finishes by itself.
  • fungi vm --yolo opens Shiitake in Full access mode inside the VM.
  • fungi vm --port 5173 forwards a port from the VM to the same port on your computer.
  • A new VM gets your Git user.name and user.email, so commits made inside it carry your name.
  • fungi vm stop stops the VM and keeps its disk.
  • fungi vm rm deletes a stopped VM and its disk after asking. Your project folder stays.

The rest of this page does the same steps with Lima directly.

1. Start the VM in your project folder

The template ships inside Spore. Open your project folder, then create and start a VM for it. Pick a short name of lowercase letters, numbers and dashes:

cd your-project
limactl start --name=fungi-your-project --mount-only="$PWD:w" \
  "$(npm root -g)/@fungi.computer/spore/dist/lima/fungi-vm.yaml"

--mount-only="$PWD:w" replaces every other mount with this folder, writable, at the same path inside the VM. Lima asks to confirm the template; press Enter to start it.

The first start downloads the Ubuntu image (about 620 MB) and then installs Node.js and Spore inside the VM (about 220 MB). It finishes when Lima prints READY. Measured first starts took one to one and a half minutes on a fast connection.

The VM gets 2 CPUs, 4 GiB of memory and a 20 GiB disk. Change them with --cpus, --memory and --disk when you create it.

2. Open Fungi inside the VM

From the same project folder, run:

limactl shell fungi-your-project fungi

Lima opens the shell at the same path, so Shiitake starts in your project. The VM has no saved logins, so sign in once:

  • Claude: run fungi login --provider anthropic --auth-type oauth in the VM, open the printed link in your browser, and paste the code back.
  • ChatGPT: run fungi login --provider openai --auth-type oauth in the VM and open the printed link. After you approve, the browser cannot reach the VM and shows an error page. Copy that page’s full address and paste it into the waiting fungi login.

Then ask for a first change, for example “create VM-CHECK.md containing hello from my local VM”. The file appears in the project folder on your computer.

To work in a shell first, run limactl shell fungi-your-project and start fungi from there. The agent can run commands as root inside the VM with sudo. Shiitake’s Workspace sandbox works inside the VM too.

3. Stop, restart and remove the VM

Lima owns the VM’s lifecycle:

limactl stop fungi-your-project    # Shut the VM down. Its disk is kept.
limactl start fungi-your-project   # Start it again, with the same mount.
limactl list                       # See your VMs and whether they run.

Stopping keeps the VM’s disk: installed tools, logins and Shiitake’s saved conversations are still there after a restart. Later starts take about ten seconds. Your project folder is never stored in the VM; it stays on your computer.

To remove the VM and its disk, stop it first:

limactl stop fungi-your-project
limactl delete fungi-your-project

Deleting the VM removes its disk, including logins and anything saved only inside the VM. It does not touch your project folder.

Ports and other limits

Ports opened inside the VM are not forwarded to your computer. To reach a development server, run fungi vm --port 5173 (repeat --port for more). A stopped VM gets the new port when it starts and keeps it; stop a running VM first. With limactl directly, create the VM with --port-forward=5173:5173.

Packages with native code must be installed inside the VM. A node_modules folder installed on macOS does not run in the Linux VM. File watching across the mount can be slower than on your computer.

The template pins Node.js by checksum and uses the Ubuntu image Lima’s release pins. fungi vm installs the same Spore version as your computer; run fungi update inside the VM to update it later. Read the template before you start it: it is dist/lima/fungi-vm.yaml in the installed Spore package.

Last updated on

Was this page helpful?