Skip to Content
heel

Get started

Install heel, start it, connect an account and give an agent its token.

Install

npm install -g useheel                      # Node 26.13 or later; installs the heel command
docker pull ghcr.io/akhileshrangani4/heel    # or run the OCI image

Quick start

export HEEL_HOME=~/.heel                    # heel's config, keys and database
heel vault init                             # creates the master key: back it up
heel serve                                  # agents on :7300, approvals on :7301

In a second terminal, with the same HEEL_HOME:

heel user enroll owner                      # open the link and register your passkey
gh auth token | heel connect github --as github --credential-stdin
heel agent add my-agent                     # prints the agent's token and MCP URL

Then write your rules to $HEEL_HOME/rules/owner.yaml. A call no rule matches is denied:

rules:
  - match: { kind: read }
    then: allow
  - match: { action: github.merge, repo: { one_of: [acme/web] }, checks: passing }
    then: ask

Run heel rules check to validate them. Then point your agent's MCP client at the printed URL, with Authorization: Bearer <token>. Reads go through, merges to acme/web with passing checks wait for your approval on the approval page, and everything else is denied.

To run heel as a server with Docker, see Running heel.

What it does

  • Rules on arguments. One YAML file covers MCP, HTTP and CLI calls. Rules can check recipients, accounts, repos, CI status and threads, and count items per run or per hour. The first match decides, and nothing matched means deny. See rules.
  • Hiding. Mail from people you name, password resets and login codes never reach the agent. See hiding.
  • Approvals the agent can't answer. An ask waits for its owner, who approves with a passkey after seeing the full arguments. An approval can become a grant. See approvals.
  • Pause. One command or one tap stops an agent, an account, or everything. See pause.
  • Every surface. Built-in definitions for Gmail, Outlook, Calendar, GitHub, Slack, Linear, Notion and Stripe. Any MCP server, any HTTP API with an OpenAPI file, and any CLI through heel run. Code mode runs scripts in a sandbox. See how it works.
  • No model decides a live call. Rules, grants and people do. See why heel.

On this page