59 lines
6.5 KiB
Markdown
Executable File
59 lines
6.5 KiB
Markdown
Executable File
---
|
||
title: Virfield
|
||
namespace: personal
|
||
updated: '2026-09-30'
|
||
status: released
|
||
tags: [virfield, macos, vm, go, infrastructure]
|
||
---
|
||
# Virfield
|
||
|
||
**Релиз:** [v2.0.0](https://github.com/mallexxx/virfield/releases/tag/v2.0.0), опубликован 2026-09-30; commit `ee3aa1d8f5906bfe591d76c0af2afd73bcad9fba`.
|
||
**Репозиторий:** [mallexxx/virfield](https://github.com/mallexxx/virfield). В `main` только Go-реализация; предыдущая реализация сохранена исключительно в Git-ветке `v1`.
|
||
|
||
## Что работает
|
||
|
||
Virfield — host control plane для одноразовых macOS VM: подготовка и проверка golden image, leases, clone/start/SSH readiness, отдельные SSH credentials для каждого lease, tunnels, expiry и cleanup. Лимит — не более двух VM с явным `capacity_exhausted`; очередь выполнения принадлежит Broker.
|
||
|
||
Четыре бинарника: `virfieldd`, `virfield`, `virfield-mcp`, `virfield-lume`. Web console встроена в daemon. CLI, stdio/HTTP MCP и UI обращаются к единому аутентифицированному API. Произвольного shell API и доступа к личным SSH-ключам нет.
|
||
|
||
## Источники истины
|
||
|
||
Obsidian хранит статус проекта и связи. Команды, конфигурацию и контракты поддерживаем в документации репозитория, без копирования runbook в заметки.
|
||
|
||
| Документ | Назначение |
|
||
|---|---|
|
||
| [README](https://github.com/mallexxx/virfield/blob/main/README.md) | Входная точка, структура и сборка |
|
||
| [Operations](https://github.com/mallexxx/virfield/blob/main/docs/OPERATIONS.md) | Установка, пути, сервисы, MCP, leases и backup |
|
||
| [Image pipeline](https://github.com/mallexxx/virfield/blob/main/docs/IMAGE-PIPELINE.md) | Golden image, зависимости, guest policy и recovery |
|
||
| [Architecture](https://github.com/mallexxx/virfield/blob/main/docs/ARCHITECTURE.md) | Модули, границы API и инварианты |
|
||
| [Verification](https://github.com/mallexxx/virfield/blob/main/docs/VERIFICATION.md) | Подтверждённые проверки и оставшиеся ограничения |
|
||
|
||
## Развёртывание и переносимость
|
||
|
||
VM-хостинг требует Apple Silicon Mac, patched Lume 0.5.3 и документированных image tools. Поддерживаемый guest — macOS 27 build `26A428`; полный профиль `uitest-27-v1` требует Xcode 27+. Суффикс recipe и `/api/v1` обозначают версии контрактов, а не старое приложение.
|
||
|
||
Каталог deployment задаётся оператором вне checkout. `deploy/prepare-services.py` берёт реального пользователя, HOME, пути и порты из конфигурации; токены не встраиваются в MCP-файлы. По умолчанию console/API — `127.0.0.1:7780`, Lume — `127.0.0.1:7777`; удалённое/container подключение требует отдельного TLS/routing setup.
|
||
|
||
На текущем Mac deployment расположен в `~/.virfield-v2`, VM-диски — в `~/.lume`. Это выбранные локальные пути, не требования к другой установке. System LaunchDaemons `ai.virfield.virfieldd` и `ai.virfield.lume` работают от владельца VM. По проверенному `release.json` установленный runtime остаётся на `44a1c15`; публикация `v2.0.0` сама по себе не обновляла сервис. Установку/обновление выполняем по Operations, не из каталога исходников.
|
||
|
||
## Проверено и что остаётся
|
||
|
||
[GitHub Actions Linux/macOS](https://github.com/mallexxx/virfield/actions/runs/36675247578) прошёл для релизного коммита. Подтверждены сборка с пустыми HOME/Go caches, deployment smoke с другими путями/портами, проверки зависимостей, секретов всей истории и релизного архива. Архив содержит четыре бинарника, source/docs, dependency notices и checksums; бинарники ad-hoc signed, без Apple notarization.
|
||
|
||
На одном физическом Mac пройдены реальный IPSW download/resume, полный golden build с Assistant/Recovery/SIP/provisioning, два изолированных clone, отказ третьему, SSH/tunnels и cleanup. Второй физический хост, длительный soak, оставшиеся crash points и восстановление VM-дисков пока не приняты. Проверки snapshot не заменяют VM-disk disaster recovery.
|
||
|
||
## Pitfalls
|
||
|
||
- `acquire` принимает job; работать по SSH можно только после lease `ready`.
|
||
- Running external VM и незавершённый cleanup занимают capacity; освобождать слот ручным редактированием SQLite нельзя.
|
||
- Неизвестный результат мутации требует inspection/recovery; повторный start/clone/delete вслепую недопустим.
|
||
- `release` удаляет disposable VM: результаты нужно выгрузить заранее.
|
||
- State backup не содержит VM-диски и IPSW cache; восстановление дисков проверяется отдельно.
|
||
|
||
## Связь с другими проектами
|
||
|
||
Целевая цепочка: `Balda → Execution Broker → Virfield → VM → Runner/Callee`. Virfield владеет VM, Broker — очередью и run lifecycle, Runner/Callee — выполнением внутри VM. Полный сценарий из Balda не подтверждён релизом Virfield; состояние остальных проектов проверяется отдельно.
|
||
|
||
- [[personal/plans/balda-callee-prism-plan]] — целевая интеграция и оставшаяся приёмка.
|
||
- [[work/wiki/apple-browsers/vm-ui-testing]] — применение VM leases для UI-тестов.
|