安装、迁移与更新Install, migrate, and update

安装前准备Before you install

首次安装Fresh install

macOS / Linux

curl -fsSL https://veilo.dev/install.sh | sh
export PATH="$HOME/.veilo/cli/bin:$PATH"
veilo --version

安装路径为 ~/.veilo/cli。安装器会更新 shell 配置，并在交互式终端自动进入统一设置引导；当前终端可先执行上面的 export PATH。

Veilo is installed under ~/.veilo/cli. The installer updates your shell profile and starts guided setup in an interactive terminal; use the export PATH line for the current terminal.

Windows PowerShell

irm https://veilo.dev/install.ps1 | iex
veilo --version

从旧版 Veilo 迁移Migrate an older Veilo install

如果 veilo 已指向旧路径，使用迁移参数。安装器会备份可写的旧程序，然后创建指向托管 CLI 的启动入口。

If veilo resolves to an older path, use the migration option. The installer backs up a writable old executable and creates a shim for the managed CLI.

curl -fsSL https://veilo.dev/install.sh | sh -s -- --replace-existing
export PATH="$HOME/.veilo/cli/bin:$PATH"
hash -r
type -a veilo
veilo --version

统一检查并完成设置Check and complete setup

veilo setup
veilo doctor

veilo setup 会统一检查登录、后台 Agent 和 Codex Runtime。缺失项会先逐一询问 yes/no；全部确认后才开始安装，任一项选择 no 都会取消且不会启动 Agent 或会话。自动化环境可使用 veilo setup --yes。

veilo setup checks sign-in, the background Agent, and Codex Runtime together. It collects yes/no approval for every missing item before making changes. Any no cancels setup without starting the Agent or a session. Automation can use veilo setup --yes.

macOS 文件权限macOS file access

veilo permissions open
# Enable Full Disk Access for veilo-agent in System Settings
veilo permissions verify
veilo doctor

在“系统设置 → 隐私与安全性 → 完全磁盘访问权限”中启用 veilo-agent，然后重启 Agent 服务并验证。

Enable veilo-agent under System Settings → Privacy & Security → Full Disk Access, then verify access.

安装 Codex RuntimeInstall the Codex Runtime

veilo update codex-runtime --version latest
veilo install agent --service
veilo doctor

latest 会查询服务端提供的最新兼容版本。安装完成后重新安装 Agent 服务，可立即刷新移动端看到的运行时目录。Claude CLI 不由 Veilo 托管，需要单独安装并确保 claude 在 PATH 中可用。

latest queries the newest compatible version from the server. Reinstalling the Agent refreshes the runtime catalog shown on mobile. Claude CLI is not managed by Veilo; install it separately and ensure claude is available on PATH.

日常更新Routine updates

veilo update
veilo update codex-runtime --version latest
veilo doctor

veilo update 会更新 CLI；如果 Agent 已安装，也会同步更新 Agent 并保留后台服务状态。仅检查新版本可使用 veilo update --check。

veilo update updates the CLI and synchronizes an installed Agent while preserving its service state. Use veilo update --check to check without installing.

开始使用Start using Veilo

# Start a Claude session
veilo claude

# Start a Codex session
veilo codex

# Inspect local sessions and host health
veilo sessions
veilo doctor

保持 Agent 服务运行后，使用同一 Veilo 账号登录移动端，即可选择电脑、工作目录、Runtime 和模型来创建会话。

Keep the Agent service running and sign in to mobile with the same Veilo account. You can then select the computer, workspace, runtime, and model when creating a session.

故障排查Troubleshooting

仍然运行旧版本The old version still runs

type -a veilo
export PATH="$HOME/.veilo/cli/bin:$PATH"
hash -r
veilo --version

Agent 不在线或版本不一致Agent is offline or has a mismatched version

veilo update
veilo install agent --service
veilo doctor

移动端没有 CodexCodex is missing on mobile

veilo update codex-runtime --version latest
veilo install agent --service
veilo doctor