570395c4ac
Introduce make lint-shell / fmt-shell with shellcheck and shfmt (-i 2 -ci -bn), normalize first-party scripts, and document the new targets. Keep them out of make lint / fmt. Signed-off-by: Ludovic Vielle <ludovic@probo.com>
Lima Sandbox Environments
Run isolated dev environments using Lima VMs. Each git worktree gets its own VM with Docker, standard ports, and a unique IP — no port conflicts between sandboxes.
Prerequisites
brew install lima jq
Quickstart
# Create and start a sandbox for the current worktree
./contrib/lima/sandbox.sh create
# Check status and get the VM IP
./contrib/lima/sandbox.sh status
# Build the backend binary (probo-stack starts automatically on boot)
./contrib/lima/sandbox.sh exec -- make build
# Start probod, the console, and the compliance-portal dev servers
./contrib/lima/sandbox.sh exec -- sudo systemctl start probod probo-console probo-compliance-portal
# Access services from your host browser using the VM IP
# e.g. http://192.168.105.2:5173 (console)
# e.g. http://192.168.105.2:5174 (compliance-portal)
# e.g. http://192.168.105.2:8080 (API)
Commands
| Command | Description |
|---|---|
./contrib/lima/sandbox.sh create [--cpus C] [--memory M] [--disk D] |
Create and start a new VM |
./contrib/lima/sandbox.sh start |
Start a stopped VM |
./contrib/lima/sandbox.sh stop |
Shut down the VM (preserves disk and Docker images) |
./contrib/lima/sandbox.sh restart |
Stop + start |
./contrib/lima/sandbox.sh delete |
Remove the VM entirely |
./contrib/lima/sandbox.sh ssh |
Interactive shell at /workspace |
./contrib/lima/sandbox.sh exec -- CMD |
Run a command in the VM |
./contrib/lima/sandbox.sh status |
Show VM state, IP, and service URLs |
./contrib/lima/sandbox.sh list |
List all probo-* VMs |
Architecture
Host (macOS)
├── worktree: ~/Developer/probo/delhi → VM "probo-delhi" (192.168.105.x)
├── worktree: ~/Developer/probo/feature-a → VM "probo-feature-a" (192.168.105.y)
└── worktree: ~/Developer/probo/feature-b → VM "probo-feature-b" (192.168.105.z)
Each VM:
- Mounts the worktree at
/workspacevia virtiofs (read-write) - Runs Docker + docker-compose inside the VM
- Forwards the host SSH agent
- Gets its own IP via vzNAT — all services on standard ports
Makefile targets
Convenience wrappers are available:
make sandbox-create
make sandbox-start
make sandbox-stop
make sandbox-delete
make sandbox-ssh
make sandbox-status
Troubleshooting
VM won't start: Check limactl list for stale entries. Delete with
./contrib/lima/sandbox.sh delete and recreate.
Slow file I/O: The worktree is mounted via virtiofs which is fast for most
operations. If node_modules is slow, consider symlinking it to VM-local disk.
Docker permission denied: The provision script adds the lima user to the
docker group. If you see permission errors, restart the VM with
./contrib/lima/sandbox.sh restart.
Can't reach VM IP from host: Ensure vzNAT networking is working. Run
./contrib/lima/sandbox.sh status to verify the IP is assigned.