@kortix/agent-tunnel
@kortix/agent-tunnel 将本地计算机通过认证反向隧道连接到Kortix。
每台连接的计算机都是一个项目的帐户 电脑 连接器, 对连接它的人来说是私有的，除非他们与项目共享。 Kortix桌面应用捆绑了这个代理，一键连接。没有 桌面应用程序，使用下面的命令。
连接一次
运行如下所示的命令 连接你的电脑 在一个项目中。然后 在浏览器中批准设备代码：
npx --yes @kortix/agent-tunnel@latest connect \
--api-url https://api.kortix.com/v1/tunnel \
--project-id <project-uuid>
电脑属于你的每一个项目和工作空间，你是其中的一员
在你的私人会议上。 --project-id 只提供“也与……分享”
，在审批页面上；没有它，电脑仍然是你的
无处不在。
再次连接同一台计算机重用其条目。代理发送SHA-256
硬件ID的哈希(IOPlatformUUID， /etc/machine-id，或者 MachineGuid);
原始ID永远不会离开电脑。
批准后, connect 在终端安装后台服务时，
和桌面应用程序一样，打印暂停、恢复、
然后去掉它。它不问任何问题。 --foreground 保持连接在
终端。没有TTY的脚本，或者 --json，留在前景
除非它通过 --daemon.
一个运行时与桌面应用程序（macOS）
当安装Kortix桌面应用程序时(/Applications/Kortix.app 或者
~/Applications/Kortix.app)，命令行安装写入的服务运行在
App自带代理和驱动： Kortix.app/Contents/MacOS/Kortix 与
ELECTRON_RUN_AS_NODE=1 和 Contents/Resources/agent-tunnel/agent-cli.js.
CLI安装和app安装是同一个连接。macOS拨款
可访问性和屏幕记录Kortix一次，永远不会 node 或者一个
终端, 你的电脑 在应用程序中控制它。
这个命令行是计算机的一个控制界面。桌面应用程序运行
这些相同的命令(status --json， access， keep-awake， stop，
start， logout)，并且永远不会编辑代理的文件本身。做出改变
在应用程序中，在终端中，或者通过Kortix进行相同的更改。没有这个应用程序，
服务运行于 node，而电脑使用则需要单独安装
cua-driver.
当它的代码在磁盘上发生变化(应用程序更新或 新提供的包)。macOS拒绝对进程的所有许可 二进制被替换在它下面，所以一个陈旧的进程将失去计算机使用。
在后台运行
该服务是终端用户的默认服务。一个脚本安装它 --daemon：
npx --yes @kortix/agent-tunnel@latest connect \
--daemon \
--api-url https://api.kortix.com/v1/tunnel
该服务在macOS上使用LaunchAgent，在Linux上使用用户系统服务，在Windows上使用Task Scheduler。
它在登录时启动，并且在每次退出（启动）后，管理员重新启动它
KeepAlive 10秒油门，系统 Restart=always（5秒的Windows循环）。
在Linux上，install启用 loginctl enable-linger 所以用户服务保持不变
登出后运行，开机时启动；如果不允许，请安装
打印警告。Windows任务在PowerShell下运行 conhost --headless
（没有控制台窗口，Windows终端也是默认终端），打开
电池，无时间限制。代理在Windows上启动的每个进程设置
windowsHide，因此不会打开控制台窗口。
代理本身永远不会自行停止：
- 它重新连接与指数后退从1秒到30秒，±20%抖动，永远。
- 它丢弃一个在75秒内没有收到中继ping的套接字，并在75秒内重新连接 一旦机器从睡眠中醒来（一个5秒的计时器，看到更多的跳跃） 而不是30岁)。一个尾流重置后退。
- 被拒绝的凭证将使其处于状态
rejected． 它检查config.json每5秒和连接一次，只要一个新的配对写入另一个凭证； 它还每5分钟重试一次旧的。 - 继电器每分钟接收5个连接。这个过程 重启速度比这个更快，等待下一个槽位的时间最长为12秒。
- 具有相同凭据的第二个进程将其置于状态
standby． 它 1分钟后再试一次，每次加倍，直到30分钟 一个证书的持有者不会来回交换连接。 - 握手不能到达
auth_ok在20秒内被丢弃并重试。 - 没有保存凭据：它等待并检查
config.json每60分钟一次。
它只会在一段时间内改变电脑的睡眠设置 keep-awake 正在进行中(见
“访问控制”)。
管理后台服务
npx --yes @kortix/agent-tunnel@latest service-status
npx --yes @kortix/agent-tunnel@latest logs
npx --yes @kortix/agent-tunnel@latest restart
npx --yes @kortix/agent-tunnel@latest stop # pause: stays stopped after login and reboot
npx --yes @kortix/agent-tunnel@latest start # resume
npx --yes @kortix/agent-tunnel@latest uninstall-service
npx --yes @kortix/agent-tunnel@latest logout # remove this computer from Kortix, then sign out
stop 禁用作业(launchctl disable， systemctl --user disable --now，
schtasks /Change /DISABLE)，所以它会一直停止，直到 start.
logout 第一次调用 DELETE /v1/tunnel/self 有了机器自己的证书，
删除机器和它在科提克斯的账户。然后清除本地
凭据并删除服务。如果联系不上科提克斯，当地的
签到仍然完成； logout --json 然后报告 "serverUnpaired": false.
status --json （及其别名） service-status --json)打印配对；
经批准的 capabilities，服务(installed， active， enabled ＝
不停顿了一下, upToDate =单位匹配什么 install-service 写),
实时连接 state (一个进程没有说就死了，读作
offline), access （同一物体） access --json 打印)。
凭据存储在 ~/.agent-tunnel/config.json． Agent隧道要求
要指定的文件为常规文件，由当前用户所有，以及模式 0600 在POSIX。
保护操作系统帐户，因为这个设置令牌可以进行身份验证
机器直到你旋转或删除连接。
远程API url必须使用HTTPS。纯HTTP仅用于 localhost，
127.0.0.1, ::1 发展的端点。
文件和隔离
| 路径（在config目录下） | 内容 |
|---|---|
config.json | 凭据和本地限制，模式 0600. |
state.json | { tunnelId, apiUrl, status: online|offline|connecting|rejected|standby, since, agentVersion, pid }，在每次连接更改时自动重写。没有凭据。 |
access.json | { mode: ask|always|off, grantedUntil, deniedUntil, keepAwake }、模式 0600． 参见“访问控制”。 |
access-request.json | { id, requestedAt, capability, method, change? }：电话，或通过Kortix (change)，等待主人。 |
desktop-app.json | 由Kortix桌面应用程序编写：如何启动它以显示访问提示。 |
logs/ | 服务输出。 |
AGENT_TUNNEL_HOME 替换配置目录(默认 ~/.agent-tunnel）。
非默认目录也有自己的服务，
ai.kortix.agent-tunnel.<first 8 hex of sha256(directory)>等一下
标识永远不会替换默认值 ai.kortix.agent-tunnel 服务。这个
服务定义携带 AGENT_TUNNEL_HOME 进入服务环境。
访问控制
在每次呼叫之前，机器会决定座席是否可以使用它。改变 使用CLI：
npx --yes @kortix/agent-tunnel@latest access # show it
npx --yes @kortix/agent-tunnel@latest access ask # or always, off
npx --yes @kortix/agent-tunnel@latest access --allow-for 60 # in ask: allow for 60 minutes (max 1440)
npx --yes @kortix/agent-tunnel@latest access --revoke # end the current allowance
npx --yes @kortix/agent-tunnel@latest access --deny # answer the waiting request with No
npx --yes @kortix/agent-tunnel@latest keep-awake on # or off (macOS and Linux)
每个命令都需要 --json 并打印 { mode, grantedUntil, deniedUntil, keepAwake, keepAwakeSupported, pendingRequest }． 错误的模式或持续时间
出口 1 改变不了什么。站在终端的人是电脑的
所有者，所以这些命令也扩大了访问范围。
mode | 效果 |
|---|---|
always | 每个调用都运行。一台没有 access.json 就像这样。 |
ask | 调用运行时 grantedUntil 是在未来（最多24小时）。否则代理会写 access-request.json，如果桌面应用程序未运行，则启动该应用程序，并保持通话20秒。一笔拨款管理着它。无应答 -32010 computer_access_pending． 一个拒绝集 deniedUntil 提前10分钟返程 -32011 computer_access_denied;在此之前，呼叫会立即失败。 |
off | 每次调用都会返回 -32012 computer_access_off. |
通过Kortix。 所有者还可以从Kortix网络应用程序更改访问权限
或者桌面应用程序的窗口(POST /v1/tunnel/connections/:id/access、用户
凭证;没有代理或会话令牌到达它)。Kortix传递
将代理更改为 tunnel.access.set：
- 缩小的(
ask，off，--revoke，--deny（保持清醒）立即适用， 即使访问是off. - 不断扩大的(
always（或更长时间的津贴）需要主人在电脑上。 代理将其写入access-request.json与change，以及桌面 应用程序显示本机 允许 / 取消 对话框。 允许 运行匹配access命令; 取消 运行access --deny，它拒绝了这种变化 没有拒绝电话。中继呼叫等待时间长达20秒，否则呼叫失败 与-32014 computer_access_unconfirmed． 没有桌面的电脑 应用程序立即失败，命名要在其上运行的命令。
从Kortix桌面应用程序开始配对 ask：应用程序显示
提示。仅使用该CLI进行的配对从 always，因为没有
在机器上可以回答提示。这是故意偏离
“新配对默认为询问”。模式和保持清醒是所有者的
机器设置：重新配对(--reauth（被拒绝或过期的凭证）
保留它们，只有先前配对的同意或拒绝才会被丢弃。
logout 删除 access.json，因此下一次配对从默认值开始。代理人回家(config.json， access.json， desktop-app.json）
始终是一个阻塞的路径：没有文件或shell调用可以更改这些文件。
代理将其状态作为签名通知报告给Kortix
tunnel.access.state 在连接和每个更改上：访问字段，
等待请求，以及 desktopPermissions （{ accessibility, screenRecording }
作为macOS应答代理进程本身，每60秒检查一次)。Kortix
这恰恰说明了这一点。
keep-awake on 使计算机在代理运行时不处于睡眠状态：
caffeinate -s 在macOS上（仅限交流电源）， systemd-inhibit --what=sleep 在
Linux。不支持Windows。
机器可读的连接
connect --json 在标准输出上打印以换行分隔的JSON事件，而不是
终端用户界面。它从不提示，从不打开浏览器；来电者显示
批准的URL。
{"event":"challenge","deviceCode":"ABCD-1234","verificationUrl":"https://…","expiresAt":"…"}
{"event":"approved","tunnelId":"…","capabilities":["filesystem","shell"]}
{"event":"service","action":"install","ok":true,"active":true,"detail":"…"}
{"event":"error","message":"…"}
approved 携带 "existing": true 当保存的配对仍然有效时。
service 只跟在后面 --daemon.
在电子(ELECTRON_RUN_AS_NODE=1)，则安装的服务将运行
与 ELECTRON_RUN_AS_NODE=1 然后把包放好。
允许界限
Kortix检查会话是否可以使用计算机帐户（所有者），
共享和连接器策略，如 require_approval)，然后再传送
操作。配对时批准的功能是固定的；再次配对改变
他们。然后，本地代理再次检查操作。
本地配置为最大边界。服务器无法扩展配置 文件系统路径、阻塞路径、shell命令、超时、文件大小或桌面 特性。
一、 shell 授予本地代码执行。允许列表与可执行文件匹配
准确地命名，块列表也匹配以该名称结尾的每个路径
（/bin/rm 是 rm）. 参数不受限制：是允许的 git， find，或者
python 可以通过自己的标志运行任何代码。格兰特 shell 只针对一个会话
你信任这台电脑。
计算机使用驱动程序
Agent Tunnel从不下载或执行桌面驱动程序。Kortix桌面
应用程序包 cua-driver 在macOS和Windows （x64）上运行，它运行的代理使用
复制。CLI安装使用来自的现有二进制文件 CUA_DRIVER_BIN，
~/.local/bin， /usr/local/bin，或者 /opt/homebrew/bin.
一个批准 desktop 当驱动程序存在时进行注册。失踪macOS
授予不会注销它：代理会报告 desktopPermissions 和
设置需要它们。当司机失踪或被拒绝（认错车主）时，
group-writable), desktop 不注册和原因报告为
unavailableCapabilities.desktop 在 status --json 在 machineInfo.
将该二进制文件视为受信任的本地代码。代理隧道不验证或更新
它。
传输二进制文件而不复制base64
运行源文件所在的客户端。集 TUNNEL_API_URL， TUNNEL_TOKEN，
和 TUNNEL_ID 对于目标连接，然后运行：
agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}'
fs_upload 从 source，计算SHA-256，并发送字节
以编程方式通过经过身份验证的隧道。它需要文件系统写入
许可。待定审批返回 success: false 出口代码为1；重试
只有经过批准。该命令接受不超过3mib的常规文件
在base64编码后，在中继的5mib消息限制下的房间。
连接的代理检查所提供的 sha256 修改目的地址之前。
它在写入后读取文件并返回其持久化文件 sha256 和 size.
只有两个源都匹配，CLI才会成功。没有校验和的旧代理
支持导致验证失败；该文件可能已经存在。更新代理
之前进行重试。
为原料 fs.write， sha256 是可选的兼容性。为二进制提供它
内容。永远不要从模型上下文中复制不透明的base64有效负载。生成文件
当编程式传输不可用时，在目标上。匹配散列
验证字节完整性，而不是格式有效性：验证XLSX/ZIP结构和工作簿
来源的内容。文件大小和魔术字节不足。不要使用
此工作流的公共文件主机中继。