Capabilities and Approvals — Nebo Developer Documentation

A capability names a kind of system, such as mail or a ledger, and the operations on it. Employee packages declare the capabilities they need; plugins declare the ones they provide; the owner connects the two at hire. Approvals are attached to operations, so the same rules hold whichever system fills the capability.

The model

A capability is a typed interface, never a product. mail has the operations mail.inbox.read, mail.inbox.search and mail.message.send.
An employee package lists the capabilities its role needs in requires.interfaces.
A plugin provides a capability by binding its operations to its own commands in interfaceBindings.
A connection is the plugin the owner connected for that capability. A watch trigger that names a capability runs on it.

Declare what a role needs

{
  "requires": { "interfaces": ["mail", "ledger"] },
  "ceiling": { "ledger.bill.create": "approval" }
}

Name capabilities, not plugins. An employee package that requires ledger works for every company, whichever accounting system it uses. Use requires.plugins only when a role truly depends on one specific plugin.

Provide a capability

"interfaceBindings": {
  "mail.inbox.read": "messages list --folder inbox",
  "mail.inbox.search": "messages search --query {query}",
  "mail.message.send": "messages send"
}

A plugin that binds any mail.* operation provides mail. Each binding also becomes a typed tool for employees, such as mail_message_send. The template syntax is on the plugin.json reference.

When a workflow watches a capability, Nebo picks the installed plugin that provides it, preferring one this employee has an account on, then alphabetical order. With none, the workflow is kept, marked degraded, and the owner is told what to connect.

The catalog

Nebo ships a catalog of capabilities and their operations, including ledger, mail, sms, telephony, calendar, drive, helpdesk, kb, deals, esign, timebilling, projects, cms, social, ads, reviews, email-marketing, repo, ci, deploy, monitoring and incidents. The catalog is shared vocabulary, not a fence. Use its terms wherever one fits so that employees and plugins from different publishers meet; a new term is a question of convention, not an error.

Each operation carries one of three marks.

Mark	Meaning
Ungated	A read, or a protective act that is reversible and loses its value if it waits, such as pause, cancel or roll back. Runs without asking.
Gated	Moves money, contacts someone outside the company, or cannot be undone. Nebo asks before the bound tool runs.
Critical	Money movement, contract formation, the company’s own records, or standing authority to act unattended. Always gated; the owner grants each one per employee and per operation, and no employee-wide setting loosens it.

Consent at hire

When an owner hires an employee, Nebo reads its needs from the package: the capabilities in requires.interfaces, the plugins in requires.plugins, and each capability or plugin a watch trigger names. The owner sees one sentence that states those needs. Hiring grants them to that employee as standing permissions. Gated operations remain approval items.

Installing a plugin, an MCP server, an app or a skill is itself the grant to use it; those are not switched on one by one. Nebo's own built-in abilities are grouped as chat, file, shell, web, contacts, desktop, media and system.

Ceilings and laws

Declared in	Effect
`ceiling` in `agent.json`	The listed operations always ask the owner for this employee. The only value is `"approval"`.
A law’s `ceiling` in the company layer	The listed operations are blocked for every employee.
A company law with `reserved_to: owner`	The listed operations need the owner’s own approval, and that approval can never be granted to an employee.

Permission modes

Each employee has a permission mode. It decides the calls that no rule settles, and the owner can override it for a single run.

Mode	Behavior
`automatic`	The default. The employee acts inside its job and asks only for gated operations and the owner’s ask rules.
`ask`	Every call that changes something asks, unless an allow rule covers it.
`plan`	Read and plan only. A call that changes something does not run.
`full_access`	Nothing asks. Deny rules and hard limits still hold.

Nebo checks every action in the same order: hard limits first, then ceilings and laws, then the owner's rules, then the mode. Hard limits, such as protecting credentials from leaking, are never lifted, not even in full_access.