emisar

emisar

让 Agent 持续工作，同时限定其对生产环境的操作权限。

emisar 为具备 MCP 能力的 Agent 提供已声明基础设施操作目录，而非 shell。策略决定哪些操作可以运行、哪些需要等待人员批准，以及哪些会被拒绝。一个仅向外发起连接的小型执行器会在主机上再次检查操作，然后才执行任何操作。

从公开的工具包目录开始，让 emisar 推荐适合主机的工具包。添加自己的操作，无需为每个客户端再添加一个 MCP 服务。

从一台主机开始

你需要一个 emisar 账户、一台运行 systemd 的 Linux 主机，以及 sudo。GitHub CLI 使用 gh attestation verify --bundle 检查发行版签名。如果没有 GitHub CLI，安装程序会在仅使用校验和继续之前征求许可。使用 --yes 时，它会发出警告并继续。允许出站 HTTPS 访问 emisar.dev:443、registry.emisar.dev:443、tuf-repo-cdn.sigstore.dev:443 和 tuf-repo.github.com:443。最后两个地址提供用于验证发行版校验和的公开信任根。无需登录 GitHub。

GitHub 是可选的发行版备用来源。如果你希望使用该备用来源，还需允许访问 api.github.com:443、github.com:443 和 release-assets.githubusercontent.com:443。

1. 在控制台中选择 Connect a runner。复制生成的命令；其中包含一个全新且仅可使用一次的注册密钥。

2. 在主机上运行该命令：

   curl -fsSL https://emisar.dev/install.sh \
     | sudo EMISAR_ENROLLMENT_KEY=emkey-enroll-... bash
   

   安装程序会验证已签名的发行版校验和，并据此验证存档。随后，它会创建服务、安装与主机匹配的入门工具包，并启动执行器。

3. 在控制台中确认执行器已上线，然后附上原因调度 linux.uptime。当输出出现，且运行记录显示在审计跟踪中时，即表示完成。

4. 打开 AI agents 并连接客户端。远程 MCP 客户端使用 OAuth；本地 stdio 客户端可以使用 emisar-mcp 桥接程序及其浏览器审批流程。

完整操作指南（包括预期输出和故障排除）请参阅 emisar.dev/docs/quickstart。Agent 可以使用公开的 install-emisar 技能执行并验证安装。

操作如何运行

AI client
    |  MCP: discover actions, request one with typed arguments
    v
emisar control plane
    |  authenticate, scope, apply policy, wait for approval when required
    v
outbound-only runner
    |  verify pack hash, validate arguments, enforce local limits
    v
declared host command
       stream redacted output, journal the attempt, update fleet audit

操作工具包定义了契约：可执行文件、argv 格式、参数架构、风险、超时时间、输出限制、脱敏规则和副作用说明。模型会从该契约中选择操作；它不会为执行器编造命令行。

添加工具包即可在相同的 MCP 接口后扩展功能。目录发生变化时，运维人员无需部署另一个工具服务，也无需重新配置每个 Agent。

边界如何保障安全

• 运行器会建立出站 TLS WebSocket 连接，且不开放任何入站监听器。 命令通过此已建立的连接返回。
• 云端输入仅限于已声明的操作和有类型、受架构约束的参数。运行器会拒绝 未知操作和参数。
• 操作包采用内容寻址：其内容的哈希值用于标识操作包。控制平面会固定受信任 操作包的哈希值，运行器会在执行前从磁盘重新计算该哈希值。新的或已更改的自定义操作包须等待信任确认。
• 控制平面会在分发前评估运行器范围、风险策略、操作覆盖项、 常设授权和条件审批。
• 在主机上，运行器会将执行选项限制在操作包的限制范围内，并运行已声明的 二进制文件及 argv。运行器会在输出离开主机前对其进行脱敏，Emisar 则会在运行历史中保留 脱敏后的输出。
• 控制平面审计日志会记录被拒绝和待处理的请求。每个运行器 也会将其执行尝试和本地拒绝记录到哈希链式 JSONL 日志中。
• 运行器可以选择要求经桥接器证明的分发：意图须由客户授权的 MCP 桥接器使用 Ed25519 或 ECDSA P-256 叶密钥签名。这样，控制平面就无法伪造或扩大获准调用。

请阅读 .agent/kb/specs/security-model.md，了解准确的保障措施、限制和威胁模型。

emisar 不是什么

• 它不是沙箱或进程隔离器。我们建议使用此类工具，例如 coop。
• 它不是通用的 execute(command) 工具，也不能替代 SSH。
• 它不能替代操作系统最小权限、变更管理或配置 管理。
• 它无法让已获准的破坏性操作变得无害。安全边界的强度取决于所用的操作、操作包信任、 策略、运行器配置和主机权限。

仅用于预发布环境的 shell 操作包是对已声明操作模型的明确紧急破例（仅限紧急情况）。 它属于严重风险，默认拒绝，绝不会被推荐，也不应安装在生产运行器上。

找到合适的入口

目标	从这里开始
安装、升级、加固或诊断主机	runner/README.md
连接 Claude、ChatGPT、Cursor、Codex 或其他 MCP 客户端	连接 CLI Agent
检查或开发 stdio 桥接器	mcp/README.md
浏览、安装或编写操作包	packs/README.md
让 Agent 安装 emisar、连接客户端或编写操作包	skills/README.md
查看架构和信任边界	.agent/kb/architecture.md
查看协议契约	.agent/kb/specs/wire-protocol.md 和 .agent/kb/specs/mcp-api.md
为控制平面贡献代码	portal/README.md
查看生产环境 GCP 基础设施	infra/README.md

仓库布局

portal/   Elixir/Phoenix control plane, operator console, website, and MCP API
runner/   Go host runner and operator CLI
mcp/      Go stdio-to-HTTP MCP bridge
packs/    Versioned action-pack catalog
skills/   Standalone customer skills for coding agents
infra/    Production Terraform for emisar on Google Cloud
run       Root contributor command for development, tests, gates, and operations
dev/      Development Compose topologies, images, configs, and fixtures
tools/    Go implementations behind the contributor command and CI
dist/     Tracked distribution packages plus ignored generated build output
.agent/kb/ Repository architecture, specifications, runbooks, and rules

每个顶层项目都有自己的 AGENTS.md，其中包含其架构、安全规则和验证门槛。运行 ./run help 查看完整的贡献者命令列表。

本地开发

推荐的方式只需在主机上安装 Coop 和 Docker。它会在隔离的项目镜像中安装仓库指定的所有工具版本：

./run bootstrap             # works before Go is installed
coop build                  # build the pinned project image once
coop run -- ./run setup     # sidecars, deps, migrations, browser tooling
coop shell                  # enter the development box

然后，在 shell 中：

./run seed        # explicit, idempotent demo data
./run serve       # live reload at the URL printed by Coop
# or: ./run serve --iex

如需原生开发，请使用 asdf 安装 .tool-versions 中指定的确切版本。你还需要 Git、Coop、Docker、PostgreSQL 客户端、ShellCheck、jq、GNU Bash（支持 read -N）、GNU coreutils、Chrome/Chromium 和 ImageMagick。在 macOS 上，Apple 随附的 Bash 和 BSD 工具无法运行所有 pack 回归检查：

brew install bash coreutils jq
export PATH="$(brew --prefix coreutils)/libexec/gnubin:$(brew --prefix bash)/bin:$PATH"

./run setup 会在启动服务前检查所有前置条件；./run doctor 会报告检测到的所有版本以及需要修复的不匹配项。在 macOS 上，完成设置后，请为此工作区运行一次 ./run certs trust。

快速开发循环会在当前环境中运行 Phoenix，并仅在工作区隔离的 Coop 依赖栈中运行 PostgreSQL 和 Keycloak。

./run urls 会打印此工作区独有的 Portal、metrics、Postgres 和 Keycloak URL。Coop 分支会继承相同的设置，但会使用不同的端口和卷。只有在你明确要求时，Setup、serve 和 reset 才会应用种子数据。

使用 ./run status 以只读方式查看当前工作区，使用 ./run logs [db|keycloak] 查看其对应的 sidecar 日志，使用 ./run psql 访问其开发数据库。每个规范门禁（./run gate <project>）都会打印当前阶段和耗时；发生故障时，会指出中断的阶段。

根目录下的 docker-compose.yml 仍保留速度较慢的打包拓扑，其中包含发布版 Portal 镜像、已填充种子数据、三个 runner、MCP 和签名。使用 ./run smoke 启动；服务地址为 http://localhost:4010。请参阅 portal/README.md 和 dev/README.md。

许可证

本仓库采用双重许可：

• runner/、mcp/ 和 packs/ 按 Apache License 2.0 开源。你可以独立检查、构建、打包和运行主机上的组件。
• 其他所有内容（包括 portal/）均以源代码形式提供，遵循 Business Source License 1.1。非生产用途免费。只有在 Additional Use Grant 允许的范围内，为运行 Apache 许可组件或托管服务而进行的生产用途才被许可。其他生产用途需要商业许可证。每个版本在其 Change Date 到期后转为 Apache 2.0。

请参阅贡献指南、安全政策和 CLA。如需商业许可，请联系 [email protected]。