ua-dev VM · Understand-Anything on Lima · Ports: 5173 (Dashboard), 8080 (Control API), 3000 (MCP)
# Start / Stop
limactl start ua-dev # boot VM (~10 min first time, ~1 min after)
limactl stop ua-dev # shutdown VM (frees 8GB RAM)
limactl restart ua-dev # restart with latest lima.yaml config
limactl ls ua-dev # check VM status (Running/Stopped)
# SSH into VM
limactl shell ua-dev # interactive shell
limactl shell ua-dev -- <command> # run single command
# Service management
sudo systemctl status ua-dashboard # dashboard (Vite, :5173)
sudo systemctl status ua-control # control API (Express, :8080)
sudo systemctl restart ua-dashboard # new token on restart
# Logs
sudo journalctl -u ua-dashboard --no-pager -n 50
sudo journalctl -u ua-control --no-pager -n 50
From macOS:
limactl shell ua-dev -- sudo journalctl -u ua-dashboard --no-pager | \
grep -o 'http://127.0.0.1:5173/?token=[a-f0-9]*' | tail -1
From inside VM:
sudo journalctl -u ua-dashboard --no-pager | \
grep -o 'http://127.0.0.1:5173/?token=[a-f0-9]*' | tail -1
For scripts:
TOKEN=$(limactl shell ua-dev -- sudo journalctl -u ua-dashboard --no-pager | \
grep -oP 'token=[a-f0-9]+' | tail -1 | cut -d= -f2)
echo "http://localhost:5173/?token=$TOKEN"
open $(limactl shell ua-dev -- sudo journalctl -u ua-dashboard --no-pager | \
grep -o 'http://127.0.0.1:5173/?token=[a-f0-9]*' | tail -1)
Rebuilds the graph from scratch using tree-sitter static analysis. Produces file, function, and class nodes with import edges and directory-based layers.
From macOS:
limactl shell ua-dev -- sudo /opt/ua-data/scripts/rebuild-graph.sh
# Custom target: limactl shell ua-dev -- sudo /opt/ua-data/scripts/rebuild-graph.sh /mnt/repo 500
From inside VM (alias):
# Alias currently not set — run directly:
sudo /opt/ua-data/scripts/rebuild-graph.sh
Adds semantic summaries, tags, layer refinement, and guided tour via PVYai API.
From macOS:
limactl shell ua-dev -- sudo bash -c '
export PVYAI_BASE_URL="https://ai-api.pvy.swiss/api"
export PVYAI_API_KEY="sk-cbeae5acd4c635c7cdc261a9697e6b543cb30332339afa28"
export PVYAI_MODEL="pvy-coder-qw36-deep"
export PYTHONUNBUFFERED=1
python3 -u /opt/ua-data/scripts/enrich.py
'
From inside VM (alias):
ua-enrich # full enrichment (summaries + layers + tour)
ua-enrich-dry # validate pipeline without API calls
Maps git changes to graph nodes and shows impact propagation (2 levels deep via imports).
From macOS:
# Unstaged changes:
limactl shell ua-dev -- sudo python3 /opt/ua-data/scripts/build-diff.py
# Specific commit range:
limactl shell ua-dev -- sudo python3 /opt/ua-data/scripts/build-diff.py --since HEAD~3 --until HEAD
From inside VM (alias):
ua-diff # current uncommitted changes
ua-diff --since HEAD~5 --until HEAD # specific range
Groups nodes into business domains (heuristic clustering) and identifies entry points.
From macOS:
# Heuristic (fast, no API):
limactl shell ua-dev -- sudo python3 /opt/ua-data/scripts/build-domain.py
# LLM-named domains (requires API):
limactl shell ua-dev -- sudo python3 /opt/ua-data/scripts/build-domain.py --llm
From inside VM (alias):
ua-domain # heuristic domain graph (fast)
ua-domain-llm # LLM-named domains (requires API)
All endpoints are accessible from the macOS host via Lima port forwarding.
# Health check
curl http://localhost:8080/health
# Graph stats (nodes, edges, layers, project info)
curl http://localhost:8080/status
# Trigger analysis on mounted repo
curl -X POST http://localhost:8080/analyze
# Fuzzy search
curl "http://localhost:8080/search?q=authentication&limit=20" | jq
# Symbol details + relations
curl "http://localhost:8080/symbol/createUser" | jq
# Dependency graph (incoming + outgoing)
curl "http://localhost:8080/deps/DatabaseService?direction=both" | jq
# Switch repo (git clone)
curl -X POST http://localhost:8080/switch-repo \
-H "Content-Type: application/json" \
-d '{"url": "https://github.com/user/repo.git"}'
# All commands in one block for agent onboarding:
TOKEN=$(limactl shell ua-dev -- sudo journalctl -u ua-dashboard --no-pager | \
grep -oP 'token=[a-f0-9]+' | tail -1 | cut -d= -f2)
# Quick status
curl -s http://localhost:8080/status | jq '{ready, totalNodes, totalEdges, layers: (.layers|length)}'
# Search for a concept
curl -s "http://localhost:8080/search?q=<query>&limit=10" | jq '.results[] | {name, type, path, summary}'
# Get symbol full context
curl -s "http://localhost:8080/symbol/<name>" | jq '{node: {name, type, summary}, edges: (.relatedEdges|length)}'
# Trace dependency chain
curl -s "http://localhost:8080/deps/<name>?direction=outgoing" | jq '.outgoing[] | {target, type}'
# Check VM is alive
limactl ls ua-dev | grep Running
http://localhost:5173/?token=<token>
Toggle: Diff button in the top toolbar (enabled when changes detected)
Trigger: run ua-diff to populate diff-overlay.json, then click Diff toggle in UI.
View: Domain graph view in the UI (when domain-graph.json exists)
Trigger: run ua-domain, then the Domain view activates in the UI.
View: Tour tab in the main graph view (when tour steps exist)
Trigger: run ua-enrich (Phase C generates the tour).
~/.lima/ua-dev/lima.yaml — change the repo mount:mounts:
- location: /Volumes/Data/Repos/new-project
mountPoint: /mnt/repo
writable: true
limactl restart ua-devlimactl shell ua-dev -- sudo /opt/ua-data/scripts/rebuild-graph.sh /mnt/repo 500ua-enrichcurl -X POST http://localhost:8080/switch-repo \
-H "Content-Type: application/json" \
-d '{"url": "https://github.com/user/repo.git"}'
limactl ls ua-dev # is VM running?
curl -sI http://localhost:5173 # should return HTTP 200
limactl shell ua-dev -- sudo systemctl status ua-dashboard
curl http://localhost:8080/status # check if graph exists
# Rebuild if needed:
limactl shell ua-dev -- sudo /opt/ua-data/scripts/rebuild-graph.sh
Graph lives at /mnt/repo/.ua/ — ensures file paths resolve correctly. If not:
limactl shell ua-dev -- sudo bash -c '
cp /opt/ua-data/.ua/knowledge-graph.json /mnt/repo/.ua/ 2>/dev/null || echo "Run rebuild first"
'
# Test API:
curl -k -s -m 15 -X POST "https://ai-api.pvy.swiss/api/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-cbeae5acd4c635c7cdc261a9697e6b543cb30332339afa28" \
-d '{"model":"pvy-coder-qw36-deep","messages":[{"role":"user","content":"OK"}],"max_tokens":3}'
# Should return JSON within 15 seconds
limactl shell ua-dev -- sudo bash -c '
cd /opt/understand-anything
rm -rf node_modules pnpm-lock.yaml
pnpm install --no-frozen-lockfile
systemctl restart ua-dashboard
'
| Description | VM Path | Host Path |
|---|---|---|
| Knowledge graph | /mnt/repo/.ua/knowledge-graph.json |
(within repo mount) |
| Diff overlay | /mnt/repo/.ua/diff-overlay.json |
(within repo mount) |
| Domain graph | /mnt/repo/.ua/domain-graph.json |
(within repo mount) |
| Pipeline scripts | /opt/ua-data/scripts/ |
~/.lima/ua-dev/data/scripts/ |
| Enrichment logs | /opt/ua-data/enrich-deep.log |
~/.lima/ua-dev/data/enrich-deep.log |
| UA source | /opt/understand-anything/ |
(provisioned, not persistent) |
| lima.yaml | (N/A) | ~/.lima/ua-dev/lima.yaml |
| Dashboard log | journalctl -u ua-dashboard |
(journal) |
| Control API log | journalctl -u ua-control |
(journal) |
ua-dashboard # restart dashboard service
ua-dashboard-stop # stop dashboard
ua-enrich # full LLM enrichment (PVYai)
ua-enrich-dry # validate enrichment pipeline
ua-diff # build change impact overlay
ua-domain # build domain graph (heuristic)
ua-domain-llm # build domain graph (LLM-named)
ua-status # graph stats (API call)
ua-search <query> # search graph
ua-logs # view service logs
Certain tasks, based on allocated CPU and RAM, such as “ua-enrich” and “ua-domain-llm” can take on larger Repositories up to 20 Minutes. There is a setting for PVYmessenger in the lima.conf called “PVYmessenger Notifications” where you can “paste” a new “webhook-url” from a PVYmessenger Channel you administrate. If task, scan, re-index is finished, you will get a Notification to your PVYmessenger, also if something failed.
Provided by PVY.swiss for General Public Usuage, MIT Licece applies for Code.