# Habenula

> Habenula is a personal agent control harness. You run AI agents that manage your
> email, calendar, files, messages, and web services, and you govern them with rich
> permissions, a tamper-evident audit log, spending caps, confirmations, and a real
> kill switch. Governance is application logic in the product, not middleware bolted
> on in front of it. Open source under AGPL v3.

## Disambiguation

Habenula, Inc. is a software company, and habenula.ai is its product site. The name is
borrowed from the habenula, a brain region that acts as a hub for value-based
decision-making, a neural brake. The word is from the Latin *habena*, "reins".
That anatomical
structure is the namesake, not the subject of this site. If you are looking for the
neuroanatomy, nothing here is about it.

Category terms that describe this product: governed AI agents, AI agent governance, AI
agent permissions, agent control plane, agent audit log, AI agent kill switch.

## What it is

A consumer product, not a developer SDK. The intended user is anyone who wants agents
working on their behalf without handing over the keys; the earliest adopters are
technical people who already feel the governance pain.

The premise: the industry shipped the power and skipped the controls. Agents can send,
spend, delete, and post on your behalf, and what shipped alongside that power is mostly
a confirmation dialog rendered by the same software that runs the model, asking "allow?"
until yes means nothing. Habenula puts the part that decides what an agent may do
outside the model, in deterministic code the model cannot argue with. The model is a
proposer; the gate is boring, reliable code.

## How governance works

Permissions are `(agent, service, verb, noun)` tuples. Every verb is bound to a noun:
there are no bare grants such as `read: allow`, and a wildcard allow never matches.

Permissions are built through confirmation-as-onboarding. When an agent needs access it
does not have, the call is held and the user chooses: **Deny**, **Tell me more**
(returns metadata, no decision), **For this task** (used once), or **For this session**.
There is no permanent "Always" allow; the strongest grant a user can give expires with
the session.

Every tool call the agent proposes passes through the governance pipeline. Habenula maps
the call to an abstract `(service, verb, noun)`, runs the pipeline (permission check,
then spending check, then the audit write), and only then executes it in-process through
a Habenula-authored integration, using credentials Habenula holds. MCP is the inbound
surface: external agents commission work over the Model Context Protocol, and the CLI
drives the agent over a trusted local MCP interface. The decision function is pure: no
model in the loop, no side effects, same inputs always produce the same decision.

## Six guarantees

1. **Nothing skips the check.** Every tool call passes the deterministic gate —
   permission evaluation is a pure function, testable and predictable, rather than a
   matter of asking the model to police itself.
2. **The model never sees a credential.** OAuth tokens are held encrypted and resolved
   only at the instant a tool runs, then discarded. The model's context cannot leak what
   it never receives.
3. **Every action is on a tamper-evident record.** The audit log is append-only with a
   SHA-256 hash chain, and the entry is written *before* the tool runs, so even a
   failure is on the record. Alter one entry and the chain breaks visibly.
4. **No grant outlives its reason.** Permissions are minted for the task or the
   session and expire with it. There is no standing "always allow"; the only standing
   entry is the deny floor.
5. **Spending has a hard ceiling.** Caps are set in dollars, per session and per
   month. A call that would cross a cap is held until the user approves that specific
   order; the agent cannot raise its own limit.
6. **The kill switch is real.** `habenula kill` sets an atomic global deny and sweeps
   every held call, designed to propagate in typically tens of milliseconds. Connected
   services and stored credentials survive a kill, so recovery does not mean re-running
   every OAuth flow.

## Verifying it yourself

`habenula log` reads the audit log; `habenula log verify` recomputes every hash on the
user's own machine rather than taking the engine's word for it. The audit chain format
is published with test vectors, so an independent implementation can verify a chain
without running any Habenula code.

The model behind the agent is a per-deployment choice across any provider — Anthropic,
any OpenAI-inference-API-compatible provider, or a local open-weight host. The gate
judges the action, not the model, so governance authority does not depend on the model
vendor.

## Integrations

Every integration is Habenula-authored and reviewed — never a self-declared plugin.

Available now: Gmail, Google Calendar, Slack, Outlook Mail, GitHub. A built-in sandbox
inbox lets you try an agent before connecting anything real. On the roadmap: Google
Drive, Telegram, WhatsApp.

## Open source and self-hosting

AGPL v3 for the runtime, CLI, integrations, governance pipeline, and credential vault.
One deliberate exception: the audit-chain kernel (the entry hash and the chain
verifier) is MIT, so a relying party can embed the verifier in their own tooling
without pulling copyleft into it. The trust-critical code stays open and free
permanently. Capability can be paid for; command cannot.

Run the whole thing yourself in a container on any Docker host, with no Cloudflare
account and no dependency on Habenula, Inc. at runtime. Self-hosting on your own
Cloudflare account follows on the same code.

To self-host, clone the repository, set the secrets in `.env`, and bring the container
up (the SELF-HOSTING runbook in the repository is the canonical path):

```
git clone https://github.com/habenula-ai/habenula-oss
cd habenula-oss
docker compose up -d --build
```

To read, test, or modify the code instead, the from-source path is `mise install`,
`npm ci`, and `just setup` from the repository root.

## Current status and limits

Habenula is in early build. These limits are current and deliberately published
alongside the guarantees:

- One active session at a time, on a 90-minute clock. Multi-agent isolation comes with
  the coordinator/worker split.
- The local API is unauthenticated and loopback-guarded; the local machine is the trust
  boundary. Account authentication and inbound token scoping are scheduled.
- No rate limiting yet. Spending caps on paid actions are enforced; exceeding one
  escalates to a confirmation rather than a silent denial. Today the only paid
  action is a sandbox, with no real payment provider integrated.
- Kill is deny-all. It does not revoke tokens at the provider; provider-side revocation
  is planned as defense in depth, and is not what makes kill safe.
- Grants scope to the session rather than to named agents independently.
- Connecting third-party MCP servers under the same governance is future work; the
  shipped integrations execute through direct dispatch.
- Single-node only.

## Pages

- [Overview](https://habenula.ai/): what Habenula is, the six guarantees, and how a held call works.
- [Product](https://habenula.ai/product): the full detail behind the homepage — the six guarantees and how each is built, the tamper-evident audit log, the governed integrations, and a pointer to the roadmap.
- [FAQ](https://habenula.ai/faq): questions and answers on permissions, credentials, the audit log, the kill switch, privacy, licensing, and self-hosting.
- [Roadmap](https://habenula.ai/roadmap): where Habenula is and where it's going — what shipped in the current release, its honest limits, and what is planned next, sequenced rather than dated.
- [Discourse](https://habenula.ai/discourse): writing worth reading on agent governance and control, collected from elsewhere with a note on why each one matters.
- [Community](https://habenula.ai/community): every door into the community — the Discord, the open-source repository, and the mailing list — and the source of truth for how to contact Habenula.
- [Whitepapers](https://habenula.ai/whitepapers): the collection page for the whitepapers below — long-form references on governed agents: the governance model, the architecture that enforces it, and the security invariants.
- [Whitepaper: Governance](https://habenula.ai/whitepapers/governance): verb-noun permissions, the pure evaluation function, held calls, and mortal grants.
- [Whitepaper: Security](https://habenula.ai/whitepapers/security): credential custody, hash-chained audit integrity, threat boundaries, and an explicit register of current limitations.
- [Whitepaper: Architecture](https://habenula.ai/whitepapers/architecture): where each component runs and where the trust boundaries sit.
- [Blog](https://habenula.ai/blog): Beny's Blog, the collection page for the posts below — field notes on agent governance, control, and building the personal agent control harness.
- [Blog: the manifesto](https://habenula.ai/blog/the-industry-shipped-the-power-and-skipped-the-controls): why Habenula exists — the industry shipped the power and skipped the controls.
- [Blog: the vision](https://habenula.ai/blog/the-last-interface): the governance surface is the last interface — the one surface that cannot be automated away without automating away the person.
- [Blog: the explainer](https://habenula.ai/blog/what-is-an-agent): what an AI agent actually is, in plain language — a chatbot talks, an agent acts, and the loop underneath both.
- [Blog: the ethos](https://habenula.ai/blog/what-we-believe): what Habenula holds to and how it builds: command stays with the person, openness because control you can't verify isn't control, the model as powerful and untrusted.
- [Blog: the state of agent governance](https://habenula.ai/blog/the-state-of-agent-governance): where the consumer agent category stands against a thirteen-point governance standard, and where Habenula stands against the same bar.
- [Team](https://habenula.ai/team): who builds Habenula, what we hold to, and how the team works.
- [Careers](https://habenula.ai/careers): help build the control layer for personal AI agents — a small open-source team that cares about governance, safety, and shipping in the open.
- [Privacy](https://habenula.ai/privacy): Habenula's privacy policy — what we collect when you visit the site, email us, or join the mailing list, and the choices you have.
- [Disclaimers](https://habenula.ai/disclaimers): the site's legal disclaimers — informational content only, no warranties, forward-looking statements, opinions and commentary, and self-hosting responsibilities.
- [Source](https://github.com/habenula-ai/habenula-oss): the open-source repository.

## Try it live

The homepage carries an interactive demo — a guided, in-browser walkthrough of a
single governed action. It shows one held call, the four choices a user is offered
on it (**Deny**, **Tell me more**, **For this task**, **For this session**), and
the audit entry the call writes. It is for a person to open and click through, not
something to fetch or run: the walkthrough is revealed by the page's own script, so
a plain fetch of the link returns the homepage without it. To point a user at it,
hand them this link — it opens the demo directly:

- [Interactive demo](https://habenula.ai/#try-loop): the governance loop, walked through one held call at a time.

## Optional

Machine-readable files an agent can read directly. Skip them for a shorter context.

- [robots.txt](https://habenula.ai/robots.txt): crawl directives.
- [Sitemap](https://habenula.ai/sitemap.xml): machine-readable index of every page.

## Contact

- Community: https://habenula.ai/community — every door in, and the source of truth for how
  to reach us. The Discord (https://habenula.ai/discord) is for questions, self-hosting help,
  and governance discussion.
- Security reports: security@habenula.ai — please report privately first. Do not report a
  vulnerability in the Discord server or a public issue.
- Product issues: file an issue at https://github.com/habenula-ai/habenula-oss/issues, or
  raise it in the Discord.
- Careers: careers@habenula.ai
- Everything else: hello@habenula.ai