AgentInbox

Documentation for AgentInbox, the local event subscription and delivery service for agents.

Getting Started

This guide shows the shortest path from install to a working local agent session.

If you are using Codex, Claude Code, or Holon, start with Onboarding With The AgentInbox Skill. That is the preferred first-run path.

Prerequisites

Install AgentInbox globally:

npm install -g @holon-run/agentinbox

Or run it directly:

npx @holon-run/agentinbox --help

If you are using Codex, Claude Code, or Holon, you can also install the bundled AgentInbox skill first:

npx skills add holon-run/agentinbox --skill agentinbox -a codex -a claude-code -a holon

Daemon

AgentInbox runs as a local daemon and stores state in ~/.agentinbox by default.

Start it explicitly:

agentinbox daemon start

Inspect it:

agentinbox daemon status

Most CLI commands can auto-start the daemon if it is not already running.

Default paths:

Register The Current Runtime

Register the current runtime/session as an agent:

agentinbox agent register
agentinbox agent register --agent-id agent-alpha
agentinbox agent register --agent-id agent-alpha --webhook-url <external-trigger-url>
agentinbox agent current

This detects the current runtime context, assigns or restores an agentId, creates the agent inbox, and attaches the appropriate activation target. For terminal-backed runtimes this is a terminal target. In Holon, the no-arg form uses HOLON_AGENT_ID and HOLON_EXTERNAL_TRIGGER_URL when present; otherwise pass --webhook-url explicitly.

If you already use gh for GitHub authentication, import it into uxc before adding GitHub-backed sources:

uxc auth credential import github --from gh

Local Event Flow

The shortest end-to-end flow is a local source:

agentinbox host add local_event local-demo
agentinbox source add <host_id> events local-demo
agentinbox subscription add <source_id>
agentinbox subscription add <source_id> --agent-id <agent_id>
agentinbox source event <source_id> \
  --native-id demo-1 \
  --event local.demo \
  --metadata-json '{"channel":"engineering"}' \
  --payload-json '{"text":"hello from a local producer"}'
agentinbox inbox read
agentinbox inbox read --agent-id <agent_id>

If you need to change an existing source definition without replacing its subscriptions, update it in place:

agentinbox source update <source_id> --config-json '{"channel":"infra"}'
agentinbox source update <source_id> --clear-config-ref

GitHub Repo CI Example

agentinbox host add github uxcAuth:github-default \
  --config-json '{"uxcAuth":"github-default"}'
agentinbox source add <host_id> ci_runs holon-run/agentinbox \
  --config-json '{"owner":"holon-run","repo":"agentinbox","pollIntervalSecs":30}'
agentinbox subscription add <source_id> --agent-id <agent_id> \
  --filter-json '{"metadata":{"status":"completed","conclusion":"failure","headBranch":"main"}}'
agentinbox source poll <source_id>

For builtin GitHub streams such as repo_events, inspect the resolved schema first if you want source-defined subscription shortcuts:

agentinbox source schema <source_id>
agentinbox subscription add <source_id> --agent-id <agent_id> \
  --shortcut pr \
  --shortcut-args-json '{"number":87}'

The shortcut path is preferred when the source exposes it because the source can fill in the matching filter, tracked resource ref, and cleanup policy as one consistent bundle.

For larger filters with nested JSON or JEXL, prefer a file or stdin over shell quoting:

agentinbox subscription add <source_id> --filter-file ./filter.json
cat filter.json | agentinbox subscription add <source_id> --filter-stdin

If a source already exists and you only need to change its config, update it in place instead of removing and recreating it:

agentinbox source update <source_id> \
  --config-json '{"owner":"holon-run","repo":"agentinbox","uxcAuth":"github-default","pollIntervalSecs":60}'
agentinbox source update <source_id> --clear-config-ref

For remote-backed sources, use lifecycle commands instead of delete/recreate when you just want to stop delivery temporarily. These commands do not apply to local_event sources:

agentinbox source pause <remote_source_id>
agentinbox source poll <remote_source_id>   # returns a paused note, does not resume
agentinbox source resume <remote_source_id>

Terminal Support

Upgrade Expectations

AgentInbox is on the stable v1 release line.