Skip to content

Getting Started

This guide gets you from clone to first task, first approval, and first proof export.

Hermit is local-first. By default it keeps state under ~/.hermit, including configuration, tasks, artifacts, receipts, and memory.

2-Minute Experience

Try governed execution in under two minutes:

# 1. Install (3 seconds)
curl -fsSL https://raw.githubusercontent.com/heggria/Hermit/main/install-macos.sh | bash

# 2. Run a task (30 seconds)
hermit run "List the files in the current directory and summarize what you see"

# 3. Inspect the task record (30 seconds)
hermit task list
hermit task show <task_id>

# 4. View proof and receipts (30 seconds)
hermit task proof <task_id>
hermit task receipts --task-id <task_id>

# 5. Roll back if needed (30 seconds)
hermit task rollback <receipt_id>

You just experienced governed execution: every action was authorized by the kernel, produced a receipt, and left an inspectable proof trail. Continue below for full setup details.

Requirements

  • Python 3.13+
  • uv recommended
  • an LLM provider configuration

Optional:

  • Feishu credentials if you want long-running channel ingress
  • macOS rumps if you want the menu bar companion

Install

The simplest path is:

make install

This initializes the local workspace and installs Hermit for local use.

Manual path:

uv sync --group dev --group typecheck --group docs --group security --group release
uv run hermit init

Configure A Provider

Hermit supports claude, codex, and codex-oauth.

Example using OpenAI:

export HERMIT_PROVIDER=codex
export OPENAI_API_KEY=sk-...
export HERMIT_MODEL=gpt-5.4

You can also store long-lived configuration in ~/.hermit/.env or ~/.hermit/config.toml.

Check the resolved config:

hermit config show
hermit auth status

For deeper configuration details, see configuration.md.

Run Your First Task

Interactive:

hermit chat

One-shot:

hermit run "Summarize the current repository"

Long-running service:

hermit serve --adapter feishu

Inspect The Task Kernel

Hermit is not just a session shell. It already records durable task objects in the local kernel ledger.

List tasks:

hermit task list

Show one task:

hermit task show <task_id>

Inspect task events:

hermit task events <task_id>

Show receipts:

hermit task receipts --task-id <task_id>

Show a proof summary:

hermit task proof <task_id>

Export a proof bundle:

hermit task proof-export <task_id>

Approval And Rollback

When a consequential action is blocked for approval, Hermit records an approval object and exposes it through the task CLI.

Approve:

hermit task approve <approval_id>

Deny:

hermit task deny <approval_id> --reason "not safe"

If a receipt supports rollback:

hermit task rollback <receipt_id>

Rollback is not universal today. Treat it as supported for selected receipt classes, not as a blanket guarantee.

Where State Lives

Common paths under ~/.hermit:

  • .env
  • config.toml
  • kernel/state.db
  • sessions/
  • memory/
  • schedules/
  • plugins/

The kernel database is where Hermit records task, step, approval, receipt, proof, and memory-related state.

How To Read The Docs

Start here:

If you are evaluating Hermit, the most important distinction is this:

  • architecture.md describes what the repo currently implements
  • kernel-spec-v0.1.md describes the target architecture Hermit is converging toward