Mac 运行时参考

barn [--json|--yaml] [-v|--verbose] mac <command> [flags] [name...]

运行 macOS 客机需要搭载 Apple 芯片且运行 macOS 27 或更高版本的 Mac，并由当前登录桌面用户直接调用。需要调用原生 runner 的命令会以 mac_root 拒绝 root 身份，并以 mac_host_unsupported 拒绝不满足要求的宿主。在 Linux 与 Intel Mac 上，顶层 --help 默认隐藏 mac 命令；而 barn mac image ls 等只读取本地记录的子命令则无需启动原生 runner。不带子命令直接运行 barn mac 等同于 barn mac ls。

本参考说明 Barn 1.2.0 的命令接口与 Barn.app（macOS 宿主上运行虚拟机的原生应用包，runner 协议版本 2）。Apple Silicon 发行包与 Homebrew 安装已包含 App，安装步骤见 macOS 客机指南。

各子命令的完整语法、选项和示例见 macOS 命令参考。本页集中说明机器规则、网络、结果格式和状态文件。

命令

SSH 与 exec

-- 之前除 Barn 参数外，最多接受一个已存在的虚拟机名（省略名称时自动选择唯一虚拟机或 mac1）。ssh 不带命令时打开交互式终端；exec 必须在 -- 后提供非空命令。未知的机器名或语法错误会在发起连接前直接返回退出码 2（usage），并提示运行 barn mac ls 查看现有机器。

ssh 会将 -- 后的参数用空格拼接成命令行交给客机 shell；exec 则将程序名和各个参数分别传入，完整保留空格、引号及后续空字符串参数。需要管道、重定向、变量展开或串行执行多条命令时，请显式使用 sh -c '...'。--json、-v、--help 等 Barn 参数必须放在 -- 前，其后的所有参数（包括第二个 --）都归属客机命令。

为保持兼容，exec 也接受单个命令字符串作为 shell 简写。新脚本请分开传入参数或显式使用 sh -c，明确是否需要 shell 解释。

barn mac ssh dev
barn mac ssh dev -- 'sw_vers; id'
barn mac exec dev -- sw_vers
barn mac exec dev -- printf '<%s>\n' 'a b' ''
barn mac exec dev -- sh -c 'sw_vers; id'
barn --json mac exec dev -- sh -c 'echo out; exit 3'

各命令的参数

对于名称可省略的命令，不传名称时会选中唯一的虚拟机或 mac1；若存在多台虚拟机且没有 mac1，命令会提示你显式指定名称。start 与 stop 支持传入多个名称或 --all。在终端中，destroy 与 recreate 会先列出即将删除的内容，并要求输入命令名称确认；--yes（或 --force）可跳过询问，没有终端时必须传入。这两条命令的 --yes 没有 -y 简写；mac stop --force 表示立即断电。

--no-wait 会在虚拟机进程启动后立即返回；对于新建虚拟机，后续仍需运行一次不带 --no-wait 的 barn mac up NAME 以完成 SSH 密钥写入与 sudo 配置。普通 start 要求虚拟机已完成首次启动——若未完成首次启动的虚拟机已在运行，可执行 barn mac open NAME 查看首次启动画面；若已停止，则执行 barn mac up NAME --open。传入 --recovery 会跳过常规就绪等待，直接启动进入 macOS 恢复模式桌面。

参数取值

对已存在的虚拟机运行 up 时，若传入的创建参数与现有设置不一致，up 会以 mac_configuration_conflict 拒绝执行，并在 next: 行给出对应的 configure 或 recreate 命令：

• 在虚拟机停止状态下使用 barn mac configure 修改 --cpu、--memory、--share/--unshare、--subnet 或 --clipboard（剪贴板配置也可在运行时修改并保存到下次启动生效；当前会话可通过菜单栏图标即时开关剪贴板同步）。共享名称支持空格与中文，须为 1–255 字节的有效 UTF-8，不能是 .、..，也不能包含 / 或 ASCII 控制字符；configure --share 复用已有名称时会更新其路径与读写属性，--unshare 则按名称移除对应共享。
• 管理员账号（--user）与磁盘容量（--disk）在虚拟机整个生命周期内固定不变，recreate 也会保留它们；如需更改账号或磁盘大小，请创建一台新虚拟机。
• 升级虚拟机的 macOS 版本时，先运行 barn mac image update，再执行 barn mac recreate NAME --update。由于 recreate --update 会保留原虚拟机的磁盘容量，若新 macOS 版本下还没有对应自定义容量（如 200G）的基础镜像，请先执行 barn mac setup --disk 200G 准备好该容量的基础镜像。

机器规则

• 名称：1–32 个字符，以小写字母开头，仅含小写字母、数字与中间连字符（例如 mac1、dev、build-2）。
• 单机两台并发上限：受 Apple Virtualization 框架限制，每台 Mac 最多同时运行两台 macOS 虚拟机（跨所有虚拟化应用以及正在执行的 .ipsw 基础镜像安装任务统一计数）。Barn 绝不会为了腾出名额而停止已有虚拟机。ls.running 统计当前 BARN_HOME 内的活跃虚拟机数，宿主全局上限则由 Apple 运行时强制执行。
• 管理员账号：默认配置免密 sudo、Ed25519 SSH 密钥登录、桌面自动登录与“远程登录”（SSH 服务），并关闭 SSH 密码认证；随机生成的本地登录密码保存在虚拟机槽位目录的 password 文件中（权限 0600）。
• 主机名：客机电脑名称（ComputerName）与虚拟机名 <name> 一致，本地主机名（LocalHostName）设为 barn-<name>（可通过 barn-<name>.local 访问）。
• 目录共享：客机内通过单个 VirtioFS 设备挂载到 /Volumes/My Shared Files/<name>。宿主源须解析为已存在的目录，支持符号链接；名称支持空格与中文。
• 剪贴板同步：每当虚拟机桌面窗口获得或失去焦点时，Barn 通过该虚拟机的 SSH 连接双向同步不超过 1 MiB 的纯文本，并自动跳过标记为敏感（concealed）的剪贴板条目。
• 关机行为：barn mac stop 会向客机发送正常关机请求，等待满两分钟仍未退出则强制断电（返回 "forced": true）；传入 --force 则立即断电。

网络

每台虚拟机的 runner 进程在启动时通过 Apple 的共享模式 vmnet API 创建独立的用户态网络，并在退出时自动销毁，全程无需守护进程或 root 权限：

如果宿主新增的路由（如 VPN 路由）占用了虚拟机已保存的网段，start 会以 mac_subnet_in_use 拒绝启动；此时执行 barn mac configure NAME --subnet auto 即可改换到空闲网段。由于 SSH 主机密钥绑定在虚拟机实例标识 barn-mac-<instance_id> 而非 IP 地址上，更换网段不会破坏 SSH 信任链。

macOS 的“本地网络”隐私权限有时会拦截第三方终端或 IDE 访问 vmnet 子网（通常表现为 No route to host），请在 系统设置 → 隐私与安全性 → 本地网络 中为对应应用开启权限。Barn 自身的 Go SSH 连接通过系统内置的 /usr/bin/nc 转发，交互命令则直接调用 /usr/bin/ssh，从而避开第三方二进制直连本地子网时的权限限制。

JSON 输出

除交互式 ssh 外，所有 barn mac 命令均支持通过 --json 与 --yaml 在 stdout 输出结构化结果，同时将进度信息写往 stderr。

ls

{
  "schema_version": 2,
  "root": "/Users/alice/.barn/mac",
  "prepared": true,
  "base": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
  "machines": [
    {
      "name": "mac1",
      "kind": "macos",
      "state": "running",
      "ready": true,
      "ssh": "ready",
      "address": "10.10.20.10",
      "address_stable": true,
      "ssh_host": "10.10.20.10",
      "ssh_port": 22,
      "user": "alice",
      "image": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
      "cpus": 4,
      "memory_bytes": 8589934592,
      "disk": {"capacity_bytes": 107374182400, "allocated_bytes": 1202647040},
      "network": {"subnet": "10.10.20.0/24", "gateway": "10.10.20.1", "address": "10.10.20.10"},
      "shares": [{"name": "src", "host": "/Users/alice/src", "guest": "/Volumes/My Shared Files/src", "readonly": false}],
      "clipboard": true,
      "pid": 2545,
      "instance_id": "b1482ffc-2da7-45d9-ace5-c5f3193a9172",
      "warnings": []
    }
  ],
  "running": 1,
  "limit": 2
}

生命周期结果

单机操作（up、restart、open、recreate、configure）返回单个结果对象；批量操作（start、stop、destroy）即使只指定一台虚拟机也始终返回 {"machines": [...]}。多台虚拟机操作部分成功时，结果中会同时保留成功项与失败详情，并以退出码 5 返回。

{"name": "mac1", "action": "created", "state": "running", "ready": true,
 "address": "10.10.20.10", "user": "alice", "version": "27.0", "build": "26A428"}

其他命令的 JSON 输出：

• exec --json：返回与 Linux barn exec --json 相同的结构（node、exit_code、stdout、stderr）。
• password --json：返回明文密码；配合 --copy 时返回 {"name": "mac1", "copied": true}。
• ssh-config --json：默认返回 fragment 字符串；配合 --install 或 --remove 时返回安装状态。
• logs --json：返回 name 与 logs。
• doctor --json：返回 ok 与 checks[]（每项含 name、ok、detail 及可选的 next），任一检查未通过时退出码为 3。

失败原因

退出码遵循 Barn 命令行退出码表，ssh 与 exec 原样透传远端命令退出码。结构化错误对象包含稳定的 reason 标识与 next 修复建议：

文件

其他宿主与客机文件路径：

• 运行时套接字：/tmp/barn-mac-<uid>-<hash>/。
• OpenSSH 配置片段：barn mac ssh-config 负责维护 ~/.ssh/barn-mac_config 以及 ~/.ssh/config 中的 # barn-mac:include 区块（与 Linux 环境使用的 # barn:include 区块互不干扰）。执行 barn mac ssh-config --remove 会在 config.json 中写入 ssh_config_off，此后生命周期命令不会再自动写入 SSH 配置，直到你显式运行 barn mac ssh-config --install。
• 桌面窗口偏好设置：Barn 将窗口位置保存在 ~/Library/Preferences/com.pgsty.barn.plist（0.9.0 使用 ~/Library/Preferences/io.pgsty.barn.mac-runner.plist）。
• Runner 查找机制：CLI 根据解析符号链接后的自身可执行文件路径定位 runner，兼容 Barn.app 应用包（Barn.app/Contents/MacOS/barn-mac-runner）、安装器与 Homebrew libexec 布局；开发调试时可通过环境变量 BARN_MAC_RUNNER 指定绝对路径、相对路径或 ~/ 路径。执行虚拟机操作前 CLI 会校验 runner 协议版本 2；barn mac doctor 还会检查 runner 的本地代码签名。
• 客机内部配置文件：Barn 在客机内写入 ~/.ssh/authorized_keys、/private/etc/sudoers.d/80-barn 与 /etc/ssh/sshd_config.d/000-barn.conf，设置电脑名称与本地主机名，并通过 pmset 禁用休眠。

镜像清理会保留中断的 recreate 仍在引用的基础镜像，直至恢复清理完成。恢复日志损坏时，barn mac image ls、barn mac doctor 的空间估算与镜像清理都会失败，直到日志修复，期间所有镜像原样保留。若某台机器的状态无法读取，barn mac ls 会整体失败，按名称操作其他机器不受影响。