# emisar

**Leave the agent working. Keep production authority bounded.**

emisar gives MCP-capable agents a catalog of declared infrastructure actions
instead of a shell. Policy decides what runs, what waits for a person, and what
is denied. A small outbound-only runner checks the action again on the host
before it executes anything.

Start with the public pack catalog and let emisar suggest the packs that match a
host. Add your own actions without adding another MCP server to every
client.

## Start with one host

You need an [emisar account](https://emisar.dev/sign_up), a Linux host with
systemd, and `sudo`. GitHub CLI with `gh attestation verify --bundle` checks the
release signature. Without GitHub CLI, the installer asks before it continues
with only the checksum. With `--yes`, it warns and continues. Allow outbound
HTTPS to `emisar.dev:443`, `registry.emisar.dev:443`,
`tuf-repo-cdn.sigstore.dev:443`, and `tuf-repo.github.com:443`. The last two
serve the public trust roots used to authenticate release checksums. No GitHub
login is required.

GitHub is the optional release fallback. If you want that fallback, also allow
`api.github.com:443`, `github.com:443`, and
`release-assets.githubusercontent.com:443`.

1. In the console, choose **Connect a runner**. Copy the generated command;
   it contains a fresh, single-use enrollment key.
2. Run it on the host:

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

   The installer authenticates the signed release checksum and verifies the
   archive against it. It then creates the service, installs host-matched
   starter packs, and starts the runner.
3. Confirm the runner is online in the console, then dispatch
   `linux.uptime` with a reason. You are done when the output appears and the
   run is present in the audit trail.
4. Open **AI agents** and connect your client. Remote MCP clients use OAuth;
   local stdio clients can use the `emisar-mcp` bridge and its browser approval
   flow.

The complete walkthrough, including expected output and troubleshooting, is at
[emisar.dev/docs/quickstart](https://emisar.dev/docs/quickstart). An agent can
perform and certify the setup with the public
[`install-emisar` skill](skills/install-emisar/SKILL.md).

## How an action runs

```text
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
```

The action pack defines the contract: the executable, argv shape, argument
schema, risk, timeout, output limits, redaction, and side-effect description.
The model selects from that contract; it does not invent a command line for the
runner to execute.

Adding a pack adds capabilities behind the same MCP surface. Operators do not
need to deploy another tool server or reconfigure every agent when the catalog
changes.

## What holds the boundary

- The runner opens an outbound TLS WebSocket and exposes no inbound listener.
  Commands return through that established connection.
- Cloud input is limited to declared actions and typed, schema-bounded
  arguments. The runner rejects unknown actions and arguments.
- Packs are content-addressed: a hash of their contents identifies them. The
  control plane pins the trusted pack hash, and the runner recomputes it from
  disk before execution. New or changed custom packs wait for trust.
- The control plane evaluates runner scope, risk policy, action overrides,
  standing grants, and conditional approval before dispatch.
- On the host, the runner clamps execution options to the pack's limits and
  runs the declared binary and argv. The runner redacts output before it leaves
  the host, and Emisar keeps the redacted output in run history.
- The control-plane audit includes denied and pending requests. Every runner
  also writes its execution attempts and local refusals to a hash-chained JSONL
  journal.
- A runner can optionally require bridge-attested dispatch: intent signed by the
  customer-authorized MCP bridge with an Ed25519 or ECDSA P-256 leaf key. The
  control plane then cannot invent or widen a permitted call.

Read the exact guarantees, limitations, and threat model in
[`.agent/kb/specs/security-model.md`](.agent/kb/specs/security-model.md).

## What emisar is not

- It is not a sandbox or process isolator. We recommend using one, such as
  [coop](https://github.com/AndrewDryga/coop).
- It is not a generic `execute(command)` tool or a replacement for SSH.
- It does not replace OS least privilege, change management, or configuration
  management.
- It does not make a permitted destructive action harmless. The safety boundary
  is only as strong as the actions, pack trust, policy, runner configuration,
  and host permissions in use.

The staging-only `shell` pack is the explicit break-glass (emergency-only)
exception to the declared-action model. It is critical-risk, default-denied,
never suggested, and should not be installed on production runners.

## Find the right surface

| Goal | Start here |
| --- | --- |
| Install, upgrade, harden, or diagnose a host | [`runner/README.md`](runner/README.md) |
| Connect Claude, ChatGPT, Cursor, Codex, or another MCP client | [Connect a CLI agent](https://emisar.dev/docs/connect-cli-agent) |
| Inspect or develop the stdio bridge | [`mcp/README.md`](mcp/README.md) |
| Browse, install, or author action packs | [`packs/README.md`](packs/README.md) |
| Let an agent install emisar, connect a client, or author a pack | [`skills/README.md`](skills/README.md) |
| Review architecture and trust boundaries | [`.agent/kb/architecture.md`](.agent/kb/architecture.md) |
| 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) |
| Contribute to the control plane | [`portal/README.md`](portal/README.md) |
| Review the production GCP infrastructure | [`infra/README.md`](infra/README.md) |

## Repository layout

```text
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
```

Each top-level project has its own `AGENTS.md` with its architecture, security
rules, and verification gate. Run `./run help` for the complete list of
contributor commands.

## Develop locally

The recommended path needs only [Coop](https://coop.dryga.com) and Docker on the
host. It installs every tool version the repository pins in the isolated project
image:

```sh
./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
```

Then, inside the shell:

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

For native development, install the exact versions in `.tool-versions` with
asdf. You also need Git, Coop, Docker, the PostgreSQL client, ShellCheck, jq,
GNU Bash (with `read -N`), GNU coreutils, Chrome/Chromium, and ImageMagick. On
macOS, Apple's bundled Bash and BSD utilities cannot run all pack regression
checks:

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

`./run setup` checks all prerequisites before starting services; `./run
doctor` reports every detected version and any mismatch to fix. On macOS,
run `./run certs trust` once for this workspace after setup.

The fast loop runs Phoenix in the current environment and keeps only PostgreSQL
and Keycloak in the workspace-isolated Coop dependency stack.

`./run urls` prints this workspace's distinct Portal, metrics, Postgres, and
Keycloak URLs. Coop forks inherit the same setup but receive different ports and
volumes. Setup, serve, and reset never apply seeds unless you ask for them.

Use `./run status` for a read-only view of the current workspace,
`./run logs [db|keycloak]` for its exact sidecar logs, and `./run psql` for its
development database. Every canonical gate (`./run gate <project>`) prints its
current phase and elapsed time; a failure names the phase that stopped it.

The root `docker-compose.yml` remains the slower packaged topology with the
release Portal image, seeded demo data, three runners, MCP, and signing. Start it
with `./run smoke`; it serves <http://localhost:4010>. See
[`portal/README.md`](portal/README.md) and [`dev/README.md`](dev/README.md).

## License

This repository is dual-licensed:

- `runner/`, `mcp/`, and `packs/` are open source under the
  [Apache License 2.0](runner/LICENSE). You can inspect, build, package, and
  operate the on-host components independently.
- Everything else, including `portal/`, is source-available under the
  [Business Source License 1.1](LICENSE.md). Non-production use is free.
  Production use is permitted only as needed to operate the Apache-licensed
  components or the hosted service under the Additional Use Grant. Other
  production use requires a commercial license. Each version converts to
  Apache 2.0 on its Change Date.

See [contributing](.github/CONTRIBUTING.md), [security](.github/SECURITY.md),
and [the CLA](.github/CLA.md). For commercial licensing, contact
`licensing@emisar.dev`.