Skip to content
Back to search

emisar

Let AI agents investigate and operate infrastructure through declared actions, bounded by policy and host-side checks. Approvals when required, with an audit trail. By Protectorate.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/andrewdryga/emisar with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/andrewdryga/emisar'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andrewdryga--emisar/badge.svg)](/listings/andrewdryga--emisar)

HTML

<a href="/listings/andrewdryga--emisar"><img src="/api/listings/andrewdryga--emisar/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 225 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # emisar
  2. **Leave the agent working. Keep production authority bounded.**
  3. emisar gives AI agents remote access to infrastructure through CLI or MCP.
  4. You choose the actions they can use. Your policy decides what runs automatically,
  5. what needs approval, and what is denied. A small runner connects out from each
  6. host and checks every request before running it. Agents call these actions
  7. without receiving a general production shell.
  8. Start with the public pack catalog and let emisar suggest the packs that match a
  9. host. Add your own actions without adding another MCP server to every
  10. client.
  11. ## Start with one host
  12. You need an [emisar account](https://emisar.dev/sign_up), a Linux host with
  13. systemd, and `sudo`. GitHub CLI with `gh attestation verify --bundle` checks the
  14. release signature. Without GitHub CLI, the installer asks before it continues
  15. with only the checksum. With `--yes`, it warns and continues. Allow outbound
  16. HTTPS to `emisar.dev:443`, `registry.emisar.dev:443`,
  17. `tuf-repo-cdn.sigstore.dev:443`, and `tuf-repo.github.com:443`. The last two
  18. serve the public trust roots used to authenticate release checksums. No GitHub
  19. login is required.
  20. GitHub is the optional release fallback. If you want that fallback, also allow
  21. `api.github.com:443`, `github.com:443`, and
  22. `release-assets.githubusercontent.com:443`.
  23. 1. In the console, choose **Connect a runner**. Copy the generated command;
  24. it contains a fresh, single-use enrollment key.
  25. 2. Run it on the host:
  26. ```sh
  27. curl -fsSL https://emisar.dev/install.sh \
  28. | sudo EMISAR_ENROLLMENT_KEY=emkey-enroll-... bash
  29. ```
  30. The installer authenticates the signed release checksum and verifies the
  31. archive against it. It then creates the service, installs host-matched
  32. starter packs, and starts the runner.
  33. 3. Confirm the runner is online in the console, then dispatch
  34. `linux.uptime` with a reason. You are done when the output appears and the
  35. run is present in the audit trail.
  36. 4. Open **AI agents** and connect your client. Remote MCP clients use OAuth;
  37. local stdio clients can use the `emisar-mcp` bridge and its browser approval
  38. flow. Agents that work in a terminal can also call tools directly with the
  39. [emisar-mcp CLI](https://emisar.dev/docs/mcp-reference#command-line).
  40. The complete walkthrough, including expected output and troubleshooting, is at
  41. [emisar.dev/docs/quickstart](https://emisar.dev/docs/quickstart). An agent can
  42. perform and certify the setup with the public
  43. [`install-emisar` skill](skills/install-emisar/SKILL.md).
  44. ## How an action runs
  45. ```text
  46. AI client
  47. | CLI or MCP: discover actions, request one with typed arguments
  48. v
  49. emisar control plane
  50. | authenticate, scope, apply policy, wait for approval when required
  51. v
  52. outbound-only runner
  53. | verify pack hash, validate arguments, enforce local limits
  54. v
  55. declared host command
  56. stream redacted output, journal the attempt, update fleet audit
  57. ```
  58. The action pack defines the contract: the executable, argv shape, argument
  59. schema, risk, timeout, output limits, redaction, and side-effect description.
  60. The model selects from that contract; it does not invent a command line for the
  61. runner to execute.
  62. Adding a pack adds capabilities behind the same MCP surface. Operators do not
  63. need to deploy another tool server or reconfigure every agent when the catalog
  64. changes.
  65. ## What holds the boundary
  66. - The runner opens an outbound TLS WebSocket and exposes no inbound listener.
  67. Commands return through that established connection.
  68. - Cloud input is limited to declared actions and typed, schema-bounded
  69. arguments. The runner rejects unknown actions and arguments.
  70. - Packs are content-addressed: a hash of their contents identifies them. The
  71. control plane pins the trusted pack hash, and the runner recomputes it from
  72. disk before execution. New or changed custom packs wait for trust.
  73. - The control plane evaluates runner scope, risk policy, action overrides,
  74. standing grants, and conditional approval before dispatch.
  75. - On the host, the runner clamps execution options to the pack's limits and
  76. runs the declared binary and argv. The runner redacts output before it leaves
  77. the host, and Emisar keeps the redacted output in run history.
  78. - The control-plane audit includes denied and pending requests. Every runner
  79. also writes its execution attempts and local refusals to a hash-chained JSONL
  80. journal.
  81. - A runner can optionally require bridge-attested dispatch: intent signed by the
  82. customer-authorized MCP bridge with an Ed25519 or ECDSA P-256 leaf key. The
  83. control plane then cannot invent or widen a permitted call.
  84. Read the exact guarantees, limitations, and threat model in
  85. [`.agent/kb/specs/security-model.md`](.agent/kb/specs/security-model.md).
  86. ## How emisar fits into your stack
  87. Use declared actions for agent access and SSH for interactive administration.
  88. Run the agent in a sandbox such as [co:op](https://github.com/AndrewDryga/coop),
  89. grant the runner the OS permissions its actions need, and ship lasting
  90. configuration changes through your deployment workflow.
  91. The runner executes permitted actions with its service user's OS permissions;
  92. it does not isolate those processes. Permitted destructive actions still have
  93. real effects. Review action definitions, pack trust, policy, runner settings,
  94. and host permissions together when deciding what the agent may do.
  95. The staging-only `shell` pack is the explicit break-glass (emergency-only)
  96. exception to the declared-action model. It is critical-risk, default-denied,
  97. never suggested, and should not be installed on production runners.
  98. ## Find the right surface
  99. | Goal | Start here |
  100. | --- | --- |
  101. | Install, upgrade, harden, or diagnose a host | [`runner/README.md`](runner/README.md) |
  102. | Connect Claude, ChatGPT, Cursor, Codex, or another MCP client | [Connect a CLI agent](https://emisar.dev/docs/connect-cli-agent) |
  103. | Inspect or develop the stdio bridge | [`mcp/README.md`](mcp/README.md) |
  104. | Browse, install, or author action packs | [`packs/README.md`](packs/README.md) |
  105. | Let an agent install emisar, connect a client, or author a pack | [`skills/README.md`](skills/README.md) |
  106. | Review architecture and trust boundaries | [`.agent/kb/architecture.md`](.agent/kb/architecture.md) |
  107. | Review protocol contracts | [`.agent/kb/specs/wire-protocol.md`](.agent/kb/specs/wire-protocol.md) and [`.agent/kb/specs/mcp-api.md`](.agent/kb/specs/mcp-api.md) |
  108. | Contribute to the control plane | [`portal/README.md`](portal/README.md) |
  109. | Review the production GCP infrastructure | [`infra/README.md`](infra/README.md) |
  110. ## Repository layout
  111. ```text
  112. portal/ Elixir/Phoenix control plane, operator console, website, and MCP API
  113. runner/ Go host runner and operator CLI
  114. mcp/ Go stdio-to-HTTP MCP bridge
  115. packs/ Versioned action-pack catalog
  116. skills/ Standalone customer skills for coding agents
  117. infra/ Production Terraform for emisar on Google Cloud
  118. run Root contributor command for development, tests, gates, and operations
  119. dev/ Development Compose topologies, images, configs, and fixtures
  120. tools/ Go implementations behind the contributor command and CI
  121. dist/ Tracked distribution packages plus ignored generated build output
  122. .agent/kb/ Repository architecture, specifications, runbooks, and rules
  123. ```
  124. Each top-level project has its own `AGENTS.md` with its architecture, security
  125. rules, and verification gate. Run `./run help` for the complete list of
  126. contributor commands.
  127. ## Develop locally
  128. The recommended path needs only [Coop](https://coop.dryga.com) and Docker on the
  129. host. It installs every tool version the repository pins in the isolated project
  130. image:
  131. ```sh
  132. ./run bootstrap # works before Go is installed
  133. coop build # build the pinned project image once
  134. coop run -- ./run setup # sidecars, deps, migrations, browser tooling
  135. coop shell # enter the development box
  136. ```
  137. Then, inside the shell:
  138. ```sh
  139. ./run seed # explicit, idempotent demo data
  140. ./run serve # live reload at the URL printed by Coop
  141. # or: ./run serve --iex
  142. ```
  143. For native development, install the exact versions in `.tool-versions` with
  144. asdf. You also need Git, Coop, Docker, the PostgreSQL client, ShellCheck, jq,
  145. GNU Bash (with `read -N`), GNU coreutils, Chrome/Chromium, and ImageMagick. On
  146. macOS, Apple's bundled Bash and BSD utilities cannot run all pack regression
  147. checks:
  148. ```sh
  149. brew install bash coreutils jq
  150. export PATH="$(brew --prefix coreutils)/libexec/gnubin:$(brew --prefix bash)/bin:$PATH"
  151. ```
  152. `./run setup` checks all prerequisites before starting services; `./run
  153. doctor` reports every detected version and any mismatch to fix. On macOS,
  154. run `./run certs trust` once for this workspace after setup.
  155. The fast loop runs Phoenix in the current environment and keeps only PostgreSQL
  156. and Keycloak in the workspace-isolated Coop dependency stack.
  157. `./run urls` prints this workspace's distinct Portal, metrics, Postgres, and
  158. Keycloak URLs. Coop forks inherit the same setup but receive different ports and
  159. volumes. Setup, serve, and reset never apply seeds unless you ask for them.
  160. Use `./run status` for a read-only view of the current workspace,
  161. `./run logs [db|keycloak]` for its exact sidecar logs, and `./run psql` for its
  162. development database. Every canonical gate (`./run gate <project>`) prints its
  163. current phase and elapsed time; a failure names the phase that stopped it.
  164. The root `docker-compose.yml` remains the slower packaged topology with the
  165. release Portal image, seeded demo data, three runners, MCP, and signing. Start it
  166. with `./run smoke`; it serves <http://localhost:4010>. See
  167. [`portal/README.md`](portal/README.md) and [`dev/README.md`](dev/README.md).
  168. ## License
  169. This repository is dual-licensed:
  170. - `runner/`, `mcp/`, `packs/`, `skills/`, and `dist/cursor-plugin/` are open
  171. source under the [Apache License 2.0](runner/LICENSE); the skills and the
  172. Cursor plugin carry their own copy ([skills](skills/LICENSE),
  173. [plugin](dist/cursor-plugin/LICENSE)). You can
  174. inspect, build, package, and operate the on-host components independently.
  175. - Everything else, including `portal/`, is source-available under the
  176. [Business Source License 1.1](LICENSE.md). Non-production use is free.
  177. Production use is permitted only as needed to operate the Apache-licensed
  178. components or the hosted service under the Additional Use Grant. Other
  179. production use requires a commercial license. Each version converts to
  180. Apache 2.0 on its Change Date.
  181. See [contributing](.github/CONTRIBUTING.md), [security](.github/SECURITY.md),
  182. and [the CLA](.github/CLA.md). For commercial licensing, contact
  183. `licensing@emisar.dev`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.