AgentInbox

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

CLI Reference

AgentInbox uses a local control-plane CLI around agents, sources, subscriptions, inboxes, activation targets, and daemon lifecycle.

Meta Commands

Text-first commands:

agentinbox --help
agentinbox help inbox
agentinbox --version

Resource and control-plane commands return JSON by default.

Daemon

agentinbox daemon start
agentinbox daemon stop
agentinbox daemon status

daemon status returns machine-readable JSON including the daemon PID, transport, and runtime metadata such as the running version, startedAt, command, and nodeVersion when they can be determined locally.

Agent

agentinbox agent register [--agent-id ID] [--force-rebind] [--notify-lease-ms N] [--min-unacked-items N]
agentinbox agent register --agent-id ID --webhook-url URL [--webhook-activation-mode MODE] [--webhook-notify-lease-ms N] [--webhook-min-unacked-items N]
agentinbox agent list
agentinbox agent current
agentinbox agent show <agent_id>
agentinbox agent remove <agent_id>
agentinbox agent target list <agent_id>
agentinbox agent target add webhook <agent_id> --url <url>
agentinbox agent target remove <agent_id> <target_id>

agent register creates or refreshes the current runtime activation target. Terminal-backed runtimes attach a terminal target. In Holon, the CLI can infer agentId from HOLON_AGENT_ID and the webhook URL from HOLON_EXTERNAL_TRIGGER_URL; otherwise pass --webhook-url.

Hosts

agentinbox host add <host_type> <host_key> [--config-json ...]
agentinbox host list
agentinbox host show <host_id>
agentinbox host schema <host_id>

Sources

agentinbox source add <host_id> <stream_kind> <stream_key> [--config-json ...]
agentinbox source list
agentinbox source show <source_id>
agentinbox source update <source_id> [--config-json ...] [--config-ref ...]
agentinbox source remove <source_id>
agentinbox source pause <remote_source_id>
agentinbox source resume <remote_source_id>
agentinbox source schema <source_id>
agentinbox source poll <source_id>
agentinbox source event <source_id> --native-id <id> --event <variant>

source pause and source resume apply only to managed remote sources. Pause stops the managed runtime without deleting its binding or stream checkpoint. Resume goes back through the normal ensure path. Manual source poll does not resume a paused source.

source update replaces persisted config and/or configRef in place while preserving the existing sourceId and attached subscriptions.

Managed remote sources now auto-pause after a grace period once their last subscription is removed. source show <sourceId> includes idleState when a source is idle or was auto-paused for idleness.

Subscriptions

agentinbox subscription add <source_id> [--agent-id <agent_id>] [--filter-json ...] [--tracked-resource-ref <ref>] [--cleanup-policy-json <json>]
agentinbox subscription add <source_id> [--agent-id <agent_id>] --filter-file <path> [--tracked-resource-ref <ref>] [--cleanup-policy-json <json>]
agentinbox subscription add <source_id> [--agent-id <agent_id>] --filter-stdin [--tracked-resource-ref <ref>] [--cleanup-policy-json <json>]
agentinbox subscription add <source_id> [--agent-id <agent_id>] --shortcut <name> [--shortcut-args-json <json>]
agentinbox subscription list [--agent-id <agent_id>] [--source-id <source_id>]
agentinbox subscription show <subscription_id>
agentinbox subscription remove <subscription_id>
agentinbox subscription poll <subscription_id>
agentinbox subscription lag <subscription_id>
agentinbox subscription reset <subscription_id> --start-policy latest

subscription add accepts exactly one of --filter-json, --filter-file, or --filter-stdin. The created subscription response echoes the normalized persisted filter. When any explicit filter input mode is selected (--filter-json, --filter-file, or --filter-stdin), the supplied payload must be a non-empty JSON object.

The control-plane POST /subscriptions API now always returns a { "subscriptions": [...] } envelope. The CLI keeps the historical single subscription JSON shape for non-shortcut calls, but shortcut-driven creates may print the full envelope because one shortcut can expand into multiple subscriptions.

--shortcut asks the source implementation to expand a named subscription shortcut into the standard persisted fields. Use agentinbox source schema <source_id> first to discover whether the source exposes any shortcuts and what arguments they require. When --shortcut is present, do not also pass --filter-*, --tracked-resource-ref, or --cleanup-policy-json; the shortcut owns those fields.

--tracked-resource-ref persists an opaque resource identity such as pr:373 or repo:holon-run/agentinbox:pr:373, depending on the source implementation. --cleanup-policy-json accepts the structured cleanup policy object persisted with the subscription, for example {"mode":"manual"} or {"mode":"on_terminal_or_at","at":"2026-05-01T00:00:00.000Z","gracePeriodSecs":300}.

Inbox

Inbox commands use agentId, not inboxId.

agentinbox inbox list
agentinbox inbox show <agent_id>
agentinbox inbox read [--agent-id <agent_id>]
agentinbox inbox read <entry_id> [--agent-id <agent_id>] [--max-bytes <bytes>] [--no-fetch] [--cursor <token>] [--full]
agentinbox inbox attachment inspect <attachment_ref> [--agent-id <agent_id>]
agentinbox inbox attachment get <attachment_ref> [--agent-id <agent_id>] --output <path>
agentinbox inbox attachment delete <attachment_ref> [--agent-id <agent_id>]
agentinbox inbox send --agent-id <agent_id> --message "..." [--sender <sender>]
agentinbox inbox watch [--agent-id <agent_id>]
agentinbox inbox ack [--agent-id <agent_id>] --through <entry_id>
agentinbox inbox ack [--agent-id <agent_id>] --item <entry_id>
agentinbox inbox ack [--agent-id <agent_id>] --all
agentinbox inbox compact <agent_id>

Without an entry ID, inbox read retains its existing list behavior. With an email entry ID, it returns a bounded normalized text page. Reading is local first; omit --no-fetch to allow UXC to retrieve missing content. If body.hasMore is true, pass the returned body.nextCursor with the same entry ID to continue the fixed snapshot. --full is accepted for compatibility in single-entry mode but never exposes the internal UXC message_ref.

The result reports complete, partial, or unverified body completeness separately from output pagination. It includes only safe attachment display metadata. attachment inspect reads that metadata without downloading. For sources configured with attachmentPolicy.mode=store_reference, attachment get performs bounded on-demand materialization and writes the binary response on the client side. The output path is created exclusively and is never sent to the daemon. attachment delete is ownership-checked and idempotently tombstones the reference; managed bytes are removed only after no live attachment references share the content-addressed object. Deleted, quarantined, and rejected attachments cannot be read.

Timers

agentinbox timer add --agent-id <agent_id> --at 2026-04-15T08:00:00+08:00 --message "..."
agentinbox timer add --agent-id <agent_id> --every 24h --message "..."
agentinbox timer add --agent-id <agent_id> --cron "0 8 * * *" --timezone Asia/Shanghai --message "..."
agentinbox timer list [--agent-id <agent_id>]
agentinbox timer pause <schedule_id>
agentinbox timer resume <schedule_id>
agentinbox timer remove <schedule_id>

Maintenance

agentinbox gc
agentinbox status

HTTP API

See HTTP API for the stable control-plane endpoints.