跳转到内容
Codux Codux AI

主机端（Codux Agent）

无界面的 Codux Agent（codux，主机端）是桌面端的非 GUI 对应物。把它跑在任意机器上—— 服务器、闲置的 Mac、一台 Linux——桌面端或手机即可通过端到端加密的 Iroh 链路 连上去，远程运行那台机器的终端、Git、AI 会话和记忆。所有功能都跑在该主机自己的 数据上，客户端只负责操控。

一个二进制 codux 驱动一切。它可在 macOS、Linux、Windows（x86_64 与 arm64）上 构建运行。PTY 使用 portable-pty（Windows 上为 ConPTY），传输 / Git / AI 都与平台 无关。

安装

Section titled “安装”

一行命令安装（推荐）

Section titled “一行命令安装（推荐）”

在 macOS 或 Linux 上，这条命令会自动下载与你系统 / 架构匹配的 codux 二进制并放到 PATH 上，不需要任何编译工具链：

Terminal window
curl -fsSL https://raw.githubusercontent.com/duxweb/codux/main/apps/agent/scripts/install.sh | sh

常用参数（写在 sh -s -- 后面）：

  • --setup — 安装完顺手跑一遍 codux config + codux install
  • --beta — 安装包含预发布在内的最新版本
  • --version <x.y.z> — 锁定到某个确切版本
  • --dir <path> — 安装到指定目录
  • --mirror <前缀> — GitHub 慢的时候，加一个下载镜像前缀
  • --uninstall — 卸载主机端（再加 --purge 会连配置、配对、日志一起删掉）

以后要卸载：

Terminal window
curl -fsSL https://raw.githubusercontent.com/duxweb/codux/main/apps/agent/scripts/install.sh | sh -s -- --uninstall

手动下载

Section titled “手动下载”

想自己动手（或在 Windows 上）？从 Releases 下载 codux-<系统>-<架构> 二进制，放到 PATH 上并命名为 codux。或从源码构建：

Terminal window
cargo build -p codux-agent --release   # 产出 `codux-agent`

初始化

Section titled “初始化”
Terminal window
codux config     # 初始化（设备名、中继）
codux install    # 安装为开机自启服务
codux qrcode     # 显示用于手机/桌面配对的二维码

服务安装分别对应 launchd（macOS）、systemd --user（Linux）、 任务计划程序（Windows），所以 codux install 会让主机开机自启、失败自动重启。

配对设备

Section titled “配对设备”
  1. 在主机上运行 codux qrcode（或用 codux link 以文本形式打印 ticket）。
  2. 在桌面端打开 设置 → 远程 → 连接，扫码或粘贴 ticket；手机端直接扫码即可。

由于连到主机本身就需要一次性的 Iroh ticket，配对是自动确认的——ticket 就是门禁。 凭据始终不离开主机。

需要预览运行在主机端的开发服务？Codux 2.0 及以上版本提供 Web 隧道浏览器。

命令

Section titled “命令”
命令作用
codux version打印版本与协议修订号。
codux config交互式配置向导。写入 codux.toml，已有值作为默认。步骤：设备名 → 中继网络 →（自定义中继：URL + 可达性检查 + 可选鉴权）。
codux start在前台启动主机（banner + 日志）。幂等——若已有实例在跑，会打印其位置而非再起一个。
codux stop停止正在运行的主机。
codux status主机是否在运行、从何时起、节点 id、已配对设备数。
codux install把 codux start 注册到系统服务管理器，开机自启、失败重启。
codux uninstall停止并移除该服务。
codux qrcode在终端里打印配对二维码（需要时会先启动主机）。
codux link以文本形式打印配对 ticket，便于粘贴到桌面端”连接”框。
codux update检查 GitHub Releases 是否有新版本，下载、校验、替换当前二进制并重启主机。
codux device列出已配对设备（id、名称、类型、最近在线）。
codux device:del <id>移除某个已配对设备。
codux device:rename <id>重命名某个已配对设备。
codux device:clear移除所有已配对设备。

运行 codux <命令> --help 查看详情。

工作原理

Section titled “工作原理”
  • 单实例。 运行中的主机持有一把建议锁（codux.lock）；start 和配对命令据此判断 “已在运行”，而不是再起第二个。
  • 稳定身份。 host_id + host_token（由 config 生成一次）作为 Iroh 节点身份的 种子，所以配对 ticket 和每个已保存桌面的重连目标都能在重启后保持不变，且不会自动轮换。
  • 自动恢复。 桌面端断开重连后，恢复的是同一批主机终端会话——PTY（以及里面运行的 shell / AI）在客户端断开期间始终存活。

文件

Section titled “文件”

状态保存在 ~/.codux-agent（可用 $CODUX_AGENT_DATA_DIR 覆盖）：

文件用途
codux.toml配置（来自 codux config）。
devices.json已配对设备。
pair-ticket.json已发布的配对 ticket。
status.json运行中守护进程状态（pid、启动时间、节点）。
codux.lock单实例锁。
codux.log后台守护进程日志。

中继 vs. 主机

Section titled “中继 vs. 主机”

中继只负责帮两台设备互相发现、在没有直连路径时转发流量——它不会运行你的终端，也看不到 解密后的内容。主机（这个 codux agent，或你的桌面端）才是真正运行会话的一方。要自建 中继，见自建中继节点。