AI 虚拟机管家 malko/aibox

AIBox

管理 AI 开发虚拟机的脚本，带反向代理和服务管理。

→ malko.github.io/aibox — 项目主页，包含功能、网络模型和快速开始。

快速开始

Run automated setup
./setup.sh

Connect to VM (automatically forwards configured services)
./aibox

Or open the local web console (services, updates, setup, VM lifecycle)
./aibox web

Access opencode at http://localhost:4096
(connection password: see the VM MOTD or run ./aibox status)

环境要求

宿主机

- 带 libvirt 的 KVM/QEMU
- 已安装 virsh、libvirt-client、virt-install
- 带 httpd applet 的 BusyBox，仅 aibox web 需要

sudo apt install libvirt-clients virt-install busybox-static

macOS 上用 Homebrew 安装 BusyBox：

brew install busybox

客户机 VM

- 可 SSH 访问的 Ubuntu/Debian VM
- 至少 4GB 内存，建议 4 核以上

网络模型

VM 故意不从你的网络直接可达：客户机服务监听客户机的 localhost（127.0.0.1），宿主机只通过一条带认证的 SSH 隧道对外暴露，隧道以用户服务方式管理。

隧道服务

aibox tunnel install（或 tunnel 安装步骤）会安装一个用户服务（Linux 上是 systemd --user，macOS 上是 LaunchAgent），为每个已配置的服务保持一条 SSH 隧道。它会：

- 默认把每个服务绑定在 127.0.0.1：服务只能从宿主机访问，地址是 http://localhost:<port>。某个服务可以单独暴露到局域网，不影响其他服务（见下文）；
- VM 关机时等待它启动（TUNNEL_WAIT，120s），然后干净退出：VM 关闭期间不轮询、不占资源；
- VM 重启后自动重连（重启会断开 SSH 连接，服务会重新建立）；
- 从不启动 VM：通过 aibox 启动 VM（aibox start、aibox、aibox restart）时，隧道随之一同启动；
- 不在登录时启动，所以 VM 关闭期间不会有任何东西在跑。

生命周期

| 命令 | 作用 |
| aibox start | 启动 VM 和隧道服务（不开 shell） |
| aibox | 启动 VM + 隧道，然后打开 shell（仅临时端口） |
| aibox status | VM 状态、服务 URL 和隧道状态 |
| aibox shutdown | 先停隧道服务，再关闭 VM |
| aibox restart | 重启 VM；隧道自动重连 |
| aibox tunnel start/stop/restart | 控制隧道，不碰 VM |
| aibox tunnel status | 隧道状态和各服务的 URL/局域网模式 |
| aibox tunnel logs | 最近的隧道日志 |

登录时常驻（可选）

如果你希望一登录就能用服务 URL，加上 aibox start 到桌面启动项（GNOME/KDE 的「启动应用程序」、macOS 的「登录项」）。这样 VM 会在登录时启动，隧道随之建立。

aibox 有意不自己这么做：你不用 VM 的时候，什么都不运行，也不开放端口。

局域网暴露

局域网暴露按服务单独决定，所以你可以暴露 opencode，同时让 dsh 只监听 localhost。每个服务有三种模式：

| 模式 | 设置方式 | 重启后保留？ |
| localhost | 默认，或 aibox tunnel lan off <service> | — |
| 临时 | aibox tunnel lan on <service> | 否 |
| 永久 | aibox tunnel lan on <service> --permanent | 是 |

aibox tunnel lan on opencode --permanent # always exposed
aibox tunnel lan on dsh --timeout 30m # temporary, expires in 30 min
aibox tunnel lan on dsh --no-timeout # temporary until reboot
aibox tunnel lan off opencode # back to localhost
aibox tunnel lan on # all services, temporary

临时暴露不存进 services.json，而是放在每次启动的运行时状态里：下次重启就丢失（运行时目录被清空时，注销也可能丢失），即使超时还没到。永久暴露存进 services.json，下次 aibox start 时重新生效。--permanent、--timeout 和 --no-timeout 互斥。

临时暴露的默认时长由 TUNNEL_LAN_TIMEOUT 决定（默认 2h）。--timeout 30m 覆盖它，--no-timeout 去掉时间限制。每个服务各有一个定时器，到点自动收回暴露；下次执行命令时也会顺带检查是否过期，隧道启动时同样会检查。

aibox service-add opencode 4096 --lan 是添加服务并永久暴露局域网的简写（--yes 跳过确认提示）。aibox service-list 显示每个服务的模式。

暴露之前，aibox 会检查选中的客户机服务是否缺少认证并给出警告（vscode-server 没有密码认证）。opencode 启动时自己生成服务器密码，dsh-web 的连接 URL 内嵌认证 token，所以这两个不需要警告。

临时端口

aibox 8081:80 只在 SSH 会话内转发一个额外端口。除非加 --lan，否则它绑定 localhost，会话结束就消失。临时端口适合用完即弃；要长期用的服务应该写进 services.json，交给隧道服务管理。

宿主机共享

宿主机的 ~/git 有意以可写方式挂载进 VM，方便智能体直接在你的仓库上工作。这是有意的取舍：智能体能改动你的工作副本，所以推送请始终在宿主机手动执行，也绝不要把仓库凭据放进 VM。

不要把 SSH agent 转发进 VM

把 agent 通过 SSH 转发进去，等于把凭据交给 VM：连接开着的时候，VM 里的任何东西（包括智能体）都能请求你本地的 ssh-agent 替你签名，比如执行 git push 时。

- OpenSSH 默认不转发，但 ForwardAgent yes（通常写在 ~/.ssh/config 的 Host 下）或 ssh -A 会打开它。这个设置很关键：不要为 VM 启用，并且要限定到具体主机，而不是 Host 。
- 在 VM 里检查：echo $SSH_AUTH_SOCK 必须为空，ssh-add -l 必须失败并报 "Could not open a connection to your authentication agent"。

用法

连接 VM

./aibox # Start VM + tunnel, then open a shell
./aibox 8081:80 # Also forward host 8081 to guest 80 (session only)
./aibox --lan 3000 # Ad-hoc forward exposed on the LAN

帮助

./aibox help # General help
./aibox help service-add # Help for one command
./aibox service-add --help # Same, from the command itself

Shell 补全

Bash
./aibox --completion bash > ~/.local/share/bash-completion/completions/aibox

Zsh (add ~/.zsh/completions to fpath)
./aibox --completion zsh > ~/.zsh/completions/_aibox

补全覆盖命令、选项、tunnel/LAN 子命令、service-remove 和 tunnel lan on/off 可用的已配置服务、snapshot delete/revert 的快照名、setup 步骤和 update 目标。

启动 / 状态

./aibox start # Start VM + tunnel without opening a shell
./aibox status # VM state, service URLs, tunnel state
./aibox shutdown # Stop tunnel + shutdown VM
./aibox restart # Restart VM (tunnel reconnects automatically)

aibox status 还会报告每个服务端口在 VM 里是否在监听：服务有响应时显示绿点，没有响应时显示红点。检查在 VM 内部执行，因为只要隧道开着，宿主端口就始终接受连接，哪怕 guest 服务已经停了。输出被重定向时，圆点会换成文字状态（[up]、[down]、[unknown]）。

Web 界面

aibox web 启动本地 Web 控制台，并在浏览器里打开：

./aibox web
./aibox web --port 8788
./aibox web --no-open

它只监听 127.0.0.1，需要带 httpd applet 的 BusyBox。服务器在前台运行：按 Ctrl+C 停止，或用页头的 close / fermer 按钮。关闭浏览器标签页后，经过短暂宽限期也会停止；重新加载会取消这次延迟停止。后台不会留下任何进程。

控制台提供：

- VM 生命周期：启动、重启、关闭（可选强制）；
- 隧道状态与控制；
- 服务列表、添加/编辑/删除、按服务开启 LAN 暴露和链接；
- 检查更新和多目标更新选择；系统更新会询问 guest 的 sudo 密码，密码通过管道传输，绝不写入磁盘；
- 检测 setup 状态并重放安全的 setup 步骤；需要 root 的步骤会询问同一个 sudo 密码；
- 运行中的操作会显示日志，可在控制台终止；
- 为服务 URL 设置 LAN 主机名；
- 界面语言：英语（默认）或法语；
- 每个服务都有实时可用性指示：端口在 VM 中处于监听状态时显示绿点，端口关闭时显示红点；
- 快照区域：列出、创建、回滚和删除 VM 快照；
- 一个按钮，用于打开连接到 VM 的终端窗口（它会运行 aibox -n：纯 SSH 会话，不带端口转发）。

界面语言在 réglages / settings 区域选择，并保存在浏览器中（localStorage）。默认是英语。

访问 token 在每次启动时生成，存放在运行时目录（${XDG_RUNTIME_DIR}/aibox-web.token，权限 600），并通过 URL fragment 传给浏览器。API 要求把它作为 bearer token 提交，拒绝非本地的 Host/Origin 请求头，且从不监听 LAN。配置的端口被占用时，控制台会改用下一个空闲端口。按键 1–6 可在控制台各区域之间切换。

在 VM 中运行命令

aibox exec 通过 SSH 在 VM 内运行命令，并返回其退出码。它面向脚本编写：stdout/stderr/stdin 原样透传，不打印其他内容，因此很适合用在管道中。

./aibox exec uname -a # run a command
./aibox exec echo "hello world" # arguments keep their boundaries
./aibox exec bash -lc 'cd ~/git/repo && make' # shell features via a shell
printf 'data' | ./aibox exec cat # stdin is forwarded
./aibox exec -t htop # allocate a TTY for interactive tools

if ./aibox exec test -f /etc/os-release; then ... # exit code propagates

VM 必须处于运行状态（用 ./aibox start 启动）；否则 exec 会立即失败，返回非零状态。

隧道管理

./aibox tunnel status # Tunnel state, per-service URLs and LAN modes
./aibox tunnel start # Start the tunnel (VM keeps running)
./aibox tunnel stop # Stop the tunnel (VM keeps running)
./aibox tunnel lan on opencode --permanent # Permanently expose one service
./aibox tunnel lan on dsh --timeout 30m # Temporary exposure (30 min)
./aibox tunnel lan on dsh --no-timeout # Temporary until reboot
./aibox tunnel lan off opencode # Back to localhost for one service
./aibox tunnel lan off # Back to localhost for all services
./aibox tunnel install # Install the user service
./aibox tunnel uninstall # Remove the user service
./aibox tunnel logs # Last tunnel logs

VS Code（Remote-SSH）

在本地用 VS Code 通过 SSH 连接 VM，无需保持会话打开：

./aibox vscode # Open the current directory when it is shared
./aibox vscode ~/git/aibox # Open a specific directory from the sharebash
./aibox vscode --guest-path /var/log # Open a path inside the VM

aibox vscode 会即时解析 VM 地址，然后运行 code --remote ssh-remote+<user>@<ip> <dir>，因此不会写入 ~/.ssh/config。宿主机上的要求：code 命令行（VS Code：「Shell Command: Install 'code' command in PATH」）和 Remote - SSH 扩展。首次连接时，VS Code Server 会在 VM 内自动安装。

注意：
- 只有共享宿主机目录（HOST_SHARE_DIR，默认 ~/git）下的路径会自动映射：先解析宿主机路径（包含符号链接），再转换成它在 VM 中的路径，共享目录就挂载在那里。
该目录之外的路径会被拒绝，此时用 --guest-path 打开只存在于 VM 中的路径。
- 不带参数时，如果当前目录在共享目录内，就用当前目录。否则 aibox 报错，并要求你输入要打开的目录（也可以退出）。
- --guest-path 打开 VM 内的路径：绝对路径（/var/log）、以 ~ 开头的路径（~/git/repo），或相对于共享目录的路径（repo）。该路径必须在 VM 中存在。
- 宿主机密钥自动接受（不提示指纹）。
- 在 macOS/Lima 上，Reachable 地址是 Lima 实例（lima-<name>）；在 ~/.ssh/config 里加一次 Include ~/.lima/*/ssh.config。

服务管理 bash ./aibox service-add opencode 4096 # Add a service (localhost only) ./aibox service-add portainer 8080:9000 # Add with custom port mapping ./aibox service-add opencode 4096 --lan # Add with permanent LAN exposure ./aibox service-edit opencode --port 4097 # Change the port ./aibox service-edit opencode --name oc --lan # Rename and expose on the LAN ./aibox service-list # List services and LAN modes ./aibox service-remove opencode # Remove a service

VM 管理 bash ./aibox shutdown # Gracefully shutdown VM ./aibox shutdown -f # Force shutdown VM ./aibox restart # Gracefully restart VM ./aibox restart -f # Force restart VM

./aibox snapshot create # Create snapshot (auto name, internal qcow2)
./aibox snapshot create my-snap # Create snapshot (custom name, internal qcow2)
./aibox snapshot list # List snapshots
./aibox snapshot list --json # Same, machine-readable
./aibox snapshot delete my-snap # Delete snapshot
./aibox snapshot revert my-snap # Revert to snapshot
./aibox snapshot revert my-snap --yes --start # Revert, then start the VM again

Note: Snapshots are internal (embedded in qcow2 file). VM must be shut off to create.
--yes skips the confirmation and shuts the VM down first, --start restarts it
after a create or a revert.

Web 控制台会打开一个终端窗口，运行 aibox -n：普通 SSH 会话，不做端口转发，也不碰隧道服务。
终端模拟器会自动挑选：先找常见的（kitty、alacritty、wezterm、foot、gnome-terminal、konsole、xfce4-terminal、x-terminal-emulator、xterm），再找桌面环境的默认终端（xdg-terminal-exec，即 freedesktop 默认终端规范），然后是生成的 desktop entry，最后在 macOS 上回退到 Terminal.app。设置 AIBOX_TERMINAL 可以强制指定一个：

AIBOX_TERMINAL=wezterm ./aibox web # always use wezterm
AIBOX_TERMINAL=xdg-terminal-exec ./aibox web

更新 bash ./aibox update scripts # Upload the latest scripts to the VM ./aibox update os # apt update + dist-upgrade (interactive) ./aibox update os -y # Same, non-interactive ./aibox update opencode # Update opencode (opencode update) + restart server ./aibox update dsh # Update dsh + restart dsh-web ./aibox update claude # Update Claude Code ./aibox update vscode-server # Pull and restart vscode-server ./aibox update all # scripts, os, opencode, dsh, claude, vscode-server ./aibox check-updates # Check for updates (aibox repo + VM) ./aibox self-update # Pull the aibox repo and push scripts to the VM

all 遇到第一个失败就停。opencode-service 不在其中（它只重装 opencode 服务）。

安装流程

./setup.sh 脚本（也可用 aibox setup）把 VM 安装拆成独立、可重放的步骤。某一步的前置步骤会自动运行，所以你可以只重跑其中一部分，不必从头再来。
bash
./setup.sh # Run every step ('all')
./setup.sh motd # Reconfigure the MOTD only
./setup.sh dsh # Install dsh and its web service
./setup.sh motd dsh # Several steps in one run
aibox setup motd # Same, through the main CLI
./setup.sh --status # Show what is installed
./setup.sh --status --json # Same, machine-readable
./setup.sh motd --yes # Use saved/default answers (non-interactive)
./setup.sh motd --no-deps # Run only this step, without prerequisites
./setup.sh --help # List all steps

步骤（按顺序）：vm、ssh、scripts、deps、sshd、git、dirs、hosts、motd、docker、vscode、opencode、dsh、claude、update-check、virtiofs、cli、tunnel。每个步骤实现在 setup/steps/ 下。

cli 步骤只在宿主机上执行：把 aibox 链接到 ~/.local/bin，仅当命令还找不到时才把它加进 PATH，并安装 bash/zsh 补全。它不改动 VM，也不需要 root。

motd 步骤在 VM 里安装登录横幅。横幅用彩色圆点显示它已知的服务：服务在端口上有响应时是绿色，单元在跑但端口关闭时是红色，服务已安装但没运行时是暗色。重跑该步骤即可更新已安装的横幅： bash ./setup.sh motd

答案保存在配置文件中，之后作为默认值复用；每一步只询问自己需要的值。

配置

服务配置

服务保存在 ~/.config/aibox/services.json： json {
"opencode": { "port": "4096", "lan": "permanent" },
"dsh": { "port": "3080" },
"portainer": { "port": "8080:9000" }
}

- port 是客户机端口，或 <host_port>:<guest_port>。
- lan: "permanent" 把服务暴露到局域网，重启后仍然有效。
- 不写 lan 时，服务只监听 localhost。临时局域网暴露不存这里：它放在每次启动的运行时文件里，重启即消失。

旧式字符串条目（"opencode": "4096"）仍可读取，下次改动时归一化为对象格式。

AIBox 配置

主配置在 ~/.config/aibox/aibox.conf：

VM_NAME="ai-agentbox"
GUEST_USER="aibox"

隧道设置：

TUNNEL_LAN_TIMEOUT="2h" # default temporary LAN duration
TUNNEL_WAIT="120" # seconds the tunnel waits for the VM

Web 界面设置：

LAN_HOSTNAME="desk.local" # hostname used in LAN service URLs (empty = auto)
WEB_PORT="8787" # local web console port

TUNNEL_BIND 是旧的全局局域网开关。下次运行 aibox 命令时自动迁移为按服务设置；不再需要它。

OpenCode 配置

在虚拟机里编辑 ~/.config/opencode/opencode.json，配置 AI 服务商。

opencode serve 启动时自己生成连接密码（每次重启都会变）。虚拟机 MOTD 和 aibox status 显示当前密码。

文件结构

aibox/
├── aibox # Main CLI (VM + port forwarding + commands)
├── setup.sh # Setup runner (steps, with prerequisites)
├── setup/ # Modular setup
│ ├── lib.sh # Step registry, prerequisites, runner
│ └── steps/ # One script per step (vm, ssh, motd, dsh, ...)
├── cmd/ # Command scripts
│ ├── start # Start VM + tunnel (no shell)
│ ├── status # VM state, URLs, tunnel state
│ ├── tunnel # Manage the tunnel user service
│ ├── service-add # Add service (optional permanent LAN)
│ ├── service-edit # Edit or rename a service
│ ├── service-remove # Remove service
│ ├── service-list # List services and LAN modes
│ ├── web # Local web console (BusyBox httpd)
│ ├── config # Read or update aibox.conf
│ ├── update-target # Dispatch an update target
│ ├── check-updates # Check for available updates
│ ├── self-update # Pull the repo and push scripts to the VM
│ ├── vm-shutdown # Shutdown VM
│ ├── vm-restart # Restart VM
│ └── vm-snapshot # Manage snapshots
├── host/ # 宿主机侧脚本 │ ├── tunnel.sh # 隧道服务入口（ssh -N -L） │ ├── service.sh # 选择服务管理器 │ ├── services/ # systemd --user / launchd 实现 │ ├── vm.sh # 虚拟机辅助脚本（libvirt） │ ├── create-vm.sh # 创建虚拟机 │ ├── start-vm.sh # 启动虚拟机 │ ├── configure-ssh.sh # 配置 SSH │ └── upload-scripts.sh # 上传到虚拟机 ├── guest/ # 虚拟机侧脚本（上传到虚拟机） │ ├── install-deps.sh # 安装依赖 │ ├── install-docker.sh # 安装 Docker │ ├── install-service.sh # 安装 opencode serve 服务 │ ├── install-dsh.sh # 安装 dsh 命令行 │ ├── install-dsh-service.sh # 安装 dsh-web 服务 │ ├── install-claude.sh # 安装 Claude Code │ ├── update-check.sh # 收集可用更新 │ └── install-update-check.sh # 安装更新检查定时器 ├── web/ # 本地 Web 控制台 │ ├── public/ # HTML/CSS/JS 和 BusyBox CGI（i18n.js = 翻译） │ └── lib/ # CGI 辅助脚本、任务运行器和 open-terminal.sh ├── services-funcs.sh # services.json + 各服务的局域网状态 └── shared-funcs.sh # 公共函数

安全须知

- 服务默认只监听 localhost；临时访问用 aibox tunnel lan on <service>，确实需要时才用 aibox tunnel lan on <service> --permanent
- 永久暴露重启后依然生效；用 aibox service-list 检查，不再需要时用 aibox tunnel lan off <service> 关闭
- Web 控制台只监听 127.0.0.1，并且需要本地 token；不要把它暴露到局域网。需要远程访问就用 SSH 端口转发
- opencode 启动时会自己生成服务器密码；vscode-server 应保留密码；它们没有保护时，aibox 会在暴露到局域网前给出警告
- 宿主机 ~/git 共享目录按设计可写：智能体能改动你的工作副本，所以改动要审查，并从宿主机推送
- 给智能体单独建一个 git 账号
- 绝不要让虚拟机直接推送到主仓库
- 保管好 SSH 密钥，绝不提交
- 你的 AI 不应该拿到你的机密信息