Metadata-Version: 2.5
Name: ailinuxweb
Version: 0.1.0
Summary: A Linux web console for interactive AI CLI (Claude Code / Codex / opencode / cline) and SSH sessions.
Project-URL: Homepage, https://open-vsx.org/namespace/agentself
Author: agentself
License-Expression: MIT
License-File: LICENSE
Classifier: Framework :: Flask
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: cryptography==49.0.0
Requires-Dist: flask-socketio==5.6.1
Requires-Dist: flask==3.1.3
Requires-Dist: pyotp==2.10.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: python-socketio==5.16.3
Requires-Dist: pyyaml==6.0.3
Requires-Dist: qrcode==8.2
Requires-Dist: requests==2.34.2
Requires-Dist: simple-websocket==1.1.0
Description-Content-Type: text/markdown

# ailinuxweb

通过网页远程控制服务器上的 AI 编码 CLI(Claude Code / Codex / opencode / cline),以及一个直连本机的 SSH 终端。后端用伪终端实时转发,还原真实 CLI 交互——包括工具调用过程和权限确认。为手机浏览器优化。

`aiwinweb` 的 Linux 版:同一个思路,`aiwinweb` 面向 Windows,`ailinuxweb` 面向 Linux 服务器。

## 原理

- 后端用 Python 的 `pty` 模块起一个伪终端,在其中运行 `claude`(真实的交互式进程,不是 `-p` 单次问答)。
- Flask-SocketIO 把终端输出实时推送到网页,前端用 [xterm.js](https://xtermjs.org/) 渲染成真正的终端;网页里打的字通过 WebSocket 写回伪终端,效果等同于 SSH 进服务器敲 `claude`。
- 会话与网页连接解耦:断线后进程保留 `SESSION_GRACE_SECONDS` 秒(默认 20 分钟),期间刷新页面或换设备都能重新 attach 回同一个会话。

## 功能

**会话**
- 多引擎:`claude` / `codex` / `opencode` / `cline`,外加直连本机的 `ssh` 终端
- 断线宽限重连,多标签页/多设备 attach 同一会话
- 实时会话列表,可远程 kill
- 历史会话浏览、导出、导入,带回收站(误删可恢复)

**文件**
- 目录树浏览、路径自动补全
- 在线查看与编辑文件
- 上传(图片可直接贴进对话)、下载、新建目录
- 一键打包项目为 zip

**通知**
- Claude Code / Codex 各自独立的通知配置,任务完成 / 需要关注 / 异常结束时推送
- 对接 [notify-fusion](https://pypi.org/project/aiwinweb/) 真实 API(企业微信/钉钉/飞书/QQ)和 openclaw 网关两条通道
- Claude 侧原生 Hooks 管理(自动检测并迁移已有的手写 Hook),Codex 侧管理 `notify.sh` 脚本

**渠道切换**
- Claude Code:管理多套 `ANTHROPIC_BASE_URL`/`ANTHROPIC_MODEL`/API Key 配置,一键切换,直接写入 `~/.claude/settings.json` 的 `env` 块,对整台机器的 `claude` 都生效
- Codex:管理 `~/.codex/config.toml` 里的 `[model_providers.*]` 渠道,切换靠 `-c model_provider=...` 命令行参数临时覆盖,不动顶层默认值

**LiteLLM 本地控制台**
- 独立虚拟环境装 `litellm[proxy]`,YAML 管路由,API Key 单独加密存(不进 YAML)
- 网页里起停服务、看日志、发测试消息(Chat Completions / Responses API / Claude Messages 三种格式都支持)

**安全**
- 账号密码登录,密码仅存哈希(werkzeug),首次运行在终端里现场设置,不用额外跑脚本
- TOTP 两步验证(可选,扫码绑定)
- 登录失败限流:5 分钟内 5 次失败锁定 5 分钟
- 锁屏 PIN + 可信设备白名单,支持空闲自动锁,含伪装页面模式
- 登录有效期上限(默认 24 小时,到点强制重新登录)

**其他**
- 系统状态监控(CPU / 内存 / 磁盘)
- 服务自启动管理(systemd)
- 出站代理配置,网页里改完即时生效,无需重启,LiteLLM/Codex/OpenCode/Cline 各自独立勾选
- OpenAI 兼容的 API 中转入口(见下)

## 快速开始

```bash
pip install ailinuxweb
ailinuxweb
```

首次运行会在终端里现场提示设置登录密码(至少 6 位),保存后直接启动,默认监听 `http://0.0.0.0:8765`。所有本地状态(密码哈希、TOTP、会话数据、渠道配置……)存在 `~/.ailinuxweb/`,不跟包代码混在一起——升级 `pip install -U ailinuxweb` 不会丢数据。

访问 `http://<服务器IP>:8765` 登录后,在顶部填入要操作的项目路径(服务器上的绝对路径),点「启动会话」即可。手机访问时底部有常用控制键(Esc / Tab / 方向键 / Ctrl+C)和独立输入框,方便虚拟键盘下输入。

## 配置

配置项跟原来一致,写在 `~/.ailinuxweb/.env` 里(留空则用默认值),或者用环境变量覆盖。

| 变量 | 说明 |
|---|---|
| `AILINUXWEB_DATA_DIR` | 数据目录,默认 `~/.ailinuxweb` |
| `WEBUI_USERNAME` | 登录账号,默认 `admin` |
| `HOST` / `PORT` | 监听地址/端口,默认 `0.0.0.0` / `8765` |
| `DEFAULT_CWD` | 路径输入框的默认值 |
| `ALLOWED_BASE_DIR` | 限制只能选择该目录下的路径;**留空 = 整台服务器随便选** |
| `SESSION_GRACE_SECONDS` | 断线后会话保留秒数,默认 `1200` |
| `SESSION_LIFETIME_HOURS` | 登录有效期小时数,默认 `24` |
| `CLAUDE_BIN` / `CODEX_BIN` / `OPENCODE_BIN` / `CLINE_BIN` | 各引擎可执行文件路径,需自行先装好并登录 |
| `SSH_BIN` / `SSH_HOST` / `SSH_USER` / `SSH_PORT` | SSH 引擎,默认连本机 `127.0.0.1` |
| `CODEX_PROXY` / `AGENT_NO_PROXY` | 首次默认代理设置,之后能在网页 🔐 弹窗里改,改完即时生效 |

## ⚠️ 安全提示

**这个应用把一个能读写文件、执行任意命令的交互式 Shell 暴露到网络上。** 如果 `ALLOWED_BASE_DIR` 留空,暴露的就是整台服务器。请务必:

1. **设强密码**,并**开启 TOTP 两步验证**。仅靠密码不够。
2. **加 HTTPS**。用 Nginx / Caddy 反代 + 证书,并设 `FORCE_SECURE_COOKIE=1`。裸 HTTP 会让密码、TOTP 码、终端里的一切内容明文过网,只适合内网临时测试。
3. **收窄 `ALLOWED_BASE_DIR`** 到具体的项目父目录。
4. **在防火墙/安全组限制来源 IP**。内置的登录限流挡不住有耐心的攻击者。
5. **慎用 `CLAUDE_PERMISSION_MODE=bypassPermissions`**。它会关掉 Claude Code 执行动作前的所有确认。
6. **不用时关端口或停服务**。

`~/.ailinuxweb/` 下的所有文件(密码哈希、TOTP 种子、锁屏 PIN、SSH 密码、渠道 API Key……)都是本机私密数据,权限已设为仅当前用户可读写,不要打包分享给别人。

## 依赖

Flask 3.1 · Flask-SocketIO 5.6 · python-socketio 5.16 · simple-websocket 1.1 · python-dotenv 1.2 · pyotp 2.10 · qrcode 8.2 · cryptography 49.0 · requests 2.34 · PyYAML 6.0

## License

MIT
