Quickstart

Zero to your first audited action in about five minutes. You'll install the runner on a Linux host, watch it connect, run linux.uptime — gated by policy, recorded in the audit trail — and then point your LLM at the same catalog.

Before you start, you need:

A Linux host with systemd — a VM, a cloud instance, or bare metal. (The default installer sets up a systemd service; containers work too — see Containers & Kubernetes.)
sudo on that host.
Outbound HTTPS to emisar.dev:443 for the runner (it dials out; nothing listens on the host, so there's no inbound port to open), plus api.github.com and github.com for the installer — it downloads the runner release and checksums from GitHub.

1. Create your account#

2. Install the runner#

In the dashboard, click Connect a runner. emisar shows a one-line command carrying a single-use enrollment key (emkey-enroll-…, shown once — copy it now). Run it on your host:

shell

$ curl -sSL https://emisar.dev/install.sh \
    | sudo EMISAR_ENROLLMENT_KEY=emkey-enroll-… EMISAR_URL=https://emisar.dev bash

Verify this download first

The installer checks the checksum itself; to prove the binary before it runs as sudo, download it and run these first — a green check names our source repository and the release workflow that built it.

shell

# provenance — built by our workflow, from our source
$ gh attestation verify emisar-<version>-linux-amd64.tar.gz --owner andrewdryga
# checksums — the bytes match what we published
$ sha256sum -c SHA256SUMS

More on the signing pipeline: Release integrity.

What does the install script do?

It's a plain, readable shell script — read it first if you'd rather. It:

— verifies the download's SHA-256;
— creates a dedicated emisar system user and an emisar.service systemd unit (Restart=on-failure);
— bakes the key and URL into /etc/emisar/runner.env;
— installs the host-matched starter packs (on a typical Linux + systemd host: linux-core, debugging, and systemd-deep);
— starts the service, which dials out to the control plane over WSS.

3. Watch it connect#

The moment the runner connects, the dashboard follows on its own — your host appears under Runners, online, advertising its action catalog. On the host you can watch the same thing:

shell

$ journalctl -u emisar -f
level=INFO msg=cloud.connected actions=89 packs=4 inflight_runs=0

The stock linux-core pack is trusted automatically — its bytes match the catalog emisar publishes, so the hash auto-pins as trusted. (A custom or edited pack lands as pending instead and waits for one click on the Packs page before anything can dispatch it. That's the drift guard.)

4. Run your first action#

Open the runner, pick linux.uptime, add the required reason (one line — it's logged), and Dispatch. The output streams back live:

output

 14:32:07 up 18 days,  4:01,  load average: 0.42, 0.51, 0.48

linux.uptime is low risk, so the default policy runs it on the spot. A high-risk action — killing a process, restarting a service — would stop here for a human approval instead. Either way the run is now in the searchable cloud audit and the runner's hash-chained journal, tagged with your reason.

5. Point your LLM at it#

In the dashboard, open LLM agents and pick your client. Claude.ai and ChatGPT connect over remote MCP with OAuth; local clients — Claude Code, Cursor, Zed, Copilot CLI, and ten more — run a one-line installer that opens a browser approval and writes a scoped key into the client's config, so the secret never touches your clipboard.

Your model now has twelve stable tools and sees only the packs, actions, and runners in its scope. Ask "what's the load on web-01?" and it runs linux.uptime; ask it to restart a service and that high-risk action stops for your approval. Full walkthrough: /docs/connect-an-llm.

Optional: stop the per-tool prompts

Most clients ask "allow this tool?" the first time a model calls one. emisar already gates every action server-side — per-account policy, and human approval on risky ones — so that client prompt is redundant for emisar's tools. You can safely tell your client to stop prompting for the emisar MCP server: it only silences the client's prompt. A risky action still pauses for approval at emisar, and an out-of-policy one is still denied — auto-permitting in the client never bypasses emisar's gate.

— Claude Code — add "mcp__emisar__*" to permissions.allow in ~/.claude/settings.json.
— Gemini CLI — set "trust": true on the emisar server in ~/.gemini/settings.json.
— Grok CLI — add "MCPTool(emisar__*)" to [permission].allow in ~/.grok/config.toml.
— Cursor, Codex CLI — Cursor approves globally through agent auto-run; Codex can trust only emisar with default_tools_approval_mode = "approve" under [mcp_servers.emisar]. The LLM agents page has the exact per-client steps.

6. The workflow we recommend#

emisar is built for the incident, not the steady state. What it is not is your configuration manager. Standing changes an agent makes on a live host are how you get drift nobody can reproduce.

So the durable pattern pairs the agent with your infrastructure-as-code:

The agent investigates through emisar and finds the root cause — reads run on policy, so this part is unattended and on the record.
If it's on fire, it hot-patches through one gated action to contain it — approved by a human, audited.
Then it writes the durable fix as code — Terraform, Ansible, a Kubernetes manifest, whatever your fleet runs — and hands you a change you review and apply through your normal pipeline.

See it end to end on a real incident: the 33-hour wipe.

What you just set up.

A finite, reviewed action catalog sitting between an AI agent and your host — instead of an SSH key and a prayer. The model can only call what you declared, risky calls stop for a human, known secrets are redacted before they leave the box, and there's a searchable audit of who ran what, and why.

Runner not showing up?

Check journalctl -u emisar -f on the host. The two usual causes are a stale enrollment key (mint a fresh one) and an outbound firewall blocking emisar.dev:443.

Connect a cloud LLM