{
  "markdown": "# emisar\n\n**Leave the agent working. Keep production authority bounded.**\n\nemisar gives MCP-capable agents a catalog of declared infrastructure actions\ninstead of a shell. Policy decides what runs, what waits for a person, and what\nis denied. A small outbound-only runner checks the action again on the host\nbefore it executes anything.\n\nStart with the public pack catalog, let emisar suggest the packs that match a\nhost, and add your own actions without adding another MCP server to every\nclient.\n\n## Start with one host\n\nYou need an [emisar account](https://emisar.dev/sign_up), a Linux host with\nsystemd, and `sudo`. GitHub CLI with `gh attestation verify --bundle` checks the\nrelease signature; without it the installer asks, or warns and continues when\nrun with `--yes`, on the checksum alone. Allow\noutbound HTTPS to `emisar.dev:443`, `registry.emisar.dev:443`,\n`tuf-repo-cdn.sigstore.dev:443`, and `tuf-repo.github.com:443`. The last two\nserve the public trust roots used to authenticate release checksums; no GitHub\nlogin is required.\n\nGitHub is the optional release fallback. To permit that fallback, also allow\n`api.github.com:443`, `github.com:443`, and\n`release-assets.githubusercontent.com:443`.\n\n1. In the console, choose **Connect a runner**. Copy the generated command;\n   it contains a fresh, single-use enrollment key.\n2. Run it on the host:\n\n   ```sh\n   curl -fsSL https://emisar.dev/install.sh \\\n     | sudo EMISAR_ENROLLMENT_KEY=emkey-enroll-... bash\n   ```\n\n   The installer authenticates the signed release checksum, verifies the\n   archive against it, creates the service, installs host-matched starter\n   packs, and starts the runner.\n3. Confirm the runner is online in the console, then dispatch\n   `linux.uptime` with a reason. You are done when the output appears and the\n   run is present in the audit trail.\n4. Open **LLM agents** and connect your client. Remote MCP clients use OAuth;\n   local stdio clients can use the `emisar-mcp` bridge and its browser approval\n   flow.\n\nThe complete walkthrough, including expected output and troubleshooting, is at\n[emisar.dev/docs/quickstart](https://emisar.dev/docs/quickstart). An agent can\nperform and certify the setup with the public\n[`install-emisar` skill](skills/install-emisar/SKILL.md).\n\n## How an action runs\n\n```text\nAI client\n    |  MCP: discover actions, request one with typed arguments\n    v\nemisar control plane\n    |  authenticate, scope, apply policy, wait for approval when required\n    v\noutbound-only runner\n    |  verify pack hash, validate arguments, enforce local limits\n    v\ndeclared host command\n       stream redacted output, journal the attempt, update fleet audit\n```\n\nThe action pack is the contract. It fixes the executable, argv shape, argument\nschema, risk, timeout, output limits, redaction, and side-effect description.\nThe model selects from that contract; it does not invent a command line for the\nrunner to execute.\n\nAdding a pack adds capabilities behind the same MCP surface. Operators do not\nneed to deploy another tool server or reconfigure every agent when the catalog\nchanges.\n\n## What holds the boundary\n\n- **No inbound runner listener.** The runner opens an outbound TLS WebSocket and\n  exposes no inbound listener; commands return through that established connection.\n- **Declared actions only.** Cloud input is limited to typed, schema-bounded\n  arguments. The runner rejects unknown actions and arguments.\n- **Content-addressed packs.** The control plane pins the trusted pack hash; the\n  runner recomputes it from disk before execution. New or changed custom packs\n  wait for trust.\n- **Policy before side effects.** Runner scope, risk policy, action overrides,\n  standing grants, and conditional approval are evaluated before dispatch.\n- **Host-side enforcement.** The runner clamps execution options to the pack's\n  limits and runs the declared binary and argv. Runner output is redacted before\n  leaving the host; Emisar retains the resulting redacted output in run history.\n- **Two records.** The control-plane audit includes denied and pending requests;\n  every runner also writes its execution attempts and local refusals to a\n  hash-chained JSONL journal.\n- **Optional bridge-attested dispatch.** A runner can require intent signed by\n  the customer-authorized MCP bridge with an Ed25519 or ECDSA P-256 leaf key,\n  so the control plane cannot originate or widen a permitted call.\n\nRead the exact guarantees, limitations, and threat model in\n[`.agent/kb/specs/security-model.md`](.agent/kb/specs/security-model.md).\n\n## What emisar is not\n\n- It is not a sandbox or process isolator. We recommend using one, such as\n  [coop](https://github.com/AndrewDryga/coop).\n- It is not a generic `execute(command)` tool or a replacement for SSH.\n- It does not replace OS least privilege, change management, or configuration\n  management.\n- It does not make a permitted destructive action harmless. The safety boundary\n  is only as strong as the actions, pack trust, policy, runner configuration,\n  and host permissions in use.\n\nThe staging-only `shell` pack is the explicit break-glass exception to the\ndeclared-action model. It is critical-risk, default-denied, never suggested,\nand should not be installed on production runners.\n\n## Find the right surface\n\n| Goal | Start here |\n| --- | --- |\n| Install, upgrade, harden, or diagnose a host | [`runner/README.md`](runner/README.md) |\n| Connect Claude, ChatGPT, Cursor, Codex, or another MCP client | [Connect a CLI agent](https://emisar.dev/docs/connect-cli-agent) |\n| Inspect or develop the stdio bridge | [`mcp/README.md`](mcp/README.md) |\n| Browse, install, or author action packs | [`packs/README.md`](packs/README.md) |\n| Let an agent install emisar, connect a client, or author a pack | [`skills/README.md`](skills/README.md) |\n| Review architecture and trust boundaries | [`.agent/kb/architecture.md`](.agent/kb/architecture.md) |\n| 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) |\n| Contribute to the control plane | [`portal/README.md`](portal/README.md) |\n| Review the production GCP infrastructure | [`infra/README.md`](infra/README.md) |\n\n## Repository layout\n\n```text\nportal/   Elixir/Phoenix control plane, operator console, website, and MCP API\nrunner/   Go host runner and operator CLI\nmcp/      Go stdio-to-HTTP MCP bridge\npacks/    Versioned action-pack catalog\nskills/   Standalone customer skills for coding agents\ninfra/    Production Terraform for emisar on Google Cloud\nrun       Root contributor command for development, tests, gates, and operations\ndev/      Development Compose topologies, images, configs, and fixtures\ntools/    Go implementations behind the contributor command and CI\ndist/     Tracked distribution packages plus ignored generated build output\n.agent/kb/ Repository architecture, specifications, runbooks, and rules\n```\n\nEach top-level project has its own `AGENTS.md` with its architecture, security\nrules, and verification gate. Run `./run help` for the complete contributor\ncommand surface.\n\n## Develop locally\n\nThe recommended path needs only [Coop](https://coop.dryga.com) and Docker on\nthe host. It installs every repository pin in the isolated project image:\n\n```sh\n./run bootstrap             # works before Go is installed\ncoop build                  # build the pinned project image once\ncoop run -- ./run setup     # sidecars, deps, migrations, browser tooling\ncoop shell                  # enter the development box\n```\n\nThen, inside the shell:\n\n```sh\n./run seed        # explicit, idempotent demo data\n./run serve       # live reload at the URL printed by Coop\n# or: ./run serve --iex\n```\n\nFor native development, install the exact versions in `.tool-versions` with\nasdf, plus Git, Coop, Docker, the PostgreSQL client, ShellCheck,\nChrome/Chromium, and ImageMagick.\n`./run setup` validates all prerequisites before starting services; `./run\ndoctor` reports every detected version and an actionable mismatch. On macOS,\nrun `./run certs trust` once for this workspace after setup.\n\nThe fast loop runs Phoenix in the current environment and keeps only PostgreSQL\nand Keycloak in the workspace-isolated Coop dependency stack.\n\n`./run urls` prints this workspace's distinct Portal, metrics, Postgres, and\nKeycloak URLs. Coop forks inherit the same setup but receive different ports and\nvolumes. Seeds are never applied by setup, serve, or reset unless explicitly\nrequested.\n\nUse `./run status` for a read-only view of the current workspace, `./run logs\n[db|keycloak]` for its exact sidecar logs, and `./run psql` for its development\ndatabase. Every canonical gate prints its current phase and elapsed time; a\nfailure names the phase that stopped it.\n\nThe root `docker-compose.yml` remains the slower packaged topology with the\nrelease Portal image, seeded demo data, three runners, MCP, and signing. Start it\nwith `./run smoke`; it serves <http://localhost:4010>. See\n[`portal/README.md`](portal/README.md) and [`dev/README.md`](dev/README.md).\n\n## License\n\nThis repository is dual-licensed:\n\n- `runner/`, `mcp/`, and `packs/` are open source under the\n  [Apache License 2.0](runner/LICENSE). You can inspect, build, package, and\n  operate the on-host components independently.\n- Everything else, including `portal/`, is source-available under the\n  [Business Source License 1.1](LICENSE.md). Non-production use is free.\n  Production use is permitted only as needed to operate the Apache-licensed\n  components or the hosted service under the Additional Use Grant; other\n  production use requires a commercial license. Each version converts to\n  Apache 2.0 on its Change Date.\n\nSee [contributing](.github/CONTRIBUTING.md), [security](.github/SECURITY.md),\nand [the CLA](.github/CLA.md). For commercial licensing, contact\n`licensing@emisar.dev`.\n",
  "bytes": 9878,
  "sha": "fce1237dc441b5b31ced858f4267d4d89bf31eedee5e5ddae6aa90464b523904",
  "repo_slug": "andrewdryga/emisar",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_emisar_emisar_8e04315f/readme"
}