内容
# emisar
**批准的 AI 工具基础设施操作，强制在宿主上执行。**
emisar 是一个控制平面、仅限 outbound 的运行器和 MCP 桥接器，允许 AI 工具请求有限的、已声明的操作动作集，而无需接收原始 shell 或 SSH 访问权限。
状态：**活跃的私有测试版**。此 monorepo 包含完整的运行器、Phoenix 控制平面、公共网站和 MCP stdio 桥接器。托管的控制平面是当前支持的产品边界；自托管和隔离部署目前不可用。
## 它做什么
- 加载每个运行器上的版本控制、内容寻址的**动作包**。
- 通过 TLS websocket **向外**连接到控制平面 - 没有入站监听器。
- 当运行器宣传新的、自定义的或更改的包内容时，阻止调度，直到管理员信任哈希值。
- 通过 OAuth 连接远程 MCP 客户端，通过 `emisar-mcp` stdio 桥接器连接本地客户端。
- 应用每个用户的运行器范围、风险级别策略、动作覆盖、人工批准和可撤销的永久授权。
- 对于来自云的每个 `run_action` 消息：
1. 根据动作的声明模式重新验证参数。
2. 重新计算并验证受信任的包哈希值。
3. 将云提供的选项限制在动作的 `*_min`/`*_max` 界限内。
4. 通过 `os/exec` 使用 **argv 数组，而非 shell 字符串**执行。
5. 通过 websocket 流式传输行缓冲、编辑后的输出。
6. 为每次尝试在本地安全日志中写入一个哈希链接的 JSONL 事件。
## 它刻意不具备的功能
- 不是沙盒或进程隔离器。
- 不是任意远程 shell 或通用 `execute(command)` 工具。
- 不是 OS 级别的最少权限、进程隔离或客户变更管理控制的替代品。
- 不是 OSI 批准的开源软件。该存储库是**源代码可用**的，但受 [`LICENSE.md`](LICENSE.md) 的约束。
参见 [`docs/security-model.md`](docs/security-model.md)。
## 安装（生产环境）
从门户创建一个运行器，接收一个有范围的启动密钥和生成的安装命令。用于 Linux（systemd）和 macOS（launchd）的底层受监督的安装程序是：
```sh
curl -sSL https://raw.githubusercontent.com/andrewdryga/emisar/main/install.sh | sudo bash
```
这会下载最新的标记版本，验证 SHA256，创建专用的服务用户（Linux），安装 `/usr/local/bin/emisar`，在 `/etc/emisar/` 下生成一个配置文件骨架，并安装 systemd 单元或 launchd plist，带有 `Restart=on-failure` 监督和 `StartLimitBurst` 限制。
安装后，编辑 `/etc/emisar/config.yaml` 和 `/etc/emisar/runner.env`，如果门户生成的命令没有填充它们，然后启动服务。参见 [`docs/install.md`](docs/install.md)，了解升级、卸载、隔离安装和完整的运维命令。
## 快速开始（开发/本地）
命令从仓库根目录运行。运行器是其自己的 Go 模块，位于 `runner/` 下（参见下面的存储库布局）；构建它会将二进制文件放在 `bin/emisar`：
```sh
# 1. 构建运行器 + MCP 桥接器
(cd runner && go build -o ../bin/emisar .)
(cd mcp && go build -o ../bin/emisar-mcp .)
# 2. 验证捆绑的示例包
./bin/emisar pack validate ./packs/linux-core
./bin/emisar pack validate ./packs/cassandra
./bin/emisar pack validate ./packs/showcase
# 3. 查看运行器将向云广告的内容
./bin/emisar --config ./runner/examples/config.yaml state | jq
# 4. 在本地运行一个动作进行调试（绕过云）
./bin/emisar --config ./runner/examples/config.yaml \
action run linux.uptime --reason "smoke test"
# 5. 流式传输一个长时间运行的动作的输出
./bin/emisar --config ./runner/examples/config.yaml \
action run linux.journalctl --arg unit=docker --stream
# 6. 检查 JSONL 日志
./bin/emisar --config ./runner/examples/config.yaml events tail --lines 20
```
以守护进程模式运行（等待云命令）：
```sh
EMISAR_AUTH_KEY=emkey-auth-... \
./bin/emisar --config ./runner/examples/config.yaml connect
```
## 文档
| 文档 | 主题 |
| --------------------------------------------------- | ---------------------------------------------------- |
| [docs/architecture.md](docs/architecture.md) | 包布局、运行时管道、启动序列。 |
| [docs/install.md](docs/install.md) | 生产安装、监督操作、升级。 |
| [docs/security-model.md](docs/security-model.md) | 考虑和明确不考虑的威胁。 |
| [docs/signed-dispatch.md](docs/signed-dispatch.md) | 仅运行人类签名的动作（客户端证明的分派）。 |
| [docs/action-packs.md](docs/action-packs.md) | 如何编写一个包。 |
| [docs/cloud-boundary.md](docs/cloud-boundary.md) | 控制平面和运行器各自强制执行的内容。 |
| [docs/wire-protocol.md](docs/wire-protocol.md) | JSON 消息类型、连接生命周期、选项。 |
## 存储库布局
Monorepo 具有一个部署组件的文件夹，每个组件都有一个语言根目录。每个 Go 文件夹都是其自己的模块；Elixir 控制平面是一个 umbrella 项目。`go.work` 将两个 Go 模块绑定在一起，以便于编辑器和 CLI 使用。
```
portal/ Elixir/Phoenix 控制平面（umbrella）
apps/emisar/ 域上下文：账户、运行、策略、审计、计费
apps/emisar_web/ LiveView 仪表板 + 营销站点 + MCP HTTP API
runner/ Go 模块 — 主机运行器二进制文件
main.go, connect.go, … CLI（cobra）
internal/cloud wire 协议 + outbound websocket 客户端
internal/engine 动作运行时（验证 → 限制 → 执行 → 编辑 → 日志）
internal/packs 包加载器 + 内存注册表
internal/executor exec/script 进程运行器（行缓冲流式传输）
internal/validation 参数模式强制执行
internal/expressions 小型 argv 替换模板引擎
internal/redact 输出编辑
internal/audit 哈希链接的 JSONL 事件日志
internal/config 配置加载器
pkg/actionspec 动作规范类型（YAML 模式）
pkg/packspec 包清单类型
examples/config.yaml 示例运行器配置
mcp/ Go 模块 — stdio MCP 桥接器，用于 Claude Code / Cursor / 等
packs/ 动作包目录（YAML）— linux-core, cassandra, docker, + 70 多个；由运行器 + 门户消耗
docs/ 架构、安全、签名调度、动作包、云边界、线路协议
docker-compose.yml 完整本地栈：Postgres、门户、种子器和运行器
install.sh 监督安装（systemd / launchd）— 对 tarball 运行
```
## 许可证
该存储库是**源代码可用**的，但不是 OSI 批准的开源软件。
代码可用，用户可以检查、评估、运行允许的内部使用、了解其工作原理并贡献改进。但不得用于克隆产品、运营竞争服务、商业重新分发、AI 训练、模型微调、嵌入式语料库、清洁室复制或构建替代产品。
参见：
- [`LICENSE.md`](./LICENSE.md)
- [`AI-USE-POLICY.md`](.github/AI-USE-POLICY.md)
- [`CONTRIBUTING.md`](.github/CONTRIBUTING.md)
- [`CLA.md`](.github/CLA.md)
- [`NOTICE.md`](.github/NOTICE.md)
- [`SECURITY.md`](.github/SECURITY.md)
对于商业许可、托管使用、AI 权限或其他权利，请联系 `licensing@emisar.dev`。
