文档Docs
网页终端：在电脑浏览器里用 Agent J 主机的命令行Web terminal — the Agent J host's command line in a computer browser
在电脑浏览器里开一个限时的终端，像云服务后台的网页终端一样在 Agent J 主机上敲命令；默认关，在「设置」→「安全」里用 Face ID 加电脑密码就能开启，手机上不能用；每次打开都要 Face ID；聊天里用`!`运行命令，扫脸填入电脑密码。A time-limited terminal on the Agent J host, used from a computer browser like a cloud console; off by default, switched on from Settings → Safety with Face ID and the computer password, not available on a phone; Face ID on every open; `!` commands from the chat and a computer password filled in with Face ID.
网页终端让你在电脑浏览器里用 Agent J 主机（装着 Agent J 的那台电脑）的命令行，就像云服务后台里的网页终端：你在浏览器里敲一行命令，主机运行它，结果显示在浏览器里。它在「设置」→「安全」→「网页终端」里。
它只能在电脑浏览器里用，也就是在电脑浏览器里打开的遥控器。手机上只显示一句：「因为安全性和便捷性的原因，网页终端只能在电脑浏览器里操控。」
它默认是关的。开启要你本人确认：在电脑浏览器里用 Face ID 加 Agent J 主机的登录密码，或者在主机上运行一条命令。Agent、定时任务和脚本都开不了。每次打开都要用 Face ID 确认，默认最长 15 分钟，全程录像。
开启以后，你还可以在聊天里直接用!开头运行命令（[详见](#bang)）；让电脑记住电脑密码，之后扫脸就能填入，Agent 的管理员命令卡上也能用（[详见](#computer-password)）；还可以让 Agent 帮你打开终端、填好命令，或者读取终端的输出（[详见](#agent)）。
在哪里找
打开「设置」→「安全」，「网页终端」这一行一直都在，按情况写着下一步：
- 电脑浏览器，还没开启或这个浏览器还不能用：点「开启并打开网页终端」，见[在电脑浏览器里开启](#enable-browser)。下面「也可以在 Agent J 主机上运行下面这行：」写着
agentj terminal enable，点旁边的按钮就能复制（[详见](#enable)）。 - 手机：只写着「因为安全性和便捷性的原因，网页终端只能在电脑浏览器里操控。」，没有按钮。
- Agent J 主机是 Windows（不在 WSL 里）：写明这台电脑的系统暂不支持，下一版支持；现在支持 Linux、macOS 和 Windows 的 WSL。
- 这台设备还没设 Face ID：先点「设置 Face ID」。
- 只写着一行命令、没有开启按钮：这台遥控器配对时没记下它是电脑还是手机（比如配对得很早）。重新配对这台遥控器，就能直接在这里开启；也可以在 Agent J 主机上运行写着的那行命令，见 [谁能用](#who)。
- 已开启，这个浏览器也能用：点「打开网页终端」。
在电脑浏览器里开启
- 在电脑浏览器里打开遥控器，到「设置」→「安全」→「网页终端」点「开启并打开网页终端」。
- 用 Face ID 确认。
- 输入一次 Agent J 主机的登录密码，就是你登录那台电脑、用 sudo 时输入的密码。主机用 sudo 核对它；开启时每次都要亲手输入，不用记住的密码。
- 密码对了，网页终端就为这个浏览器开启，并马上打开：你离开「设置」，在这个窗口里全屏使用它，点右上角的 ✕ 收起（[详见](#full-screen)）。
开启后，所有遥控器都会收到一条通知，写明是在哪台设备上开启的。这台是网页版遥控器时，通知里还会写：不是你本人开启的话，立刻在 Agent J 主机上运行 agentj terminal disable。
浏览器判断你用的是电脑还是手机，只是为了把你带到对的地方。Agent J 主机自己也会按配对时记下的设备类型，拒绝配对成手机的遥控器打开或开启网页终端。真正保护你的是这几道门：签名、Face ID、电脑登录密码、全程录像和时间限制。
在 Agent J 主机上开启
另一种开启方式：在 Agent J 主机自己的终端里运行：
agentj terminal enable- 主机上会显示一串 6 位对照码，同时你已配对的遥控器（包括手机）都会收到一张确认卡片，卡片上写着能用的设备、每次最长几分钟，以及同一串对照码。
- 核对两边的数字一样，再在一台设了 Face ID 的遥控器上点允许，用 Face ID 确认。5 分钟内没人确认，就什么都不改。
- 确认后，名单上那个电脑浏览器的「设置」→「安全」里出现「打开网页终端」。
要求：
- 至少一台已配对的电脑浏览器设了 Face ID（或指纹，也就是通行密钥）。还没设的，先在它的「设置」→「安全」→「网页终端」点「设置 Face ID」。
- 支持 Linux、macOS 和 Windows 的 WSL；Windows 本身还不支持，留到下一版。Mac 上另有几条，见 [在 Mac 上](#macos)。
- 你的电脑账户要能用 sudo，而且 sudo 要输密码。sudo 不用密码（NOPASSWD）或者账户不是管理员，
agentj terminal enable会直接拒绝并说明原因：网页终端要拿电脑登录密码当第二道锁。
这条命令只能由你在自己的终端里亲手运行。Agent、定时任务、脚本，还有网页终端本身，都开不了它。遥控器只能用「开启并打开网页终端」为它自己开启，还要 Face ID 和电脑登录密码；手机开不了。
有好几台设了 Face ID 的电脑浏览器时，用 --device 选一台（可以写多次；配对成手机的遥控器选不了）；每次最长几分钟用 --minutes 改，默认 15，最多 60：
agentj terminal enable --device <设备> --minutes 30agentj terminal status 列出开关、名单上的设备和每台是否记住了电脑密码。
在 Mac 上
Agent J 主机是 Mac 时，网页终端和 Linux 上一样：同样要你本人开启、每次打开都要 Face ID、有时间限制、全程录像、危险命令要再确认、敲的命令照样先遮挡再记录。几点不同：
- 开启前还要满足三条，不满足时会直接说明原因：你的 Mac 账户是管理员（系统设置 → 用户与群组里写着管理员）；sudo 没有开启 Touch ID 或 Apple Watch 验证，不然 sudo 会在 Mac 屏幕上等你按指纹，远程永远等不到；装了命令行开发工具（在 Mac 上运行
xcode-select --install），网页终端里的 sudo 才能安全地用记住的电脑密码。没装的话终端照样能用，只是 sudo 会说明原因并拒绝运行。 - 终端用你的登录 shell：默认是 zsh；登录 shell 是 bash 的，就用系统自带的 bash。它不读
~/.zshrc、~/.bash_profile这些启动文件，所以里面的别名和函数没有；常用路径（包括 Homebrew 的/opt/homebrew/bin）都在 PATH 里，文字按 UTF-8 显示。 - 命令历史只存在 Agent J 的数据目录里，不写进
~/.zsh_history。看起来像密码、密钥、令牌的行，和以空格开头的行，都不进历史。 - Mac 上没有 Linux 那样的隔离运行空间。终端以你本人的身份运行，不是 Agent，也不受 Agent 的隔离限制；保护它的是前面那几道门。
谁能用
名单上的设备才能打开网页终端。开启时选的那台，或者在浏览器里自己开启的那台，是你自己的。
请朋友（比如一位工程师）帮忙时，不要把你的设备交给他。让他在自己电脑的浏览器里配对成一台遥控器，并设好他自己的 Face ID，然后你在 Agent J 主机上临时允许这一台：
agentj terminal allow <设备> --hours 2--hours 可以填 1 到 24，默认 2，到时间自动取消。临时允许的设备不会记住电脑密码，每次打开都要重新输入一次。用 agentj terminal deny <设备> 可以提前把它从名单上去掉。配对成手机的遥控器不能被允许。
网页版遥控器要多加 --allow-web。这种设备的「网页终端」那一行会写「这台设备是网页版」。原因：网页版的页面如果被篡改，可能借用你的 Face ID。确认卡片上也会写明这一点。
agentj terminal allow <设备> --allow-web打开和输入密码
- 在电脑浏览器里，到「设置」→「安全」→「网页终端」点「打开网页终端」，再点「用 Face ID 确认」。每次打开都要 Face ID，不会因为刚用过就跳过。
- 在一台设备上第一次打开时（除非这台已经能扫脸填入，见[下文](#computer-password)），终端页里会出现「输入电脑的登录密码」。这就是你登录 Agent J 主机、用 sudo 时输入的那个密码。它在浏览器里加密后才发出，只有 Agent J 主机能解开；它不会显示，也不会留在这台设备上。点「用 Face ID 发送」。
- 主机核对密码，对了就打开终端，顶上显示当前目录、剩余时间和「录像中」。
密码输错：同一台设备连错 3 次锁 15 分钟；整台主机一小时内错 10 次锁 1 小时。每次输错，所有遥控器都会收到提醒。电脑系统自己可能也会把这些错误计入它的锁定次数（比如 Linux 的 pam_faillock），连错太多次，可能连电脑本身的登录也会被暂时锁住。
电脑密码怎么保存
电脑会按下面三种方式之一保存密码，「设置」里的那一行会用大白话写明是哪一种：
| 方式 | 设置里怎么写 | 什么时候用 |
|---|---|---|
| 扫脸才能解开 | 电脑密码已加密保存，只有你扫脸才能解开。 | 这台设备的 Face ID 支持这项能力时（优先） |
| 电脑本机加密 | 电脑密码已加密保存在电脑上，扫脸后电脑才使用它。 | 设备不支持上一种，且「隔离运行」开着、「会话模式」是「独立会话」时 |
| 只在这一次 | 每次打开都要输入电脑密码，用完即清除。 | 其他情况，以及朋友临时允许的设备 |
这几种方式能防什么、不能防什么：
- 前两种：防备份、离线拷贝和 Agent 直接读盘；不防能改 Agent J 代码或用户服务的程序。 密码文件加了密，拷走、备份走都打不开，Agent 直接去读也读不到明文。但同一台电脑上，如果有程序能改 Agent J 自己的代码或你的用户服务，它就能在密码被用到的那一刻拿到它。
- 电脑本机加密只在「隔离运行」开着、「会话模式」是「独立会话」时才能用；你一关隔离或改成共享会话，这份密码立刻删除，下次打开重新输入。
- 只在这一次：密码只在电脑上的 Agent J 内存里，终端关掉就清除，硬盘上不留。
想让电脑对这台设备忘掉密码，在「设置」→「安全」→「电脑密码」点「清除这台」；想删掉所有记住的密码，在电脑上运行 agentj terminal forget。你在电脑上改了登录密码以后，旧的那份在下次被 sudo 拒绝时自动删除，下次打开时再输一次新密码就好。
电脑密码：输一次，以后扫脸
上面第一种方式就是一个小小的密码保险箱。电脑密码只以加密形式存在电脑上，从不存在遥控器上；每台设备用自己的 Face ID 或指纹来解开。
- 在一台设备上第一次用：输一次密码（在终端里，或在管理员命令卡上）。之后这台设备扫脸就能填入。
- 换一台设备：在那台设备的「设置」→「安全」→「电脑密码」点「让这台也能用」，先用 Face ID 确认，再在 2 分钟内到一台已经能用的设备上点「用 Face ID 同意」。那张卡片上写着新设备的名字、设备编号、通行密钥、配对日期和类型：只在你认得这台设备时同意。同意后所有遥控器都会收到提醒。也可以直接在新设备上输一次密码。
- Agent 的管理员命令卡（sudo）：点「用 Face ID 填入电脑密码」；或者点「或者输入电脑密码」，并勾选「用 Face ID 记住（下次扫脸即可）」。密码只用于这一条命令，Agent 拿到的是命令的输出，不是密码。手机上的管理员命令卡也能这样用。
- Face ID 不支持这项能力的设备（设置里会写明），以及临时允许的设备，每次都要输入密码。
- 你改过密码时，卡片上会写「记住的电脑密码不对了（可能改过），请输入一次。」这不算输错密码。
它能防的和上面一样：防备份、离线拷贝和 Agent 直接读文件；不防能改 Agent J 代码或用户服务的程序。
「设置」里的「电脑密码」那一行写着这台设备能不能用；「清除这台」只取消这一台的使用权。
怎么敲命令：行模式
第一版是行模式：你在浏览器里写好一整行，点「发送」，主机才运行。
- 一行最多 4096 字节，不能有 Tab 和换行。没有 Tab 补全。
- 控制键只有两个：Ctrl+C（中断正在运行的程序）和 Ctrl+\（强制退出它）。没有 Ctrl+D、Ctrl+Z。
- 不能用全屏程序，比如
vim、top、less。要看文件用cat、head、tail。 - 有的程序发现输出不是屏幕，会攒够一大块才一起显示，看上去像卡住。可以在命令前加
stdbuf -oL，让它一行一行地输出。 - 错误信息和普通输出按顺序混在一起显示。颜色等控制字符会去掉，看起来像密码、密钥的内容会先在主机上遮住再发到浏览器。输出太快时，多出来的部分会省略，并写明省略了多少字节。
- 浏览器只把输出放在内存里，关掉就没了，不存到这台设备上。
不要在终端里输入密码
网页终端不是真正的屏幕，程序要密码时（比如 ssh、git 要账号密码，passwd），它读到的就是你发的下一整行明文。所以不要在这里输入任何密码。输入框下面也有这句提示。
sudo 是例外：你在终端里用 sudo，页面上会弹出「用 Face ID 允许 sudo」，写明 sudo 实际要运行的命令和你敲的那一行；两者不一样时会特别提醒。点「用 Face ID 允许」，主机把记住的密码交给这一次 sudo；点「不允许」，sudo 就失败。60 秒内不答也算不允许。密码从来不会出现在你发的命令里。
程序正在运行时你发的行，会交给那个程序。这样的行在录像里只留一句占位说明，不记内容，也不进命令历史。
网页终端自己的命令历史只存在主机上（只有你能读）。行首带空格的行、和上一行重复的行，以及看起来在设置密钥或密码的行（比如 TOKEN=…、--password=…、Bearer …、https://用户名:密码@…）都不会留下；你平时用的终端的历史不会被读取，也不会被复制过来。
危险命令要再确认一次
每一行发出前，主机都会先看一遍。删除文件这类高风险命令，还有直接起一个新的 shell 或解释器、运行脚本文件、ssh、su、source、eval 这一类，会先弹「这一行要你确认」，写明原因。点「运行」并用 Face ID 确认才执行；不点，或 120 秒内没确认，就不执行。这种确认只能由正在用终端的这台设备来点，任何自动批准都不适用。
老实说：这一步只防手滑，不防已经拿到会话的人。 一条命令可以拆成好几行拼出来，比如先存成变量、写进文件再运行，主机不一定认得出来。真正保护你的是前面那几道门：开启要你本人确认、名单、每次 Face ID、时间限制和全程录像。
什么时候会自动关
出现下面任何一种情况，终端就关掉，并停下它里面还在运行的所有命令：
- 到了时间上限（默认 15 分钟，在主机上开启时用
--minutes改，最多 60）。 - 5 分钟没有发任何一行。
- 浏览器切到别的标签页或最小化超过 60 秒。
- 连接断了。
- 你点了「全部停下」，或主机上的 Agent J 停了。
- 你在主机上运行了
agentj terminal disable，或用deny把这台设备去掉。 - 你点了「结束」。
打开和关闭时，所有遥控器都会收到一条通知，写明原因和用了几分钟。同一时间只能有一台设备在用网页终端。
全屏、收起、复制和截屏
终端打开后是全屏的：深色底、浅色字。从「设置」里打开时，你会离开设置页，在这个窗口里全屏使用它。（这里说的是页面全屏；vim 这类全屏程序仍然不能用。）
- 收起：点右上角的 ✕，按 Esc，或者把顶部的小横条往下拉。双击什么都不会发生，免得打扰正在运行的程序。
- 收起不等于结束。 终端照样运行，时间限制不变，消息框上方会出现「终端 · 剩 N 分钟」，点「打开」就回来。弹出 sudo 或确认卡片时，终端会自己回到全屏。
- 「复制输出」：复制页面上的输出。
- 「截屏发到聊天」：把屏幕上看得到的输出画成一张图，放进附件；你点发送才会发出去。
- 点「结束」才会关掉终端。
在聊天里用!运行命令
在电脑浏览器的消息框里先打 !，再接命令，比如 !df -h，然后发送。它不会当成聊天发给 Agent J，而是作为一行命令在网页终端里运行。
- 这台设备的终端没开时，会先请你用 Face ID 打开它，打开后收在后台。
- 聊天里出现一张结果卡片，显示输出；输出长时点「展开全部」。
- 命令和输出随后交给 Agent J，它会接着处理。
上面的规矩全都照旧：危险的行要确认，sudo 要 Face ID，时间限制和录像不变。同一时间只运行一条! 命令；120 秒还没运行完，卡片先显示到那时为止的输出。
终端没开启，或这台设备不在名单上时，会弹出一张卡片写明怎么开启；在手机上，卡片说明网页终端只能在电脑浏览器里操控。只想发一句以 ! 开头的普通消息，就在! 前面加一个空格。! 只在 Agent J 的 App 和网页里有用，Telegram、邮件里不算。
哪些内容会交给 AI
! 命令的输出，以及 Agent 用 agentj terminal output 读到的内容，会进 Agent 的对话，也就会发给你用的 AI 模型服务商。发出之前，电脑会再遮一遍：KEY、TOKEN、SECRET、PASS 这类名字后面的值，-p 或 --password 后面的那个词，链接里的密码。卡片上会写遮了几处，比如「已隐藏 3 处像密码或密钥的内容」。
这种遮挡并不完美：它会多遮一些无害的东西（比如 mkdir -p dir 里的 dir），也可能漏掉格式少见的密钥。所以不要在终端里打印密码或密钥（比如别 cat .env）。
录像
每次使用都会录下来：遮挡过的输出和你发的每一行（同样先遮挡）。录像存在主机上 Agent J 的数据目录里，只有你的电脑账户能读，保留 30 天后自动删除。录像不上传到任何地方，也不会进客服报告。操作记录里另外记下哪台设备、什么时候打开和关闭，以及确认过的危险命令和 sudo，这些只记摘要，不记命令原文。
在主机上看最近的记录和录像文件名：
agentj terminal logs它不是断线时的备用通道
网页终端走的是遥控器和 Agent J 主机之间同一条加密连接。连接断了，它也用不了。遥控器连不上主机时，用这些办法：
- 遥控器上的「紧急修复」，按 ① ② 的顺序试。
- 在主机上运行
agentj doctor --reconnect。 - 请主机旁边的人运行
curl -fsSL https://agentj.app/rescue | sh。
详见 手机显示灰色或断开怎么办。
「紧急修复」下面「Agent J 主机上的命令」里的每条命令，在终端开启且这台设备在名单上时，旁边会多一个「在终端里打开」：它把这条命令填进网页终端，你按回车才运行。
关掉和收回
- 关掉整个功能，同时删掉所有记住的密码：
agentj terminal disable- 把一台设备从名单上去掉：
agentj terminal deny <设备>- 只删掉记住的电脑密码，名单不变：
agentj terminal forget解除一台遥控器的配对，或删掉它的 Face ID，它也会自动从名单上去掉，记住的密码一起删除。
借朋友电脑救急
Agent J 主机不能随身带，但浏览器到处都有。急着要在主机上敲几条命令时，可以临时借一台电脑的浏览器，用完解绑：
- 扫码配对：在借来的电脑上用浏览器打开遥控器网页，让它亮出配对二维码；拿你已配对的手机扫这个码，核对两边的 6 位对照码一致后确认。详见 被扫码配对。
- 设 Face ID：在这个浏览器里点「设置 Face ID」。朋友的电脑没有指纹时，按浏览器的提示改用你的手机确认。
- 开启并打开：在这个浏览器的「设置」→「安全」→「网页终端」点「开启并打开网页终端」，用 Face ID 确认，再输入一次 Agent J 主机的登录密码。见[在电脑浏览器里开启](#enable-browser)。
- 用：敲完命令点「结束」。
- 解绑：在你的手机上打开「遥控器管理」，把这台「解绑」。解绑的那一刻，它正开着的网页终端立刻关掉，里面还在运行的命令一起停下；它从名单上去掉，记住的电脑密码一起删除；之后这个浏览器再也打不开网页终端，要用只能重新配对。
还电脑之前，顺手清掉这个浏览器里遥控器网页的网站数据；不要让浏览器记住 Agent J 主机的密码。
Agent 能做什么
Agent 永远不能往终端里打字、发送命令，也不能打开网页终端的开关。它只能做两件事：
- 帮你打开终端、填好命令。 需要你亲自运行某条命令时（比如一条 sudo 命令），Agent 可以在你名单上、正在线的设备上打开终端（配对成手机的遥控器除外），命令已经填在输入框里：「Agent J 填好了一条命令，看清楚后按回车运行。」终端没开时，照样要你用 Face ID 打开。你已经在输入框里打了字的话，Agent 的命令会先放在一个小条里，等你点了才放进去。Agent 填的命令一字没改就发送时，页面总会再问一次「这条命令由 Agent 填写」，要 Face ID 确认。
- 读取输出。 不用你复制粘贴，Agent 可以读当前这次终端的命令和输出，或者上一次的（关闭后 30 分钟内）。这些只放在主机内存里，遮挡方式和[哪些内容会交给 AI](#what-the-ai-sees) 一样。你输给正在运行的程序的内容不在里面，临时允许的设备用的那次终端也不在里面。终端页上写着：「Agent J 能读到这里的输出，密码和密钥会被隐藏。」
Agent 在处理不是你发来的消息时（群聊、转发、好友），这两件事都做不了。Agent 用密钥卡向你要电脑登录密码或 sudo 密码，会被拒绝。
更多命令和参数见 agentj 命令参考。遥控器上其他设置见 使用手册。
The web terminal gives you the command line of the Agent J host (the computer Agent J is installed on) in a computer browser, like the web console of a cloud service: you type a line in the browser, the host runs it and the output shows in the browser. It lives in Settings → Safety → Web terminal.
It works only in a computer browser, that is, a remote opened in a browser on a computer. A phone shows one sentence only: For safety and convenience, the web terminal can only be used from a computer browser.
It is off by default. Switching it on takes you in person: Face ID plus the Agent J host's login password in a computer browser, or one command run at the host. The Agent, scheduled tasks and scripts cannot. Every open needs Face ID, lasts at most 15 minutes by default and is recorded in full.
Once it is on, you can also run a command straight from the chat by starting the message with ! ([details](#bang)), let the computer remember its password so Face ID fills it in, on the Agent's admin-command cards too ([details](#computer-password)), and let the Agent open the terminal with a command filled in or read what it printed ([details](#agent)).
Where to find it
Open Settings → Safety. The Web terminal row is always there and tells you the next step:
- A computer browser, the terminal off or this browser not allowed yet: tap Switch on and open; see [Switch it on in a computer browser](#enable-browser). Below it, Or run this line on the Agent J host: shows
agentj terminal enablewith a button to copy it ([details](#enable)). - A phone: it says only For safety and convenience, the web terminal can only be used from a computer browser. There are no buttons.
- The Agent J host runs Windows (not inside WSL): it says this system is not supported yet and the next version will be. Today it works on Linux, macOS and Windows' WSL.
- This device has no Face ID yet: tap Set up Face ID first.
- Only a command line, no switch-on button: this remote did not record at pairing whether it is a computer or a phone (it was paired long ago, for example). Pair this remote again to switch it on right here, or run the line shown at the Agent J host; see [Who can use it](#who).
- Switched on and this browser may use it: tap Open web terminal.
Switch it on in a computer browser
- Open the remote in a computer browser and go to Settings → Safety → Web terminal. Tap Switch on and open.
- Confirm with Face ID.
- Type the Agent J host's login password once — the password you use to log in to that computer and for sudo. The host checks it with sudo. Switching on always takes a typed password, never a remembered one.
- When the password is right, the web terminal is switched on for this browser and opens straight away: you leave Settings and use it full screen in this window. The ✕ at the top right collapses it ([details](#full-screen)).
Every remote then gets a notice naming the device it was switched on from. When that device is a web-version remote, the notice also says: if this was not you, run agentj terminal disable on the Agent J host now.
The browser's guess of computer or phone only takes you to the right place. The Agent J host also checks, by the device type recorded at pairing, and refuses to open or switch on the terminal for a remote that paired as a phone. What really protects you are the locks: the signature, Face ID, the computer login password, the full recording and the time limits.
Switch it on at the Agent J host
The other way: in the Agent J host's own terminal, run:
agentj terminal enable- The host prints a 6-digit match code, and every paired remote (phones included) gets a card naming the devices that may use the terminal, the minutes per session and the same match code.
- Check that the digits match, then allow it on a remote that has Face ID set up and confirm with Face ID. If nobody confirms within 5 minutes, nothing changes.
- The computer browser on the list now shows Open web terminal under Settings → Safety.
What it needs:
- At least one paired computer browser with Face ID (or a fingerprint — a passkey). If none has it yet, tap Set up Face ID under Settings → Safety → Web terminal in that browser first.
- It runs on Linux, macOS and Windows' WSL; native Windows comes in the next version. A Mac has a few extra points: see [On a Mac](#macos).
- Your computer account must be able to use sudo, and sudo must ask for a password. With a sudo that needs no password (NOPASSWD), or an account that is not an administrator,
agentj terminal enablerefuses and says why: the web terminal uses your computer login password as a second lock.
Only you, typing in your own terminal, can run this. The Agent, scheduled tasks, scripts and the web terminal itself cannot. A remote can only switch it on for itself with Switch on and open, which also takes Face ID and the computer login password; a phone cannot.
With several computer browsers that have Face ID, pick one with --device (repeatable; a remote that paired as a phone cannot be picked). Change the minutes per session with --minutes (default 15, at most 60):
agentj terminal enable --device <device> --minutes 30agentj terminal status lists the switch, the devices on the list and whether each one has a remembered computer password.
On a Mac
When the Agent J host is a Mac, the web terminal works as on Linux: switched on only by you, Face ID on every open, a time limit, a recording of everything, a second confirmation for risky commands, and what you type is masked before it is recorded. What differs:
- Three more things before it can be switched on, and you are told which one is missing: your Mac account is an administrator (System Settings → Users & Groups says Admin); sudo does not use Touch ID or Apple Watch, or sudo would wait for a fingerprint on the Mac's own screen, which never comes when you are away; and the Command Line Tools are installed (run
xcode-select --installon the Mac), so that sudo in the web terminal can use the remembered computer password safely. Without them the terminal still works, but sudo says why and does not run. - The terminal uses your login shell: zsh by default, or the system's bash when your login shell is bash. It does not read start-up files such as
~/.zshrcor~/.bash_profile, so their aliases and functions are not there; the usual paths (including Homebrew's/opt/homebrew/bin) are on the PATH, and text is shown as UTF-8. - The command history is kept only in Agent J's data folder, never in
~/.zsh_history. Lines that look like a password, key or token, and lines starting with a space, never go into it. - A Mac has no isolated space like Linux's. The terminal runs as you — not as the Agent, and outside the Agent's fence; the gates above are what protect it.
Who can use it
Only devices on the list can open the web terminal. The one chosen at enable, or the browser that switched it on for itself, is yours.
When a friend (an engineer, say) helps you, do not hand over your device. Let them pair a browser on their own computer as a remote, with their own Face ID, then allow that remote for a while at the Agent J host:
agentj terminal allow <device> --hours 2--hours takes 1 to 24 (default 2); the permission ends by itself. A device allowed for a while never gets a remembered computer password: it types it on every open. agentj terminal deny <device> takes it off the list early. A remote that paired as a phone cannot be allowed.
A web-version remote also needs --allow-web. On such a device the Web terminal row says it is the web version. The reason: a tampered web page could borrow your Face ID. The confirmation card says so too.
agentj terminal allow <device> --allow-webOpening it and the password
- In a computer browser, go to Settings → Safety → Web terminal, tap Open web terminal, then Confirm with Face ID. Every open needs Face ID, even if you just used it.
- The first time on a device (unless Face ID can already fill it in, see [below](#computer-password)), the terminal page asks you to Type your computer login password — the password you use to log in to the Agent J host and for sudo. It is encrypted in the browser before it leaves and only the Agent J host can open it; it is never shown or kept on this device. Tap Send with Face ID.
- The host checks it and opens the terminal. The top shows the current folder, the time left and Recording.
Wrong passwords: 3 in a row on one device lock it for 15 minutes; 10 within an hour on the whole host lock it for an hour. Every wrong password is a notice on every remote. The computer's own system may count these failures toward its own lockout as well (pam_faillock on Linux, for example), so too many can also lock the computer's normal login for a while.
How the computer keeps the password
The computer keeps it in one of three ways; the Settings row says which in plain words:
| Way | What Settings says | When |
|---|---|---|
| Unlocked by your Face ID | Your computer password is stored encrypted; only your Face ID can unlock it. | This device's Face ID (passkey) supports it (preferred) |
| Encrypted on the computer | Your computer password is stored encrypted on the computer; it is used only after your Face ID. | The device does not support the first way, Isolated sandbox is on and Session mode is independent |
| This session only | You type the computer password each time you open it; it is cleared when you finish. | Everything else, and every device allowed for a while |
What each protects against:
- The first two: they protect against backups, offline copies and the Agent reading the disk directly; they do not protect against a program that can change Agent J's code or your user services. The stored password is encrypted: a copy or a backup cannot open it, and the Agent reading the file directly sees no plain text. But a program on the same computer that can change Agent J's own code or your user services could catch the password at the moment it is used.
- Encrypted on the computer is allowed only while Isolated sandbox is on and Session mode is independent. The moment you switch isolation off or move to a shared session, that copy is deleted and you type the password again next time.
- This session only: the password stays only in Agent J's memory on the computer and is cleared when the terminal closes; nothing is written to disk.
To make the computer forget the password for this device, tap Clear on this device under Settings → Safety → Computer password; to delete every remembered copy, run agentj terminal forget at the computer. After you change your login password, the old copy is deleted the next time sudo rejects it; type the new one at the next open.
The computer password: type it once, then Face ID
The first way above is a small password vault. Your computer password is stored only in encrypted form on the computer, never on a remote. Each device unlocks it with its own Face ID or fingerprint.
- The first time on a device, type the password once (in the terminal, or on an admin-command card). After that, Face ID on that device fills it in.
- Another device: open Settings → Safety → Computer password on it and tap Use it on this device too. Confirm with Face ID, then, within 2 minutes, tap Agree with Face ID on a device that can already use it. That card shows the new device's name, ID, passkey, pairing date and type: agree only if you know the device. Every remote gets a notice afterwards. You can also simply type the password once on the new device.
- The Agent's admin-command cards (sudo): tap Fill in the computer password with Face ID. Or tap Or type the computer password and tick Remember it with Face ID (next time, just scan your face). The password is used for that one command only; the Agent gets the command's output, not the password. This works on a phone's admin-command cards too.
- A device whose Face ID cannot do this (Settings says so), or a device allowed only for a while, types the password each time.
- If you changed the password, the card says The remembered computer password no longer works (it may have changed). Type it once. This does not count as a wrong password.
It protects against the same things as above: backups, offline copies and the Agent reading the files; not against a program that can change Agent J's code or your user services.
The Computer password row in Settings says whether this device can use it. Clear on this device removes only this device's access.
Typing commands: line mode
Version 1 is line mode: you write a whole line in the browser and tap Send; only then does the host run it.
- A line is at most 4096 bytes, with no Tab and no line break. There is no Tab completion.
- There are two control keys only: Ctrl+C (interrupt the running program) and Ctrl+\ (force-quit it). No Ctrl+D, no Ctrl+Z.
- Full-screen programs such as
vim,toporlessdo not work. Usecat,headortailto read a file. - Some programs notice they are not writing to a screen and hold their output until a large block is ready, so they look stuck. Put
stdbuf -oLin front of the command to make it print line by line. - Error output and normal output arrive together, in order. Colours and other control codes are removed, and anything that looks like a password or key is hidden on the host before it reaches the browser. When output comes too fast, the excess is left out with a note of how many bytes.
- The browser keeps the output in memory only; it is gone when you close the terminal and is never saved on this device.
Never type passwords into the terminal
The web terminal is not a real screen. When a program asks for a password (ssh, git asking for credentials, passwd), it reads the next whole line you send, as plain text. So do not type any password here. The note under the input box says the same.
sudo is the exception: when you use sudo in the terminal, the page shows Allow sudo with Face ID with the command sudo will really run and the line you typed, and warns you when the two differ. Allow with Face ID hands the remembered password to this one sudo; Don't allow makes sudo fail, and so does no answer within 60 seconds. The password never appears in a line you send.
A line you send while a program is running goes to that program. The recording keeps only a placeholder for such a line, not its text, and it does not enter the command history.
The web terminal keeps its own command history on the host, readable only by you. A line that starts with a space, a repeat of the line before, and any line that looks like it sets a key or password (such as TOKEN=…, --password=…, Bearer …, https://user:password@…) is not kept. The history of your usual terminal is never read or copied in.
Risky lines are confirmed again
The host looks at every line before it runs. High-risk commands such as deleting files, and lines that start a new shell or interpreter, run a script file, or use ssh, su, source or eval, first show This line needs your OK with the reason. They run only after you tap Run and confirm with Face ID; without that, or after 120 seconds, they do not run. Only the device using the terminal can answer, and no automatic approval applies.
To be honest: this step only catches slips; it does not stop someone who already holds the session. A command can be put together across several lines — a variable, a file written and then run — and the host will not always recognise it. What really protects you are the locks before it: switching on takes you in person, the list, Face ID on every open, the time limits and the full recording.
When it closes by itself
The terminal closes, and stops everything still running in it, when:
- the time limit is reached (15 minutes by default; set with
--minuteswhen you switch it on at the host, at most 60); - no line has been sent for 5 minutes;
- the browser has been on another tab or minimised for more than 60 seconds;
- the connection drops;
- you tap Stop everything, or Agent J on the host stops;
- you run
agentj terminal disableat the host, or take this device off the list withdeny; - you tap End.
Every remote gets a notice when it opens and when it closes, with the reason and the minutes used. Only one device can use the web terminal at a time.
Full screen, collapse, copy and screenshot
The terminal opens full screen: light text on a dark background. When you open it from Settings, you leave Settings and use it full screen in this window. (The page is full screen; full-screen programs such as vim still do not work.)
- Collapse it: click the ✕ at the top right, press Esc, or drag the handle at the top down. Double-clicking does nothing, so it never disturbs a running program.
- Collapsing does not end it. The session keeps running with the same time limits, and a chip above the message box shows Terminal · N min left; tap Open to go back. A sudo or confirmation card brings the terminal back by itself.
- Copy output copies the output on the page.
- Screenshot to chat turns the visible output into a picture and puts it in your attachments. It is sent only when you send the message.
- Tap End to close it.
Run a command from the chat with !
In the message box in a computer browser, type ! and then the command, for example !df -h, and send. It is not sent to Agent J as chat: it runs as one line in the web terminal.
- If the terminal is not open on this device, you are first asked to open it with Face ID. It then stays collapsed in the background.
- A result card in the chat shows the output; Show all opens long output.
- The command and its output then go to Agent J, which carries on from there.
Everything above applies: risky lines are confirmed, sudo asks for Face ID, the time limits and the recording stay the same. One ! command runs at a time. If the output is not finished after 120 seconds, the card shows the output so far.
If the terminal is off or this device is not on the list, a card explains how to switch it on; on a phone, the card says the web terminal can only be used from a computer browser. To send an ordinary message that starts with !, put a space before it. ! works only in the Agent J app and web page, not in Telegram or e-mail.
What reaches the AI
The output of a ! command, and what the Agent reads with agentj terminal output, go into the Agent's conversation, so they are sent to your AI model provider. Before that, the computer hides more: the value after names such as KEY, TOKEN, SECRET or PASS, the word after -p or --password, and passwords inside links. The card says how many items it hid, for example 3 items that look like passwords or keys are hidden.
The hiding is not perfect. It also hides some harmless things (in mkdir -p dir, dir is hidden), and it can miss a secret in an unusual format. So do not print passwords or keys in the terminal (no cat .env).
The recording
Every session is recorded: the output, already masked, and each line you sent, masked the same way. The recording stays on the host in Agent J's data folder, readable only by your computer account, and is deleted after 30 days. It is never uploaded anywhere and never goes into a support report. The activity log also notes which device opened and closed it and when, plus the risky lines and sudo calls you confirmed — as fingerprints only, never the command text.
To see the recent log and the recording files at the host:
agentj terminal logsIt is not a way in when the connection is down
The web terminal uses the same encrypted connection between the remote and the Agent J host. When that connection is down, the terminal is down too. When a remote cannot reach the host:
- Use Emergency repair on the remote, ① then ②.
- Run
agentj doctor --reconnectat the host. - Ask someone at the host to run
curl -fsSL https://agentj.app/rescue | sh.
See Phone grey or disconnected?.
Under Emergency repair → Commands on the Agent J host, each command also gets Open in terminal while the terminal is on and this device is on the list: it puts the command into the web terminal, and it runs only when you press Enter.
Switching it off
- Switch the whole feature off and delete every remembered password:
agentj terminal disable- Take one device off the list:
agentj terminal deny <device>- Delete only the remembered computer passwords and keep the list:
agentj terminal forgetUnpairing a remote, or removing its Face ID, also takes it off the list and deletes its remembered password.
Borrowing a friend's computer in an emergency
You cannot carry the Agent J host around, but there is a browser everywhere. When you urgently need a few commands on the host, borrow a computer's browser for a while and unbind it afterwards:
- Pair by scanning: on the borrowed computer, open the remote web page in a browser and let it show its pairing QR code; scan it with your paired phone, check that both 6-digit match codes are the same, and confirm. See Be scanned.
- Set up Face ID: tap Set up Face ID in that browser. If your friend's computer has no fingerprint reader, follow the browser's prompt to confirm with your phone instead.
- Switch on and open: in that browser go to Settings → Safety → Web terminal, tap Switch on and open, confirm with Face ID and type the Agent J host's login password once. See [Switch it on in a computer browser](#enable-browser).
- Use it, and tap End when you are done.
- Unbind: on your phone, open Remotes and Unbind this one. The moment you do, its open web terminal closes and every command still running in it stops; it leaves the list and its remembered computer password is deleted; from then on that browser cannot open the web terminal at all — it would have to be paired again.
Before you hand the computer back, clear this browser's site data for the remote web page, and do not let the browser save the Agent J host's password.
What the Agent can do
The Agent can never type into the terminal, send a line or switch the terminal on. It can do two things:
- Open it for you with a command filled in. When you need to run something yourself (a sudo command, say), the Agent can bring up the terminal on your allowed devices that are online (never on a remote that paired as a phone), with the line already in the input box: Agent J filled in a command. Check it, then press Enter to run it. A closed terminal still needs your Face ID to open. If you had already typed something, the Agent's line waits in a chip until you tap it. When you send the Agent's line without changing it, the page always asks again, This command was filled in by the Agent, with Face ID.
- Read the output. Instead of asking you to paste it, the Agent can read the lines and output of the current session, or of the last one for up to 30 minutes after it closed. This is kept only in memory on the host, hidden the same way as in [What reaches the AI](#what-the-ai-sees). A line you type into a running program is not included, and nor is the session of a device allowed only for a while. The terminal page says so: Agent J can read the output here; passwords and keys are hidden.
Neither works while the Agent is handling a message that did not come from you (a group, a forwarded message, a friend). If the Agent asks you, through a key card, for your computer login password or sudo password, that request is refused.
More commands and options: agentj command reference. Other remote settings: User guide.